Struktur dokumen Google Dokumen

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.
Struktur tab dokumen.
Gambar 1. Struktur tab dokumen.

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:

Struktur konten isi.
Gambar 2. Struktur konten isi.

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.
Gambar 3. Elemen struktural.

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:

Struktur elemen paragraf.
Gambar 4. Struktur elemen paragraf.

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:

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

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

Struktur teks berjalan.
Gambar 6. Struktur teks berjalan.

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:

Struktur katalog dokumen.
Gambar 7. Struktur katalog dokumen.

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.