Struktur dokumen Google Dokumen

Untuk menggunakan Google Docs API secara efektif, Anda harus memahami arsitektur dokumen Google Dokumen dan elemen yang membentuk dokumen, serta hubungan di antara elemen tersebut. Halaman ini memberikan ringkasan mendetail tentang topik berikut:

  • Model konseptual elemen dokumen
  • Cara Docs API merepresentasikan elemen ini
  • Properti gaya elemen

Elemen tingkat teratas

Elemen penampung terluar di Google Dokumen adalah dokumen. Ini adalah unit yang dapat disimpan di Google Drive, dibagikan kepada pengguna lain, dan diperbarui dengan teks dan gambar.

Elemen tingkat teratas dari resource documents mencakup Tab, SuggestionsViewMode, dan atribut lainnya:

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

Tabs

Satu dokumen dapat berisi beberapa tab, yang memiliki konten tingkat teks yang berbeda. Properti tabs dokumen adalah urutan objek Tab. Tab terdiri atas kolom berikut:

  • TabProperties: Berisi atribut tab seperti ID, judul, dan indeks.
  • childTabs: Menampilkan tab turunan tab (tab yang disarangkan langsung di bawahnya).
  • DocumentTab: Mewakili konten teks tab.
Struktur tab dokumen.
Gambar 1. Struktur tab dokumen.

Bagian selanjutnya memberikan ringkasan singkat tentang hierarki tab dokumen; Representasi JSON tab juga memberikan informasi yang lebih mendetail. Lihat Bekerja dengan Tab untuk mengetahui informasi selengkapnya tentang fitur tab.

Untuk memanipulasi fitur tab dokumen global di luar konten Body, hampir selalu lebih baik menggunakan satu atau beberapa template dokumen, yang dapat Anda gunakan sebagai dasar untuk membuat dokumen baru secara terprogram. Untuk mengetahui informasi selengkapnya, lihat Menggabungkan teks ke dalam dokumen.

Isi teks

Body biasanya berisi seluruh konten tab dokumen. Sebagian besar item yang dapat, atau kemungkinan ingin, Anda gunakan secara terprogram adalah elemen dalam konten Body:

Struktur konten isi.
Gambar 2. Struktur konten isi.

Elemen struktural

StructuralElement mendeskripsikan konten yang memberikan struktur pada dokumen. Konten Body adalah urutan objek StructuralElement. Elemen konten mempersonalisasi setiap objek StructuralElement, seperti yang ditunjukkan dalam diagram berikut:

Elemen struktural.
Gambar 3. Elemen struktural.

Elemen struktural dan objek kontennya berisi semua komponen visual dalam dokumen. Hal ini mencakup teks, gambar inline, dan pemformatan.

Struktur paragraf

Paragraph adalah StructuralElement yang merepresentasikan paragraf. Memiliki rentang konten yang diakhiri dengan karakter baris baru. Terdiri dari objek berikut:

  • ParagraphElement: Mendeskripsikan konten dalam paragraf.
  • ParagraphStyle: Elemen opsional yang secara eksplisit menetapkan properti gaya untuk paragraf.
  • Bullet: Jika paragraf adalah bagian dari daftar, elemen opsional yang memberikan spesifikasi butir.

ParagraphElement berfungsi seperti StructuralElement. Serangkaian jenis elemen konten (seperti ColumnBreak dan Equation) mempersonalisasi ParagraphElement-nya sendiri, seperti yang ditunjukkan dalam diagram berikut:

Struktur elemen paragraf.
Gambar 4. Struktur elemen paragraf.

Untuk contoh struktur dokumen lengkap, lihat contoh 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 berikutnya.

Jalankan teks

TextRun adalah ParagraphElement yang merepresentasikan string teks yang berdekatan dengan semua gaya teks yang sama. Paragraf dapat berisi beberapa rangkaian teks, tetapi rangkaian teks tidak pernah melintasi batas paragraf. Konten dibagi setelah karakter newline untuk membentuk rangkaian teks terpisah. Misalnya, perhatikan dokumen kecil seperti berikut:

