โครงสร้างของเอกสาร Google เอกสาร

หากต้องการใช้ Google เอกสาร API อย่างมีประสิทธิภาพ คุณต้องเข้าใจสถาปัตยกรรมของเอกสาร Google เอกสารและองค์ประกอบที่ประกอบกันเป็นเอกสาร รวมถึงความสัมพันธ์ระหว่างองค์ประกอบเหล่านั้น หน้านี้แสดงภาพรวมโดยละเอียดของหัวข้อต่อไปนี้

  • โมเดลแนวคิดขององค์ประกอบเอกสาร
  • วิธีที่ Docs API แสดงองค์ประกอบเหล่านี้
  • พร็อพเพอร์ตี้การจัดรูปแบบขององค์ประกอบ

องค์ประกอบระดับบนสุด

องค์ประกอบคอนเทนเนอร์ด้านนอกสุดใน Google เอกสารคือเอกสาร นี่เป็นหน่วยที่สามารถบันทึกใน Google ไดรฟ์ แชร์กับผู้ใช้รายอื่น และอัปเดตด้วยข้อความและรูปภาพ

องค์ประกอบระดับบนสุดของทรัพยากร documents ประกอบด้วย Tab, SuggestionsViewMode และแอตทริบิวต์อื่นๆ ดังนี้

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

แท็บ

เอกสารเดียวอาจมีแท็บหลายแท็บซึ่งมีเนื้อหาระดับข้อความแตกต่างกัน พร็อพเพอร์ตี้ tabs ของเอกสารคืออนุกรมออบเจ็กต์ Tab Tab ประกอบด้วยฟิลด์ต่อไปนี้

  • TabProperties: มีแอตทริบิวต์ของแท็บ เช่น รหัส ชื่อ และดัชนี
  • childTabs: แสดงแท็บย่อยของแท็บ (แท็บที่ฝังอยู่ใต้แท็บนั้นโดยตรง)
  • DocumentTab: แสดงเนื้อหาข้อความของแท็บ
โครงสร้างของแท็บเอกสาร
รูปที่ 1 โครงสร้างของแท็บเอกสาร

ส่วนต่อๆ ไปจะแสดงภาพรวมคร่าวๆ ของลําดับชั้นแท็บเอกสาร และการนําเสนอ JSON ของแท็บยังมีรายละเอียดเพิ่มเติมด้วย ดูข้อมูลเพิ่มเติมเกี่ยวกับฟีเจอร์แท็บได้ที่ใช้แท็บ

หากต้องการจัดการฟีเจอร์แท็บเอกสารส่วนกลางนอกเนื้อหา Body คุณควรใช้เทมเพลตเอกสารอย่างน้อย 1 รายการ ซึ่งจะใช้เป็นพื้นฐานในการสร้างเอกสารใหม่แบบเป็นโปรแกรมได้ ดูข้อมูลเพิ่มเติมได้ที่หัวข้อผสานข้อความลงในเอกสาร

เนื้อหาส่วนเนื้อหา

โดยปกติแล้ว Body จะมีเนื้อหาทั้งหมดของแท็บเอกสาร รายการส่วนใหญ่ที่คุณสามารถใช้หรืออาจต้องการใช้แบบเป็นโปรแกรมคือองค์ประกอบภายในเนื้อหา Body ดังนี้

โครงสร้างของเนื้อหา
รูปที่ 2 โครงสร้างของเนื้อหา

องค์ประกอบโครงสร้าง

StructuralElement อธิบายเนื้อหาที่ให้โครงสร้างแก่เอกสาร เนื้อหา Body คือลำดับออบเจ็กต์ StructuralElement องค์ประกอบเนื้อหาจะปรับเปลี่ยนออบเจ็กต์ StructuralElement แต่ละรายการในแบบของคุณ ดังที่แสดงในแผนภาพต่อไปนี้

องค์ประกอบโครงสร้าง
รูปที่ 3 องค์ประกอบโครงสร้าง

องค์ประกอบโครงสร้างและออบเจ็กต์เนื้อหามีองค์ประกอบภาพทั้งหมดในเอกสาร ซึ่งรวมถึงข้อความ รูปภาพในบรรทัด และการจัดรูปแบบ

โครงสร้างย่อหน้า

