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

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

  • โมเดลเชิงแนวคิดขององค์ประกอบเอกสาร
  • วิธีที่ Docs API แสดงองค์ประกอบเหล่านี้
  • พร็อพเพอร์ตี้การจัดสไตล์ขององค์ประกอบ

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

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

องค์ประกอบระดับบนสุดของ documentsทรัพยากรได้แก่ its Tabs, SuggestionsViewMode, และแอตทริบิวต์อื่นๆ

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

แท็บ

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

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

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

หากต้องการจัดการฟีเจอร์แท็บเอกสารส่วนกลางนอกเนื้อหา Body การใช้เทมเพลตเอกสารอย่างน้อย 1 รายการซึ่งคุณใช้เป็นพื้นฐานในการสร้างเอกสารใหม่แบบเป็นโปรแกรมมักจะเป็นวิธีที่ดีกว่า ดูข้อมูลเพิ่มเติมได้ที่หัวข้อ Merge text into a document

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

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

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

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

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

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

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

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

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

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

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

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

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

TextRun

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

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

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

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

AutoText

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

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

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

องค์ประกอบส่วนใหญ่ภายในเนื้อหาในเนื้อความมีพร็อพเพอร์ตี้ startIndex และ endIndex ซึ่งอิงตาม 0 โดยพร็อพเพอร์ตี้เหล่านี้จะระบุออฟเซ็ตของจุดเริ่มต้นและจุดสิ้นสุดขององค์ประกอบ ซึ่งสัมพันธ์กับจุดเริ่มต้นของส่วนที่ล้อมรอบ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีจัดลำดับการเรียก Docs API แบบกลุ่มได้ที่หัวข้อ Batch updates

ดัชนีจะวัดเป็นหน่วยโค้ด UTF-16 ซึ่งหมายความว่าคู่ตัวแทนจะใช้ดัชนี 2 รายการ ตัวอย่างเช่น อีโมจิ "GRINNING FACE" 😄 แสดงเป็น \uD83D\uDE00 และใช้ดัชนี 2 รายการ

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

ประเภท "การปรับเปลี่ยน" สำหรับองค์ประกอบโครงสร้าง ได้แก่SectionBreak,TableOfContents,Table และParagraph จะไม่มีดัชนีเหล่านี้เนื่องจากStructuralElement ที่ล้อมรอบมีช่องเหล่านี้ ซึ่งเป็นกรณีเดียวกันกับประเภทการปรับเปลี่ยนที่มีอยู่ใน ParagraphElement เช่น TextRun, AutoText, และ PageBreak

เข้าถึงองค์ประกอบ

องค์ประกอบหลายรายการแก้ไขได้ด้วยเมธอด documents.batchUpdate ตัวอย่างเช่น การใช้ InsertTextRequest, จะช่วยให้คุณเปลี่ยนเนื้อหาขององค์ประกอบที่มีข้อความได้ ในทำนองเดียวกัน คุณสามารถ ใช้ UpdateTextStyleRequest เพื่อใช้การจัดรูปแบบกับช่วงข้อความที่มีอยู่ในองค์ประกอบอย่างน้อย 1 รายการ

หากต้องการอ่านองค์ประกอบของเอกสาร ให้ใช้เมธอด documents.getเพื่อ รับการดัมพ์ JSON ของเอกสารแบบสมบูรณ์ จากนั้นคุณจะแยกวิเคราะห์ JSON ที่ได้เพื่อค้นหาค่าขององค์ประกอบแต่ละรายการได้ ดูข้อมูลเพิ่มเติมได้ที่หัวข้อ Output document contents as JSON

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

โครงสร้างของแคตตาล็อกเอกสาร
รูปที่ 7 โครงสร้างของแคตตาล็อกเอกสาร

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

การสืบทอดพร็อพเพอร์ตี้

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

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

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