หน้าเว็บ องค์ประกอบของหน้า และคุณสมบัติ

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

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

การอ่านภาพรวมนี้และภาพรวมแนวคิดอื่นๆ จะช่วยให้เข้าใจและใช้คำแนะนำวิธีใช้ เอกสารอ้างอิง และตัวอย่างโค้ดได้ง่ายขึ้น

งานนำเสนอ หน้า และองค์ประกอบของหน้า

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

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

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

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

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

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

นอกจากนี้ยังมีหน้าอีก 2 ประเภท ได้แก่ หน้าบันทึกและต้นแบบบันทึก ซึ่งส่วนใหญ่จะเกี่ยวข้องกับการทำงานกับบันทึกของผู้บรรยาย

ประเภทและโครงสร้างการแสดงผล API

ส่วนนี้จะอธิบายวิธีแสดงโมเดลเชิงแนวคิดของ Google สไลด์ตามที่อธิบายไว้ข้างต้นใน Slides API

แผนภาพต่อไปนี้แสดงความสัมพันธ์ระหว่างงานนำเสนอ หน้า และองค์ประกอบของหน้าเป็นประเภทต่างๆ ใน Slides API

ส่วนต่อไปนี้แสดงวิธีแสดงประเภทเหล่านี้ใน JSON

งานนำเสนอ

งานนำเสนอประกอบด้วยพร็อพเพอร์ตี้จำนวนหนึ่งและมีหน้าต่างๆ อยู่ภายใน ดังนี้

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

Pages

หน้าประกอบด้วยชุดพร็อพเพอร์ตี้ และมีองค์ประกอบของหน้าอยู่ภายใน ดังนี้

{
  "objectId": string,
  "pageType": enum(PageType),
  "pageElements": [ { object(PageElement) } ],
  "pageProperties": { object(PageProperties) },

  // Union field properties can be only one of the following:
  "slideProperties": { object(SlideProperties) },
  "layoutProperties": { object(LayoutProperties) },
  "notesProperties": { object(NotesProperties) },
  // End of list of possible types for union field properties.
}

องค์ประกอบของหน้า

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

{
  "objectId": string,
  "size": { object(Size) },
  "transform": { object(AffineTransform) },
  "title": string,
  "description": string,

  // Union field element_kind can be only one of the following:
  "elementGroup": { object(Group) },
  "shape": { object(Shape) },
  "image": { object(Image) },
  "video": { object(Video) },
  "line": { object(Line) },
  "table": { object(Table) },
  "wordArt": { object(WordArt) },
  "sheetsChart": { object(SheetsChart) },
  // End of list of possible types for union field element_kind.
}

องค์ประกอบของหน้ามีหลายประเภทตามที่กำหนดโดยช่อง Union element_kind ในคำจำกัดความด้านบน องค์ประกอบของหน้าประเภทต่างๆ มีคำอธิบายในตารางต่อไปนี้

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

พร็อพเพอร์ตี้ของหน้าและองค์ประกอบของหน้า

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

องค์ประกอบของหน้าแต่ละประเภทจะมีองค์ประกอบพร็อพเพอร์ตี้และข้อความอัปเดตพร็อพเพอร์ตี้ที่เกี่ยวข้อง เช่น

• มีองค์ประกอบของหน้าประเภทรูปร่าง
• ช่องพร็อพเพอร์ตี้คือ shapeProperties
• คำขออัปเดตพร็อพเพอร์ตี้เหล่านี้คือ UpdateShapePropertiesRequest

ชุดองค์ประกอบ/พร็อพเพอร์ตี้/คำขออัปเดตเดียวกันนี้มีอยู่สำหรับองค์ประกอบของหน้าแต่ละประเภท ได้แก่ Image/imageProperties/UpdateImageProperties เป็นต้น

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

ประเภทของพร็อพเพอร์ตี้

มีพร็อพเพอร์ตี้บางอย่างที่ใช้ร่วมกันระหว่างออบเจ็กต์หลายประเภทใน Slides API ดังนี้

