ในการใช้ 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
ที่สำคัญ
ในทางกลับกัน ฟีเจอร์การจัดรูปแบบใดๆ ที่ไม่ได้ตั้งค่าจะยังคงรับค่ามาจากรูปแบบย่อหน้า