โครงสร้างของเอกสาร 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 ของตัวเองในแบบของคุณ ดังที่แสดงในไดอะแกรมต่อไปนี้

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

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

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

แผนภาพต่อไปนี้แสดงวิธีที่คุณอาจเห็นภาพลำดับย่อหน้า ในเอกสารก่อนหน้า ซึ่งแต่ละย่อหน้ามี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

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

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

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

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

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

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

หัวข้อที่เกี่ยวข้อง

• คำขอและการตอบกลับ
• กฎและลักษณะการทำงานของการแก้ไขโครงสร้าง