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

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

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

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

องค์ประกอบคอนเทนเนอร์ด้านนอกสุดใน Google เอกสารคือ document ซึ่งเป็นหน่วยที่สามารถบันทึกไว้ใน 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 ของตัวเองให้เหมาะกับผู้ใช้ ดังที่แสดงในแผนภาพต่อไปนี้

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

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

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

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

AutoText

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

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

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

องค์ประกอบส่วนใหญ่ภายในเนื้อหาร่างกายจะมีพร็อพเพอร์ตี้ startIndex และ 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

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

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

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

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

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

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

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

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