Halaman, Elemen Halaman, dan Properti

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

• Model konseptual komponen presentasi
• Cara API merepresentasikan komponen ini
• Properti gaya komponen

Membaca ringkasan konsep ini dan ringkasan konsep lainnya akan memudahkan Anda memahami dan menggunakan panduan cara kerja, dokumentasi referensi, dan contoh kode.

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, yang merupakan halaman yang dilihat dan dibalik pengguna saat presentasi dirender 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 adalah master dan tata letak, dan propertinya menentukan cara slide dirender, seperti yang ditunjukkan dalam diagram berikut:

Master — Halaman master memiliki dua tujuan. Placeholder di master berisi default untuk gaya teks yang digunakan di seluruh presentasi Anda. Latar belakang dan bentuk lainnya di 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 master.

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

Ada dua jenis halaman lagi—halaman catatan dan master catatan—yang sebagian besar relevan untuk digunakan dengan 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 sesuai dengan 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, seperti yang ditentukan oleh kolom gabungan element_kind dalam definisi di atas. Jenis elemen halaman ini dijelaskan dalam tabel berikut:

Jenis elemen	Deskripsi
Grup	Kumpulan elemen halaman yang diperlakukan sebagai unit tersendiri. Objek tersebut dapat dipindahkan, diskalakan, dan diputar bersama-sama.
Bentuk	Objek visual biasa, seperti persegi panjang, elips, dan kotak teks. Bentuk dapat berisi teks, sehingga merupakan elemen halaman yang paling umum untuk membuat slide.
Gambar	Grafik yang diimpor ke Slide.
Video	Video yang diimpor ke Slide.
Garis	Garis, kurva, atau konektor visual.
Tabel	Petak konten.
WordArt	Elemen teks visual yang berperilaku lebih seperti bentuk.
SheetsChart	Diagram yang diimpor ke Slide dari Google Spreadsheet.

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 dan pesan pembaruan properti yang sesuai, misalnya:

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

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

Anda dapat membaca atribut properti di mana pun Anda menemukannya 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:

Properti	Deskripsi
Warna	Warna di Slides API dapat berupa nilai RGB atau referensi ke warna tema. Warna tema dirujuk berdasarkan nama (misalnya "DARK1") dan dapat dipetakan ke nilai RGB menggunakan skema warna halaman. Skema warna ini biasanya diperbarui saat mengubah tema presentasi di editor Slide.
Isi	Isi mewakili rendering ruang kosong di dalam objek. Isian yang paling umum didukung di Slide adalah isian solid, yaitu bagian dalam objek diisi dengan satu warna solid. Isian juga dapat digunakan untuk latar belakang Halaman.
Garis batas	Garis batas mewakili kumpulan garis yang mengelilingi elemen halaman. Warna garis dikontrol dengan Isian. Pemanggil juga dapat menyesuaikan lebar dan gaya garis putus-putus dari garis batas.
Bayangan	Bayangan ini merepresentasikan efek visual yang dimaksudkan untuk meniru bayangan fisik yang dihasilkan oleh objek. Saat ini, bayangan di Slides API bersifat hanya baca.

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.

Masker kolom * diperlakukan seperti karakter pengganti dan merupakan singkatan untuk menentukan setiap kolom dalam pesan. Sintaksis karakter pengganti dapat memberikan hasil yang tidak diinginkan jika API diperbarui di masa mendatang, karena kolom hanya baca dan kolom yang baru ditambahkan dapat menyebabkan error. Untuk aplikasi produksi, selalu cantumkan kolom tertentu yang sedang diperbarui dalam mask kolom dan hindari penggunaan karakter pengganti *.

Warisan properti

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

• Properti halaman — Halaman mewarisi properti apa pun yang tidak ditentukannya, tetapi ditentukan dalam tata letak atau master yang menjadi dasarnya.
• Properti bentuk — Bentuk dapat ditandai sebagai placeholder, sehingga Anda dapat secara eksplisit mereferensikan bentuk placeholder lain (pada tata letak induk atau master halaman) yang menjadi sumber pewarisan properti.

Ide-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 dalam 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 akan menerima nilai yang diwariskan.

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 yang diwarisinya. Dalam contoh ini, nilai yang di-resolve yang digunakan untuk merender Slide 1 adalah sebagai berikut:

• PropertyA adalah "Red".
• PropertyB adalah "Orange".

Halaman yang tidak memiliki induk akan mewarisi nilai default dari Google Slide untuk properti apa pun yang tidak ditentukannya.

Pewarisan properti bentuk

Bentuk dapat mewarisi properti, seperti isian, garis batas, atau bayangan, dari bentuk lain. Bentuk adalah placeholder jika kolom Shape.placeholder-nya 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.

Anda dapat membuat placeholder menggunakan editor Slide, tetapi tidak menggunakan Slides API.

Dengan hierarki pewarisan yang ditentukan ini, 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 diwariskan.

Diagram berikut menunjukkan pewarisan properti antara tiga placeholder yang terdapat dalam slide, tata letak, dan master:

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

• Placeholder1: propertyA dirender sebagai "Yellow", propertyB sebagai "Green".
• Placeholder2: propertyA dirender sebagai "Yellow", propertyB sebagai "Purple".
• Placeholder3: propertyA dirender sebagai "Yellow", propertyB sebagai "Purple".

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.

Jika bentuk tidak memiliki induk, nilai apa pun yang tidak ditetapkan akan otomatis diisi dengan default aplikasi.

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

Memperbarui properti secara implisit akan menetapkan status propertinya ke `RENDERED`, kecuali jika Anda menetapkan status ke nilai lain dalam permintaan yang sama.

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

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

• Placeholder1: propertyA dirender sebagai "Red".
• Placeholder2: propertyA is not rendered. Jika ini adalah properti outline, Placeholder2 tidak akan memiliki outline.
• Placeholder3: propertyA tidak dirender.

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