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

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

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

โมเดลแนวคิดขององค์ประกอบเอกสาร
Docs API แสดงถึงองค์ประกอบเหล่านี้อย่างไร
คุณสมบัติการจัดรูปแบบขององค์ประกอบ

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

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

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

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

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

เนื้อความ

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

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

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

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

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

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

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

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

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

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

ข้อความทำงาน

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

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

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

**รูปที่ 5** โครงสร้างของการเรียกใช้ข้อความ

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

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

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

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

การรับช่วงพร็อพเพอร์ตี้ต่อ

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

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

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