Paragraph คือ StructuralElement ที่แสดงถึงย่อหน้า มีเนื้อหาที่หลากหลายซึ่งลงท้ายด้วยอักขระขึ้นบรรทัดใหม่ ซึ่งประกอบด้วยออบเจ็กต์ต่อไปนี้

  • ParagraphElement: อธิบายเนื้อหาภายในย่อหน้า
  • ParagraphStyle: องค์ประกอบที่ไม่บังคับซึ่งตั้งค่าพร็อพเพอร์ตี้สไตล์สำหรับย่อหน้าอย่างชัดเจน
  • Bullet: หากย่อหน้าเป็นส่วนหนึ่งของรายการ องค์ประกอบที่ไม่บังคับซึ่งระบุข้อกำหนดของสัญลักษณ์หัวข้อ

ParagraphElement ทำงานคล้ายกับ StructuralElement ชุดประเภทองค์ประกอบเนื้อหา (เช่น ColumnBreak และ Equation) จะปรับเปลี่ยนParagraphElementของตนเองในแบบของคุณ ดังที่แสดงในแผนภาพต่อไปนี้

โครงสร้างขององค์ประกอบย่อหน้า
รูปที่ 4 โครงสร้างขององค์ประกอบย่อหน้า

ดูตัวอย่างโครงสร้างเอกสารที่สมบูรณ์ได้ที่ documentตัวอย่างในรูปแบบ JSON ในเอาต์พุต คุณจะเห็นองค์ประกอบโครงสร้างและเนื้อหาหลักๆ หลายรายการ รวมถึงการใช้ดัชนีเริ่มต้นและดัชนีสิ้นสุดตามที่อธิบายไว้ในส่วนถัดไป

ข้อความ

TextRun คือ ParagraphElement ที่แสดงสตริงข้อความต่อเนื่องที่มีรูปแบบข้อความเหมือนกันทั้งหมด ย่อหน้าอาจมีข้อความหลายบรรทัด แต่ข้อความบรรทัดหนึ่งๆ จะต้องไม่ข้ามขอบเขตของย่อหน้า ระบบจะแบ่งเนื้อหาหลังอักขระขึ้นบรรทัดใหม่เพื่อสร้างข้อความที่แยกกัน ตัวอย่างเช่น ลองพิจารณาเอกสารขนาดเล็กๆ ดังต่อไปนี้

เอกสารขนาดเล็กที่มีย่อหน้าและรายการสัญลักษณ์หัวข้อย่อย
รูปที่ 5 เอกสารขนาดเล็ก

แผนภาพต่อไปนี้แสดงวิธีที่คุณอาจแสดงลำดับย่อหน้าในเอกสารก่อนหน้าเป็นภาพ โดยแต่ละย่อหน้าจะมีการตั้งค่า TextRun และ Bullet ของตนเอง (ไม่บังคับ)

โครงสร้างของข้อความ
รูปที่ 6 โครงสร้างของข้อความ

AutoText

AutoText คือ ParagraphElement ที่แสดงตำแหน่งในข้อความที่จะแทนที่ด้วยเนื้อหาแบบไดนามิกซึ่งอาจเปลี่ยนแปลงได้เมื่อเวลาผ่านไป ในเอกสาร จะใช้เครื่องหมายนี้สำหรับหมายเลขหน้า

ดัชนีเริ่มต้นและสิ้นสุด

เมื่อคุณอัปเดตเนื้อหาของแท็บในเอกสาร การอัปเดตแต่ละครั้งจะเกิดขึ้นที่ตำแหน่งหรือช่วงภายในเอกสาร ตำแหน่งและช่วงเหล่านี้จะระบุโดยใช้ดัชนี ซึ่งแสดงถึงออฟเซตภายในกลุ่มเอกสารที่มี ส่วนคือเนื้อหา ส่วนหัว ส่วนท้าย หรือเชิงอรรถที่มีองค์ประกอบโครงสร้างหรือเนื้อหา ดัชนีขององค์ประกอบภายในกลุ่มจะสัมพันธ์กับจุดเริ่มต้นของกลุ่มนั้น

องค์ประกอบส่วนใหญ่ภายในเนื้อหาของข้อความมีพร็อพเพอร์ตี้ startIndex และ endIndex ที่อิงตาม 0 ซึ่งระบุออฟเซตของจุดเริ่มต้นและจุดสิ้นสุดขององค์ประกอบ โดยสัมพันธ์กับจุดเริ่มต้นของส่วนที่ล้อมรอบ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีสั่งซื้อการเรียก API ของเอกสารแบบเป็นกลุ่มได้ที่การอัปเดตแบบกลุ่ม

ดัชนีจะวัดเป็นหน่วยโค้ด UTF-16 ซึ่งหมายความว่าคู่ตัวแทนจะใช้ดัชนี 2 รายการ เช่น อีโมจิ "ใบหน้ายิ้ม" 😄 จะแสดงเป็น \uD83D\uDE00 และใช้ดัชนี 2 รายการ

