หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

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

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

แท็บ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ข้อความ

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

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

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

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 พื้นฐาน ในทางกลับกัน ฟีเจอร์การจัดรูปแบบที่คุณไม่ได้ตั้งค่าจะยังคงรับค่าจากสไตล์ย่อหน้าต่อไป