Dokumen kecil dengan paragraf dan daftar berbutir.
Gambar 5. Dokumen kecil.

Diagram berikut menunjukkan cara Anda dapat memvisualisasikan urutan paragraf dalam dokumen sebelumnya, yang masing-masing memiliki setelan TextRun dan Bullet opsional.

Struktur rangkaian teks.
Gambar 6. Struktur rangkaian teks.

AutoText

AutoText adalah ParagraphElement yang merepresentasikan tempat dalam teks yang diganti secara dinamis dengan konten yang dapat berubah dari waktu ke waktu. Di Dokumen, ini digunakan untuk nomor halaman.

Indeks awal dan akhir

Saat Anda memperbarui konten tab dokumen, setiap pembaruan dilakukan di lokasi atau di seluruh rentang dalam dokumen. Lokasi dan rentang ini ditentukan menggunakan indeks, yang merepresentasikan offset dalam segmen dokumen yang berisi. Segmen adalah isi, header, footer, atau catatan kaki yang berisi elemen struktural atau konten. Indeks elemen dalam segmen relatif terhadap awal segmen tersebut.

Sebagian besar elemen dalam konten isi memiliki properti startIndex dan endIndex berbasis nol. Atribut ini menunjukkan offset awal dan akhir elemen, relatif terhadap awal segmen yang menyertakannya. Untuk mengetahui informasi selengkapnya tentang cara mengurutkan panggilan batch Docs API, lihat Pembaruan batch.

Indeks diukur dalam unit kode UTF-16. Artinya, pasangan surrogate menggunakan dua indeks. Misalnya, emoji "WAJAH MENYERINGAI", 😄, ditampilkan sebagai \uD83D\uDE00 dan menggunakan dua indeks.

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

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

Mengakses elemen

Banyak elemen dapat diubah dengan metode documents.batchUpdate. Misalnya, dengan menggunakan InsertTextRequest, Anda dapat mengubah konten elemen apa pun yang berisi teks. Demikian pula, Anda dapat menggunakan UpdateTextStyleRequest untuk menerapkan format ke rentang teks yang terdapat dalam satu atau beberapa elemen.

Untuk membaca elemen dokumen, gunakan metode documents.get untuk mendapatkan dump JSON dari dokumen lengkap. Kemudian, Anda dapat mengurai JSON yang dihasilkan untuk menemukan nilai elemen individual. Untuk mengetahui informasi selengkapnya, lihat Menampilkan konten dokumen sebagai JSON.

Mengurai konten dapat bermanfaat untuk berbagai kasus penggunaan. Misalnya, pertimbangkan aplikasi pengatalogan dokumen yang mencantumkan dokumen yang ditemukannya. Aplikasi ini dapat mengekstrak judul, ID revisi, dan nomor halaman awal tab dokumen, seperti yang ditunjukkan dalam diagram berikut:

Struktur katalog dokumen.
Gambar 7. Struktur katalog dokumen.

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

Warisan properti

StructuralElement dapat mewarisi properti dari objek induknya. Properti objek, termasuk yang ditentukan dan yang diwariskan, menentukan tampilan visual akhirnya.

Pemformatan karakter teks menentukan cara teks dirender dalam dokumen, seperti tebal, miring, dan garis bawah. Pemformatan yang Anda terapkan akan menggantikan pemformatan default yang diwarisi dari TextStyle paragraf yang mendasarinya. Sebaliknya, karakter apa pun yang pemformatannya tidak Anda tetapkan akan terus diwarisi dari gaya paragraf.

Pemformatan paragraf menentukan cara blok teks dirender dalam dokumen, seperti perataan, batas, dan indentasi. Pemformatan yang Anda terapkan menggantikan pemformatan default yang diwarisi dari ParagraphStyle yang mendasarinya. Sebaliknya, fitur pemformatan yang tidak Anda tetapkan akan terus diwarisi dari gaya paragraf.