สำหรับองค์ประกอบภายในเนื้อหาเอกสาร ดัชนีจะแสดงการเลื่อนจากจุดเริ่มต้นของเนื้อหาเนื้อหา ซึ่งเป็นองค์ประกอบ "รูท"

ประเภท "การปรับให้เหมาะกับผู้ใช้" สำหรับองค์ประกอบโครงสร้างอย่าง SectionBreak, TableOfContents, Table และ Paragraph จะไม่มีดัชนีเหล่านี้เนื่องจาก StructuralElement ที่ล้อมรอบมีช่องเหล่านี้ เช่นเดียวกับประเภทการปรับให้เหมาะกับผู้ใช้ที่อยู่ใน ParagraphElement เช่น TextRun, AutoText และ PageBreak

เข้าถึงองค์ประกอบ

องค์ประกอบหลายอย่างแก้ไขได้ด้วยเมธอด documents.batchUpdate เช่น การใช้ InsertTextRequest จะช่วยให้คุณเปลี่ยนเนื้อหาขององค์ประกอบที่มีข้อความได้ ในทํานองเดียวกัน คุณสามารถใช้ UpdateTextStyleRequest เพื่อใช้การจัดรูปแบบกับช่วงข้อความที่มีอยู่ในองค์ประกอบอย่างน้อย 1 รายการ

หากต้องการอ่านองค์ประกอบของเอกสาร ให้ใช้เมธอด documents.get เพื่อรับการดัมพ์ JSON ของเอกสารฉบับสมบูรณ์ จากนั้นคุณสามารถแยกวิเคราะห์ JSON ที่ได้เพื่อค้นหาค่าขององค์ประกอบแต่ละรายการ ดูข้อมูลเพิ่มเติมได้ที่แสดงผลเนื้อหาเอกสารเป็น JSON

การแยกวิเคราะห์เนื้อหาจะเป็นประโยชน์สำหรับกรณีการใช้งานที่หลากหลาย ตัวอย่างเช่น แอปพลิเคชันการจัดทําแคตตาล็อกเอกสารที่แสดงรายการเอกสารที่พบ แอปนี้สามารถดึงข้อมูลชื่อ รหัสการแก้ไข และหมายเลขหน้าเริ่มต้นของแท็บเอกสารได้ ดังที่แสดงในแผนภาพต่อไปนี้

โครงสร้างของแคตตาล็อกเอกสาร
รูปที่ 7 โครงสร้างของแคตตาล็อกเอกสาร

เนื่องจากไม่มีวิธีการอ่านการตั้งค่าเหล่านี้อย่างชัดเจน แอปของคุณจึงต้องรับทั้งเอกสารแล้วแยกวิเคราะห์ JSON เพื่อดึงค่าเหล่านี้

การสืบทอดพร็อพเพอร์ตี้

StructuralElement สามารถรับค่าพร็อพเพอร์ตี้จากออบเจ็กต์หลัก พร็อพเพอร์ตี้ของออบเจ็กต์ ซึ่งรวมถึงพร็อพเพอร์ตี้ที่ออบเจ็กต์กำหนดและรับค่ามา จะกำหนดลักษณะที่ปรากฏของออบเจ็กต์ในขั้นสุดท้าย

การจัดรูปแบบอักขระข้อความจะกำหนดวิธีแสดงผลข้อความในเอกสาร เช่น ตัวหนา ตัวเอียง และขีดเส้นใต้ การจัดรูปแบบที่คุณใช้จะลบล้างการจัดรูปแบบเริ่มต้นที่รับค่ามาจากTextStyle ของย่อหน้าที่อยู่เบื้องล่าง ในทางกลับกัน อักขระที่คุณไม่ได้กำหนดการจัดรูปแบบจะยังคงรับค่าจากสไตล์ของย่อหน้า

การจัดรูปแบบย่อหน้าจะกำหนดวิธีแสดงผลบล็อกข้อความในเอกสาร เช่น การจัดตำแหน่ง เส้นขอบ และการเยื้อง การจัดรูปแบบที่คุณใช้จะลบล้างการจัดรูปแบบเริ่มต้นที่รับค่ามาจาก ParagraphStyle พื้นฐาน ในทางกลับกัน ฟีเจอร์การจัดรูปแบบที่คุณไม่ได้ตั้งค่าจะยังคงรับค่าจากสไตล์ย่อหน้าต่อไป