พร็อพเพอร์ตี้	คำอธิบาย
สี	สีใน Slides API อาจเป็นค่า RGB หรือการอ้างอิงสีของธีมก็ได้ สีของธีมจะอ้างอิงตามชื่อ (เช่น "DARK1") และสามารถแมปกับค่า RGB โดยใช้รูปแบบสีของหน้า โดยทั่วไปแล้ว รูปแบบสีนี้จะอัปเดตเมื่อเปลี่ยนธีมของงานนำเสนอในเครื่องมือแก้ไขสไลด์
เติมพื้น	การเติมสีแสดงถึงการแสดงผลพื้นที่ว่างภายในออบเจ็กต์ การเติมที่รองรับโดยทั่วไปในสไลด์คือการเติมสีทึบ โดยที่ภายในของออบเจ็กต์จะเติมด้วยสีทึบสีเดียว นอกจากนี้ยังใช้การเติมสีสำหรับพื้นหลังของหน้าได้ด้วย
โครงร่าง	เส้นขอบแสดงชุดเส้นที่ล้อมรอบองค์ประกอบของหน้า สีของเส้นจะควบคุมด้วยการเติม นอกจากนี้ ผู้โทรยังปรับความกว้างและรูปแบบเส้นประของเส้นขอบได้ด้วย
เงา	เงาแสดงถึงเอฟเฟกต์ภาพที่เลียนแบบเงาจริงที่วัตถุทอดลงมา ปัจจุบันเงาใน Slides API เป็นแบบอ่านอย่างเดียว

กำลังอัปเดตพร็อพเพอร์ตี้

หากต้องการอัปเดตพร็อพเพอร์ตี้ ให้ใช้คำขอ Update...Properties ที่เหมาะสมในการเรียกใช้ batchUpdate เช่น UpdateShapeProperties สำหรับรูปร่าง คำขอเหล่านี้ยอมรับข้อความพร็อพเพอร์ตี้แบบเต็มและสามารถใช้มาสก์ฟิลด์เพื่อระบุว่าควรจะอัปเดตฟิลด์ใดในข้อความพร็อพเพอร์ตี้

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

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

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

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

เราจะอธิบายแนวคิดเหล่านี้เพิ่มเติมในย่อหน้าต่อไปนี้

การรับค่าพร็อพเพอร์ตี้ของหน้าเว็บ

โครงสร้างของสไลด์ เลย์เอาต์ และต้นแบบจะกำหนดลำดับชั้นการรับค่าภายในงานนำเสนอ โดยสไลด์จะรับค่าจากเลย์เอาต์ และเลย์เอาต์จะรับค่าจากต้นแบบ เลย์เอาต์หลักและต้นแบบของสไลด์จะระบุไว้ในช่อง slideProperties ของสไลด์

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

แผนภาพต่อไปนี้แสดงสไลด์ที่รับค่าพร็อพเพอร์ตี้จากเลย์เอาต์ ซึ่งรับค่ามาจากต้นแบบ

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

• PropertyA คือ "Red"
• PropertyB คือ "Orange"

หน้าเว็บที่ไม่มีหน้าหลักจะรับค่าเริ่มต้นจาก Google สไลด์สำหรับพร็อพเพอร์ตี้ที่ไม่ได้กำหนดไว้

การรับค่าพร็อพเพอร์ตี้รูปร่าง

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

คุณสามารถสร้างตัวยึดตำแหน่งโดยใช้เครื่องมือแก้ไขสไลด์ แต่จะใช้ Slides API ไม่ได้

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

แผนภาพต่อไปนี้แสดงการรับค่าพร็อพเพอร์ตี้ระหว่างตัวยึดตำแหน่ง 3 รายการที่อยู่ในสไลด์ เลย์เอาต์ และต้นแบบ

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

• Placeholder1: propertyA แสดงผลเป็น "Yellow", propertyB แสดงผลเป็น "Green"
• Placeholder2: propertyA แสดงเป็น "Yellow", propertyB แสดงเป็น "Purple"
• Placeholder3: propertyA แสดงเป็น "Yellow", propertyB แสดงเป็น "Purple"

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

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

"การซ่อน" พร็อพเพอร์ตี้โดยใช้ PropertyState

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

การอัปเดตพร็อพเพอร์ตี้จะตั้งค่าสถานะพร็อพเพอร์ตี้เป็น `RENDERED` โดยนัย เว้นแต่คุณจะตั้งค่าสถานะเป็นค่าอื่นในคำขอเดียวกัน

แผนภาพต่อไปนี้แสดงการรับค่าพร็อพเพอร์ตี้ระหว่างตัวยึดตำแหน่ง 3 ตัวที่จัดการฟิลด์ PropertyState

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

• Placeholder1: พร็อพเพอร์ตี้ A แสดงผลเป็น "สีแดง"
• Placeholder2: propertyA ไม่แสดงผล หากนี่เป็นพร็อพเพอร์ตี้ของเส้นขอบ Placeholder2 จะไม่มีเส้นขอบ
• Placeholder3: propertyA ไม่แสดงผล

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