Halaman ini diterjemahkan oleh Cloud Translation API.

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 dokumen tersebut. Halaman ini menyediakan ringkasan mendetail tentang topik-topik berikut:

Model konseptual elemen dokumen
Cara Docs API mewakili elemen-elemen ini
Properti gaya visual elemen

Elemen tingkat atas

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

Elemen tingkat atas dari resource documents menyertakan Body, Header, Footer, dan beberapa atribut lainnya:

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

Untuk memanipulasi fitur dokumen global di luar konten Body, sebaiknya gunakan satu atau beberapa template dokumen yang dapat Anda gunakan sebagai dasar untuk membuat dokumen baru secara terprogram. Untuk mengetahui informasi selengkapnya, lihat Menggabungkan teks menjadi dokumen.

Konten isi

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

Elemen struktural

StructuralElement menjelaskan 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 dan objek kontennya berisi semua komponen visual dalam dokumen. Ini termasuk teks, gambar inline, dan pemformatan.

Struktur paragraf

Paragraph adalah StructuralElement yang merepresentasikan paragraf. Berisi berbagai konten yang dihentikan dengan karakter baris baru. Terdiri dari objek berikut:

ParagraphElement: Menjelaskan 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. Kumpulan jenis elemen konten (seperti ColumnBreak dan Equation) mempersonalisasi ParagraphElement-nya sendiri, seperti yang ditunjukkan dalam diagram berikut:

Untuk contoh struktur dokumen yang 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 berikut.

Teks berjalan

TextRun adalah ParagraphElement yang mewakili string teks yang berdekatan dengan semua gaya teks yang sama. Sebuah paragraf dapat berisi beberapa operasi teks, tetapi operasi teks tidak pernah melintasi batas paragraf. Konten dipisahkan setelah karakter baris baru untuk membentuk eksekusi teks terpisah. Misalnya, pertimbangkan dokumen kecil seperti berikut ini:

Dokumen kecil dengan paragraf dan daftar berbutir. — **Gambar 4.** Dokumen kecil.

Diagram berikut menunjukkan cara memvisualisasikan urutan paragraf dalam dokumen sebelumnya, masing-masing dengan setelan TextRun dan setelan Bullet opsionalnya sendiri.

**Gambar 5.** Struktur teks yang dijalankan.

AutoText

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

Indeks awal dan akhir

Saat Anda melakukan pembaruan pada konten dokumen, setiap pembaruan akan berlangsung di suatu lokasi atau di seluruh rentang dalam dokumen. Lokasi dan rentang ini ditentukan menggunakan indeks, yang mewakili offset dalam segmen dokumen yang memuatnya. Segmen adalah isi, header, footer, atau catatan kaki yang berisi elemen struktural atau konten. Indeks elemen dalam sebuah segmen relatif terhadap awal segmen tersebut.

Sebagian besar elemen dalam konten isi memiliki properti startIndex dan endIndex berbasis nol. Nilai ini menunjukkan offset awal dan akhir elemen, relatif terhadap awal segmen yang melingkupinya. Untuk informasi selengkapnya tentang cara mengurutkan panggilan API Dokumen batch, lihat Update massal.

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

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

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

Elemen akses

Banyak elemen yang dapat diubah dengan metode documents.batchUpdate. Misalnya, dengan 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 documents.get untuk mendapatkan dump JSON dari dokumen lengkap. Anda kemudian dapat mengurai JSON yang dihasilkan untuk menemukan nilai masing-masing elemen. Untuk mengetahui informasi selengkapnya, lihat Konten dokumen output sebagai JSON.

Penguraian konten dapat bermanfaat untuk berbagai kasus penggunaan. Pertimbangkan, misalnya, dokumen yang membuat katalog aplikasi yang mencantumkan dokumen yang ditemukannya. Aplikasi ini dapat mengekstrak judul, ID revisi, dan nomor halaman awal dokumen, seperti yang ditunjukkan pada diagram berikut:

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

Warisan properti

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

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

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