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