Struktur dokumen Google Dokumen

Panduan ini menjelaskan struktur internal dokumen Google Dokumen: elemen yang membentuk dokumen dan hubungan di antara elemen tersebut.

Elemen tingkat atas

Elemen tingkat atas dokumen mencakup isi dan beberapa atribut dokumen lainnya secara keseluruhan:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

Untuk memanipulasi fitur dokumen global di luar konten isi, sebaiknya gunakan satu atau beberapa template dokumen, yang dapat Anda gunakan sebagai dasar untuk membuat dokumen baru secara terprogram.

Konten isi

Sebagian besar item yang dapat, atau mungkin ingin, Anda gunakan secara terprogram adalah elemen dalam konten isi:

Diagram konten isi.

Elemen struktural

Konten isi hanyalah urutan objek StructuralElement. Elemen konten mempersonalisasi setiap objek StructuralElement, seperti yang ditunjukkan dalam diagram berikut:

Diagram elemen struktural.

Elemen struktural dan objek kontennya berisi semua teks dokumen, gambar inline, dan sebagainya.

Paragraf berisi jenis elemen khusus yang disebut ParagraphElement yang berfungsi seperti StructuralElement. Kumpulan jenis elemen konten mempersonalisasi ParagraphElement-nya sendiri, seperti yang ditunjukkan dalam diagram berikut:

Diagram elemen paragraf.

Untuk contoh struktur dokumen yang lengkap, lihat contoh dump dokumen dalam format JSON. Dalam output, Anda dapat melihat banyak elemen struktural dan konten utama, serta penggunaan indeks awal dan akhir seperti yang dijelaskan di bagian berikut.

Indeks awal dan akhir

Sebagian besar elemen dalam konten isi memiliki properti startIndex dan endIndex. Ini menunjukkan offset awal dan akhir elemen, relatif terhadap awal segmen yang melingkupinya.

Indeks diukur dalam unit kode UTF-16. Ini berarti pasangan surrogate memakai 2 indeks. Misalnya, emoji "WAJAH MENYARIK", 👀, akan direpresentasikan sebagai "\uD83D\uDE00" dan akan menggunakan 2 indeks.

Untuk elemen dalam isi dokumen, indeks merepresentasikan offset dari awal konten isi, yang merupakan elemen "root".

Jenis "personalisasi" untuk elemen struktural—SectionBreak, TableOfContents, Table, dan Paragraph—tidak memiliki indeks ini karena penutupnya StructuralElement memiliki kolom ini. Hal ini juga berlaku untuk jenis personalisasi yang terdapat dalam ParagraphElement.

Struktur paragraf

Sebuah paragraf terdiri dari hal-hal berikut:

  • elements—Urutan yang berisi satu atau beberapa instance textRun.
  • paragraphStyle—Elemen opsional yang secara eksplisit menetapkan properti gaya untuk paragraf.
  • bullet—Elemen opsional yang memberikan spesifikasi butir jika paragraf merupakan bagian dari daftar.

Teks berjalan

textRun mewakili string teks yang berdekatan dengan semua gaya teks yang sama. Sebuah paragraf dapat berisi beberapa baris teks, tetapi teks tidak boleh melintasi batas paragraf. Misalnya, pertimbangkan dokumen kecil seperti berikut:

Diagram berikut menunjukkan cara memvisualisasikan urutan paragraf dalam dokumen di atas, masing-masing dengan eksekusi teksnya sendiri dan setelan butir opsional.

Diagram teks berjalan.

Elemen akses

Banyak elemen yang dapat diubah menggunakan metode BatchUpdate. Misalnya, dengan menggunakan jenis permintaan InsertTextRequest, Anda dapat mengubah isi elemen apa pun yang berisi teks. Demikian pula, Anda dapat menggunakan UpdateTextStyleRequest untuk menerapkan pemformatan ke rentang teks yang terdapat dalam satu atau beberapa elemen.

Untuk membaca elemen dokumen, gunakan metode get untuk mendapatkan dump JSON dari dokumen lengkap. (Untuk mengetahui cara melakukannya, lihat contoh Konten dokumen output sebagai JSON.) Anda kemudian dapat mengurai JSON yang dihasilkan untuk menemukan nilai setiap elemen.

Mengurai konten dapat berguna untuk berbagai kasus penggunaan. Misalnya, pertimbangkan dokumen yang membuat katalog listingan aplikasi yang berisi dokumen yang ditemukannya. Aplikasi ini mungkin ingin mengekstrak judul, ID revisi, dan nomor halaman awal dokumen, seperti yang ditunjukkan dalam diagram berikut:

Diagram aplikasi katalog dokumen.

Karena tidak ada metode untuk membaca setelan ini secara eksplisit, aplikasi Anda harus mendapatkan seluruh dokumen, lalu mengurai JSON untuk mengekstrak nilai ini.