Halaman, Elemen Halaman, dan Properti

Untuk menggunakan Slides API secara efektif, Anda perlu memahami arsitektur presentasi dan komponennya, serta interaksi antara komponen tersebut. Halaman ini memberikan ringkasan mendetail tentang topik-topik berikut:

• Model konseptual komponen presentasi
• Cara API merepresentasikan komponen ini
• Menata gaya properti komponen

Membaca ringkasan konsep ini dan konsep lainnya akan mempermudah Anda memahami dan menggunakan panduan cara melakukannya, dokumentasi referensi, dan contoh resep.

Presentasi, halaman, dan elemen halaman

Elemen penampung terluar di Google Slide adalah presentasi. Ini adalah unit yang dapat disimpan di Google Drive, dibagikan kepada pengguna lain, dan sebagainya.

Setiap presentasi berisi berbagai jenis halaman. Salah satu jenis halaman adalah slide, yaitu halaman yang dilihat dan dibuka pengguna saat presentasi ditampilkan di layar.

Setiap halaman berisi sejumlah elemen halaman, yang bersama-sama membentuk konten halaman, seperti yang ditunjukkan dalam diagram berikut:

Selain slide, ada jenis halaman lain yang memungkinkan Anda menerapkan desain ke banyak slide yang berbeda, sehingga menciptakan tampilan yang konsisten. Jenis halaman lainnya ini adalah master dan tata letak, dan propertinya menentukan cara slide dirender, seperti yang ditunjukkan dalam diagram berikut:

Master — Halaman master memiliki dua tujuan. Penampung di slide master berisi gaya teks default yang digunakan di seluruh presentasi Anda. Latar belakang dan bentuk lain pada slide master membentuk latar belakang default untuk semua slide berdasarkan master tersebut. Jika Anda memiliki logo perusahaan yang ingin ditampilkan di setiap slide dalam presentasi, letakkan di slide master.

Tata Letak — Template tata letak menentukan cara konten disusun pada setiap jenis slide. Jika Anda ingin semua slide judul terlihat dengan cara tertentu, misalnya, Anda dapat mengedit template tata letak judul.

Ada dua jenis halaman lagi—halaman catatan dan master catatan—yang sebagian besar relevan untuk menggunakan catatan pembicara.

Jenis dan struktur representasi API

Bagian ini menjelaskan cara model konseptual Google Slide, seperti yang dijelaskan di atas, direpresentasikan dalam Slides API.

Diagram berikut menggambarkan hubungan antara presentasi, halaman, dan elemen halaman sebagai jenis dalam Slides API:

Bagian berikut menunjukkan cara jenis ini direpresentasikan dalam JSON.

Presentasi

Presentasi mencakup sejumlah properti, dan berisi halaman yang ada di dalamnya:

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

Halaman

Halaman mencakup sekumpulan properti, dan berisi elemen halaman yang ada di dalamnya:

{
  "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.
}

Elemen halaman

Elemen halaman adalah komponen visual yang ditempatkan di halaman. Elemen halaman di API berisi sejumlah properti, termasuk kolom yang bervariasi menurut jenis elemen halaman:

{
  "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.
}

Ada beberapa jenis elemen halaman, sebagaimana ditentukan oleh kolom gabungan element_kind dalam definisi di atas. Jenis elemen halaman ini dijelaskan dalam tabel berikut:

Properti halaman dan elemen halaman

Slides API memungkinkan Anda membaca dan memperbarui tampilan halaman dan elemen halaman dalam presentasi Anda. Elemen halaman yang berbeda mendukung properti yang berbeda yang mengontrol cara elemen halaman dirender.

Setiap jenis elemen halaman memiliki elemen properti yang sesuai dan pesan update properti, misalnya:

• Ada jenis elemen halaman Bentuk
• Kolom propertinya adalah shapeProperties
• Permintaan untuk memperbarui properti ini adalah UpdateShapePropertiesRequest

Set elemen/properti/permintaan pembaruan yang sama ada untuk setiap jenis elemen halaman: Image/imageProperties/UpdateImageProperties, dan sebagainya.

Anda dapat membaca atribut properti di mana pun Anda menemuinya saat membaca elemen; untuk mengubah nilai di dalamnya, gunakan dengan jenis permintaan yang cocok sebagai payload untuk metode batchUpdate, sehingga Anda dapat mengubah nilai ini dalam presentasi.

Jenis properti

Ada beberapa properti yang umum di antara beberapa jenis objek di Slides API:

Memperbarui properti

Untuk memperbarui properti, gunakan permintaan Update...Properties yang sesuai dalam panggilan batchUpdate—misalnya, UpdateShapeProperties untuk Bentuk. Permintaan ini menerima pesan properti lengkap dan dapat menggunakan mask kolom untuk menentukan kolom mana dalam pesan properti yang harus diperbarui.

