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

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

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

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

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

องค์ประกอบระดับบนสุดของ documents ซึ่งรวมถึง Tab SuggestionsViewMode และแอตทริบิวต์อื่นๆ:

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

แท็บ

เอกสาร 1 รายการจะมีแท็บได้หลายแท็บ มีเนื้อหาระดับข้อความแตกต่างกัน พร็อพเพอร์ตี้ tabs ของเอกสารคือ ลำดับของ Tab ออบเจ็กต์ Tab ประกอบด้วยช่องข้อมูลต่อไปนี้

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

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

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

เนื้อหาในเนื้อความ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

AutoText

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

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

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

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

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

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