Untuk menggunakan Google Docs API secara efektif, Anda harus memahami arsitektur dokumen Google Dokumen dan elemen-elemen yang membentuk dokumen, serta hubungan di antaranya. Halaman ini menyediakan ikhtisar terperinci 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 yang dapat disimpan di Google Drive, dibagikan dengan pengguna lain, dan diperbarui dengan teks dan gambar.
Elemen tingkat atas documents
resource mencakup Tab
-nya,
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 dari kolom berikut:
TabProperties
: Berisi atribut tab seperti ID, judul, dan indeks.childTabs
: Mengekspos tab turunan tab (tab yang disusun bertingkat secara langsung di bawahnya).DocumentTab
: Menampilkan konten teks tab.
Bagian selanjutnya memberikan gambaran singkat tentang hierarki tab dokumen; tindakan Representasi JSON tab juga memberikan informasi yang lebih rinci. Lihat Bekerja dengan Tab untuk informasi selengkapnya tentang fitur tab.
Untuk memanipulasi fitur tab dokumen global di luar konten Body
,
hampir selalu lebih baik jika menggunakan satu atau
lebih {i>template<i} dokumen, yang dapat Anda gunakan sebagai
dasar untuk menghasilkan dokumen baru secara terprogram. Untuk informasi selengkapnya, lihat
Menggabungkan teks menjadi dokumen.
Konten isi
Body
biasanya berisi seluruh konten tab dokumen. Sebagian besar
item yang dapat, atau mungkin ingin, gunakan secara terprogram adalah elemen dalam
konten Body
:
Elemen struktural
StructuralElement
menjelaskan konten yang memberikan struktur pada dokumen. Konten Body
urutan objek StructuralElement
. Elemen konten mempersonalisasi setiap elemen
Objek StructuralElement
, seperti yang ditunjukkan dalam diagram berikut:
Elemen struktural dan objek isinya berisi semua komponen visual di dalam dokumen. Hal ini mencakup teks, gambar inline, dan pemformatan.
Struktur paragraf
Paragraph
adalah
StructuralElement
yang mewakili paragraf. Data ini memiliki berbagai macam konten yang
diakhiri dengan karakter baris baru. Terdiri dari objek-objek berikut ini:
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 menyediakan poin spesifikasi pendukung.
ParagraphElement
berfungsi seperti StructuralElement
. Satu set
jenis elemen konten (seperti
ColumnBreak
dan
Equation
) mempersonalisasi
ParagraphElement
, seperti yang ditampilkan dalam diagram berikut:
Untuk contoh struktur dokumen yang lengkap, lihat dokumentasi contoh dalam format JSON. Pada output, Anda bisa melihat banyak elemen struktural dan konten utama, serta penggunaan awal dan indeks akhir seperti yang dijelaskan di bagian berikut.
Text berjalan
TextRun
adalah
ParagraphElement
yang mewakili string teks yang berdekatan dengan semua gaya teks yang sama. J
paragraf dapat berisi beberapa aliran teks, tetapi aliran teks tidak pernah melintasi paragraf
batasan data. Konten dibagi setelah karakter baris baru untuk membentuk teks terpisah
yang dijalankan. Misalnya, pertimbangkan dokumen kecil seperti berikut:
Diagram berikut menunjukkan cara memvisualisasikan urutan paragraf
dalam dokumen sebelumnya, masing-masing dengan TextRun
dan Bullet
opsionalnya
setelan.
AutoText
AutoText
adalah
ParagraphElement
yang mewakili tempat dalam teks yang diganti secara dinamis
dengan konten yang dapat berubah seiring waktu. Di Dokumen, ini digunakan untuk
nomor halaman.
Indeks awal dan akhir
Saat Anda membuat pembaruan pada konten {i>tab<i} dokumen, setiap pembaruan akan ditempatkan di suatu lokasi atau di seluruh rentang dalam dokumen. Lokasi-lokasi ini dan rentang ditentukan menggunakan indeks, yang mewakili offset dalam dokumen yang berisi segmen. Segmen adalah {i>body<i}, {i>header<i}, {i>footer<i}, 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 startIndex
berbasis nol dan
Properti endIndex
. Ini menunjukkan {i>offset <i}dari awal dan
akhir, relatif terhadap awal segmen yang mencakupnya. Untuk informasi selengkapnya
tentang cara mengurutkan panggilan Docs API batch Anda, lihat Batch
update Google.
Indeks diukur dalam unit kode UTF-16. Ini berarti pasangan surrogate menggunakan
dua indeks. Misalnya, "Wajah GRINNING" emoji, Match, direpresentasikan sebagai
\uD83D\uDE00
dan menggunakan dua indeks.
Untuk elemen di dalam isi dokumen, indeks merepresentasikan offset dari awal dari isi {i>body<i}, yang merupakan "{i>root<i}" .
"Personalisasi" jenis untuk struktural
elemen—SectionBreak
,
TableOfContents
,
Table
, dan
Paragraph
—tidak memiliki indeks ini karena enkapsulasi
StructuralElement
memiliki kolom ini. Hal ini juga berlaku
untuk personalisasi
jenis yang terdapat dalam ParagraphElement
, seperti TextRun
, AutoText
, dan
PageBreak
Elemen akses
Banyak elemen yang dapat diubah dengan
documents.batchUpdate
. Misalnya, menggunakan
InsertTextRequest
,
Anda dapat mengubah isi elemen
apa pun yang berisi teks. Demikian pula, Anda dapat
penggunaan
UpdateTextStyleRequest
untuk menerapkan pemformatan ke rentang teks yang terkandung dalam satu atau beberapa elemen.
Untuk membaca elemen dokumen, gunakan
documents.get
untuk mendapatkan
Dump JSON dokumen lengkap. Anda kemudian dapat mengurai JSON yang dihasilkan untuk
menemukan nilai dari elemen individu. Untuk informasi selengkapnya, lihat Output
isi dokumen sebagai JSON.
Mengurai konten dapat bermanfaat untuk berbagai kasus penggunaan. Pertimbangkan, untuk misalnya, aplikasi pembuatan katalog yang mencantumkan dokumen yang ditemukannya. Aplikasi ini dapat mengekstrak judul, ID revisi, dan nomor halaman awal dokumen tab, seperti yang ditunjukkan dalam diagram berikut:
Karena tidak ada metode untuk membaca setelan ini secara eksplisit, aplikasi Anda memerlukan untuk mendapatkan seluruh dokumen, lalu mengurai JSON untuk mengekstrak nilai-nilai ini.
Warisan properti
StructuralElement
dapat mewarisi properti dari objek induknya. Channel
properti objek, termasuk yang didefinisikan
dan yang diwarisinya,
menentukan tampilan visual akhirnya.
Pemformatan karakter teks menentukan bagaimana teks dirender dalam dokumen, misalnya
tebal, miring, dan garis bawah. Format yang Anda terapkan menggantikan format default
format yang diwarisi dari atribut
TextStyle
Sebaliknya, setiap
karakter yang formatnya tidak Anda atur akan terus mewarisi dari
gaya paragraf.
Pemformatan paragraf menentukan bagaimana blok teks dirender dalam dokumen,
seperti {i>alignment<i}, {i>border<i}, dan {i>indent<i}. Format yang Anda terapkan
mengganti format default yang diwarisi dari ParagraphStyle
pokok.
Sebaliknya, setiap fitur pemformatan yang tidak Anda atur akan terus diwariskan
gaya paragraf.