Warisan properti

Halaman atau elemen halaman dapat mewarisi properti dari objek induknya. Properti objek, termasuk properti yang ditentukan dan yang diwariskan, menentukan tampilan visual akhirnya.

• Properti halaman — Halaman mewarisi properti apa pun yang tidak ditentukan, tetapi ditentukan dalam tata letak atau master yang menjadi dasarnya.
• Properti bentuk — Bentuk dapat ditandai sebagai tempat penampung, sehingga Anda dapat secara eksplisit merujuk bentuk tempat penampung lain (pada tata letak induk atau master halaman) yang propertinya akan diwarisi.

Ide ini dijelaskan lebih lanjut dalam paragraf berikut.

Pewarisan properti halaman

Struktur slide, tata letak, dan master menentukan hierarki pewarisan dalam presentasi: slide mewarisi dari tata letak, dan tata letak mewarisi dari master. Tata letak induk dan master slide ditentukan di kolom slideProperties slide.

Halaman dapat mewarisi properti, seperti latar belakang dan skema warna, dari halaman induk. Untuk mewarisi properti, halaman turunan cukup tidak menetapkan nilai untuk properti tersebut dalam pesan PageProperties-nya. Dengan tidak "mengganti" nilai yang ditentukan oleh induk, halaman menerima nilai yang diwarisi.

Diagram berikut menunjukkan slide yang mewarisi properti dari tata letak, yang mewarisi dari master:

Properti yang digunakan untuk merender slide adalah kombinasi dari properti yang ditentukan dan properti yang diwariskan. Dalam contoh ini, nilai yang di-resolve yang digunakan untuk merender Slide 1 adalah sebagai berikut:

• PropertyA adalah "Merah".
• PropertyB adalah "Orange".

Pewarisan properti bentuk

Bentuk dapat mewarisi properti, seperti pengisi, garis batas, atau bayangan, dari bentuk lain. Bentuk adalah placeholder jika kolom Shape.placeholder ditetapkan. Kolom Shape.placeholder.parentObjectId placeholder turunan mengidentifikasi placeholder induknya. Saat Anda membuat slide baru berdasarkan tata letak, semua placeholder dalam tata letak tersebut akan muncul sebagai bentuk turunan di slide baru. Demikian pula, placeholder di halaman master dapat bertindak sebagai induk dari placeholder tata letak.

Dengan hierarki pewarisan ini ditentukan, halaman turunan mewarisi properti dengan tidak menetapkan nilai tersebut dalam pesan ShapeProperties-nya. Dengan tidak mengganti nilai yang ditentukan oleh induk, bentuk turunan menerima nilai yang diwarisi.

Diagram berikut menunjukkan pewarisan properti antara tiga tempat penampung yang ada dalam slide, tata letak, dan master:

Properti yang digunakan untuk merender bentuk placeholder adalah kombinasi dari properti yang ditentukan dan yang diwariskan. Dalam contoh ini, nilai yang di-resolve untuk bentuk tersebut adalah sebagai berikut:

• Placeholder1: propertyA dirender sebagai "Kuning", propertyB sebagai "Hijau".
• Placeholder2: propertyA dirender sebagai "Kuning", propertyB sebagai "Ungu".
• Placeholder3: propertyA dirender sebagai "Kuning", propertyB sebagai "Ungu".

Bentuk adalah satu-satunya jenis elemen halaman yang dapat memiliki induk. Jenis lain, seperti gambar, tabel, dan diagram, tidak dapat menjadi placeholder dan tidak dapat memiliki induk.

Menyembunyikan properti menggunakan PropertyState

Enumerasi PropertyState mengontrol apakah properti bentuk benar-benar digunakan untuk rendering, atau apakah nilai hanya digunakan untuk pewarisan oleh bentuk turunan. Properti dengan status properti NOT_RENDERED tidak akan digunakan saat merender bentuk di halamannya, tetapi turunan yang memiliki status properti RENDERED yang sesuai masih dapat mewarisi properti ini.

Diagram berikut menunjukkan pewarisan properti antara tiga placeholder yang memanipulasi kolom PropertyState:

Rendering properti bentuk dapat dipengaruhi oleh kolom PropertyState. Dalam contoh ini, nilai yang diselesaikan untuk bentuk ini adalah sebagai berikut:

• Placeholder1: propertyA dirender sebagai "Merah".
• Placeholder2: propertyA tidak dirender. Jika ini adalah properti garis batas, Placeholder2 tidak akan memiliki garis batas.
• Placeholder3: propertyA tidak dirender.

Ada satu lagi kemungkinan nilai enumerasi PropertyState: status properti INHERIT berarti bahwa status properti itu sendiri diwarisi, dan nilai induk harus digunakan. Bentuk tanpa induk tidak dapat memiliki status properti INHERIT.