หากต้องการใช้ 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
ของตนเองในแบบของคุณ ดังที่แสดงในแผนภาพต่อไปนี้
ดูตัวอย่างโครงสร้างเอกสารที่สมบูรณ์ได้ที่ documentตัวอย่างในรูปแบบ JSON ในเอาต์พุต คุณจะเห็นองค์ประกอบโครงสร้างและเนื้อหาหลักๆ หลายรายการ รวมถึงการใช้ดัชนีเริ่มต้นและดัชนีสิ้นสุดตามที่อธิบายไว้ในส่วนถัดไป
ข้อความ
TextRun
คือ ParagraphElement
ที่แสดงสตริงข้อความต่อเนื่องที่มีรูปแบบข้อความเหมือนกันทั้งหมด ย่อหน้าอาจมีข้อความหลายบรรทัด แต่ข้อความบรรทัดหนึ่งๆ จะต้องไม่ข้ามขอบเขตของย่อหน้า ระบบจะแบ่งเนื้อหาหลังอักขระขึ้นบรรทัดใหม่เพื่อสร้างข้อความที่แยกกัน ตัวอย่างเช่น ลองพิจารณาเอกสารขนาดเล็กๆ ดังต่อไปนี้
แผนภาพต่อไปนี้แสดงวิธีที่คุณอาจแสดงลำดับย่อหน้าในเอกสารก่อนหน้าเป็นภาพ โดยแต่ละย่อหน้าจะมีการตั้งค่า TextRun
และ Bullet
ของตนเอง (ไม่บังคับ)
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
การแยกวิเคราะห์เนื้อหาจะเป็นประโยชน์สำหรับกรณีการใช้งานที่หลากหลาย ตัวอย่างเช่น แอปพลิเคชันการจัดทําแคตตาล็อกเอกสารที่แสดงรายการเอกสารที่พบ แอปนี้สามารถดึงข้อมูลชื่อ รหัสการแก้ไข และหมายเลขหน้าเริ่มต้นของแท็บเอกสารได้ ดังที่แสดงในแผนภาพต่อไปนี้
เนื่องจากไม่มีวิธีการอ่านการตั้งค่าเหล่านี้อย่างชัดเจน แอปของคุณจึงต้องรับทั้งเอกสารแล้วแยกวิเคราะห์ JSON เพื่อดึงค่าเหล่านี้
การสืบทอดพร็อพเพอร์ตี้
StructuralElement
สามารถรับค่าพร็อพเพอร์ตี้จากออบเจ็กต์หลัก พร็อพเพอร์ตี้ของออบเจ็กต์ ซึ่งรวมถึงพร็อพเพอร์ตี้ที่ออบเจ็กต์กำหนดและรับค่ามา จะกำหนดลักษณะที่ปรากฏของออบเจ็กต์ในขั้นสุดท้าย
การจัดรูปแบบอักขระข้อความจะกำหนดวิธีแสดงผลข้อความในเอกสาร เช่น ตัวหนา ตัวเอียง และขีดเส้นใต้ การจัดรูปแบบที่คุณใช้จะลบล้างการจัดรูปแบบเริ่มต้นที่รับค่ามาจากTextStyle
ของย่อหน้าที่อยู่เบื้องล่าง ในทางกลับกัน อักขระที่คุณไม่ได้กำหนดการจัดรูปแบบจะยังคงรับค่าจากสไตล์ของย่อหน้า
การจัดรูปแบบย่อหน้าจะกำหนดวิธีแสดงผลบล็อกข้อความในเอกสาร เช่น การจัดตำแหน่ง เส้นขอบ และการเยื้อง การจัดรูปแบบที่คุณใช้จะลบล้างการจัดรูปแบบเริ่มต้นที่รับค่ามาจาก ParagraphStyle
พื้นฐาน
ในทางกลับกัน ฟีเจอร์การจัดรูปแบบที่คุณไม่ได้ตั้งค่าจะยังคงรับค่าจากสไตล์ย่อหน้าต่อไป