Untuk menggunakan Google Docs API secara efektif, Anda harus memahami arsitektur dokumen Google Dokumen dan elemen-elemen yang membentuk sebuah dokumen, serta hubungan di antara keduanya. Halaman ini memberikan ringkasan mendetail tentang topik berikut:
- Model konseptual dari elemen dokumen
- Cara Docs API menampilkan elemen ini
- Properti gaya visual elemen
Elemen tingkat atas
Elemen penampung terluar di Google Dokumen adalah dokumen. Ini adalah unit yang dapat disimpan di Google Drive, dibagikan dengan pengguna lain, dan diperbarui dengan teks dan gambar.
Elemen level teratas resource documents
mencakup 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 Anda, atau mungkin ingin Anda, gunakan secara terprogram adalah elemen dalam
konten Body
:
Elemen struktural
StructuralElement
menjelaskan konten yang menyediakan struktur ke 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. Hal ini mencakup teks, gambar inline, dan pemformatan.
Struktur paragraf
Paragraph
adalah
StructuralElement
yang mewakili paragraf. Memiliki berbagai konten yang
diakhiri dengan karakter baris baru. Terdiri dari objek-objek berikut ini:
ParagraphElement
: Mendeskripsikan konten dalam sebuah 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:
Untuk contoh struktur dokumen yang lengkap, lihat contoh dokumen dalam format JSON. Dalam output, Anda bisa melihat banyak elemen struktural dan konten utama, serta penggunaan indeks awal dan akhir seperti yang dijelaskan di bagian berikut.
Text berjalan
TextRun
adalah
ParagraphElement
yang mewakili string teks yang berdekatan dengan semua gaya teks yang sama. Satu
paragraf dapat berisi beberapa aliran teks, tetapi aliran teks tidak pernah melintasi batas
paragraf. Konten dibagi setelah karakter newline untuk membentuk teks
terpisah. Misalnya, pertimbangkan dokumen kecil seperti berikut:
Diagram berikut menunjukkan cara memvisualisasikan urutan paragraf
dalam dokumen sebelumnya, masing-masing dengan setelan TextRun
dan Bullet
opsionalnya sendiri.
AutoText
AutoText
adalah
ParagraphElement
yang mewakili tempat dalam teks yang secara dinamis diganti
dengan konten yang dapat berubah dari waktu ke waktu. Di Dokumen, ini digunakan
untuk nomor halaman.
Indeks awal dan akhir
Saat Anda memperbarui konten dokumen, setiap pembaruan akan dilakukan 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 suatu segmen bersifat relatif terhadap awal segmen tersebut.
Sebagian besar elemen dalam konten isi memiliki properti startIndex
dan
endIndex
berbasis nol. Ini menunjukkan offset awal dan akhir elemen, relatif terhadap awal segmen yang mencakupnya. Untuk informasi selengkapnya
tentang cara mengurutkan panggilan Docs API batch Anda, lihat Update
batch.
Indeks diukur dalam unit kode UTF-16. Artinya pasangan surrogate menggunakan
dua indeks. Misalnya, emoji "GRINNING FACE", HELP, direpresentasikan sebagai \uD83D\uDE00
dan menggunakan dua indeks.
Untuk elemen dalam isi dokumen, indeks merepresentasikan offset dari awal konten isi, yaitu elemen "root".
Jenis "mempersonalisasi" untuk elemen
struktural—SectionBreak
,
TableOfContents
,
Table
, dan
Paragraph
—tidak memiliki indeks ini karena
StructuralElement
yang menyertakannya 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 konten elemen 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. Selanjutnya, Anda dapat mengurai JSON yang dihasilkan untuk menemukan nilai setiap elemen. Untuk mengetahui informasi selengkapnya, lihat Output
isi dokumen sebagai JSON.
Mengurai 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 dalam diagram berikut:
Karena tidak ada metode untuk membaca setelan ini secara eksplisit, aplikasi Anda harus mendapatkan seluruh dokumen, lalu mengurai JSON untuk mengekstrak nilai ini.
Warisan properti
StructuralElement
dapat mewarisi properti dari objek induknya. Properti objek, termasuk yang didefinisikan dan 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.
Pemformatan paragraf menentukan cara blok teks dirender dalam dokumen,
seperti perataan, batas, dan indentasi. Format yang Anda terapkan
akan menggantikan format default yang diwarisi dari ParagraphStyle
pokok.
Sebaliknya, fitur pemformatan yang tidak Anda tetapkan akan terus mewarisi dari gaya paragraf.