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

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

หากต้องการใช้ Google Docs 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เนื้อหา

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

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

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

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

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

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

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

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

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

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

การเรียกใช้ข้อความ

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

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

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

AutoText

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

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

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

องค์ประกอบส่วนใหญ่ภายในเนื้อหาของเนื้อความมีพร็อพเพอร์ตี้ startIndex และ endIndex ที่อิงตาม 0 ระบุออฟเซ็ตของจุดเริ่มต้นและจุดสิ้นสุดขององค์ประกอบ เทียบกับจุดเริ่มต้นของส่วนที่ล้อมรอบ ดูข้อมูลเพิ่มเติม เกี่ยวกับวิธีจัดลำดับการเรียก Docs 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พื้นฐาน ในทางกลับกัน ฟีเจอร์การจัดรูปแบบใดก็ตามที่คุณไม่ได้ตั้งค่าจะยังคงรับค่ามาจาก รูปแบบย่อหน้า