Google Docs API memungkinkan Anda mengakses konten dari tab mana pun dalam dokumen.
Apa yang dimaksud dengan tab?
Google Dokumen memiliki lapisan organisasi yang disebut tab. Dokumen memungkinkan pengguna membuat satu atau beberapa tab dalam satu atau beberapa tab dokumen, mirip dengan tab yang ada di Spreadsheet saat ini. Setiap tab memiliki judul dan ID (ditambahkan dalam URL). Tab juga dapat memiliki tab turunan, yaitu tab yang bertingkat di bawah tab lain.
Dukungan API untuk tab turunan tersedia saat ini, tetapi dukungan UI akan segera hadir. Anda dapat menangani tab turunan dalam kode Anda hari ini sehingga saat dukungan UI diluncurkan Anda tidak perlu melakukan pembaruan kode lebih lanjut.
Perubahan struktural pada cara konten dokumen direpresentasikan dalam Resource Dokumen
Di masa lalu, dokumen tidak memiliki konsep tab, jadi
Document
Referensi yang terdapat secara langsung
semua konten teks melalui kolom berikut:
document.body
document.headers
document.footers
document.footnotes
document.documentStyle
document.suggestedDocumentStyleChanges
document.namedStyles
document.suggestedNamedStylesChanges
document.lists
document.namedRanges
document.inlineObjects
document.positionedObjects
Dengan hierarki struktural tambahan pada tab, kolom ini tidak lagi
merepresentasikan konten teks secara semantik dari semua tab dalam dokumen. Tujuan
konten berbasis teks sekarang
direpresentasikan dalam lapisan berbeda. Properti tab dan
konten di Google Dokumen
dapat diakses dengan
document.tabs
, yang merupakan daftar
Objek Tab
, yang masing-masing
berisi semua isian konten teks yang disebutkan di atas. Bagian selanjutnya memberikan
ikhtisar singkat; tindakan
Representasi JSON tab
juga memberikan informasi
yang lebih rinci.
Mengakses properti Tab
Akses properti tab menggunakan
tab.tabProperties
,
yang mencakup informasi seperti ID, judul, dan posisi tab.
Mengakses konten teks dalam Tab
Konten dokumen aktual dalam tab
ditampilkan sebagai
tab.documentTab
Semua
kolom konten teks yang disebutkan di atas dapat diakses menggunakan tab.documentTab
.
Misalnya, daripada menggunakan document.body
, Anda harus menggunakan
document.tabs[indexOfTab].documentTab.body
.
Hierarki tab
Tab turunan direpresentasikan di API sebagai
Kolom tab.childTabs
di
Tab
Mengakses semua tab di
dokumen memerlukan melintasi "pohon" tab turunan. Misalnya, pertimbangkan
dokumen yang berisi hierarki tab sebagai berikut:
Untuk mengambil Body
dari Tab 3.1.2, Anda akan mengakses
document.tabs[2].childTabs[0].childTabs[1].documentTab.body
. Lihat contohnya
blok kode di bagian selanjutnya, yang menyediakan kode contoh untuk diiterasi
di semua tab
dalam suatu dokumen.
Perubahan pada metode
Dengan diperkenalkannya tab, masing-masing metode dokumen memiliki beberapa perubahan yang mungkin mengharuskan Anda untuk memperbarui kode.
documents.get
Secara default, tidak semua konten tab ditampilkan. Developer harus memperbarui
kode untuk mengakses semua tab. Tujuan
Metode documents.get
menampilkan
parameter includeTabsContent
yang memungkinkan konfigurasi apakah konten dari
semua tab disediakan
dalam respons.
- Jika
includeTabsContent
disetel ketrue
, Metodedocuments.get
akan ditampilkan ResourceDocument
dengan Kolomdocument.tabs
diisi. Semua kolom teks langsung didocument
(misalnya,document.body
) akan dibiarkan kosong. - Jika
includeTabsContent
tidak diberikan, kolom teks di ResourceDocument
(misalnya,document.body
) hanya akan diisi dengan konten dari tab pertama. Kolomdocument.tabs
akan kosong dan konten dari tab lain tidak akan ditampilkan.
documents.create
Metode documents.create
menampilkan Resource Document
merepresentasikan dokumen kosong yang dibuat. Resource
Document
yang ditampilkan akan mengisi
konten dokumen kosong di kolom konten teks dokumen serta
document.tabs
.
document.batchUpdate
Setiap Request
menyertakan
cara untuk menentukan tab untuk
menerapkan pembaruan. Secara {i>default<i}, jika tab tidak
tersebut,
Request
akan paling banyak
kasus diterapkan ke
tab pertama dalam dokumen.
ReplaceAllTextRequest
,
DeleteNamedRangeRequest
,
dan
ReplaceNamedRangeContentRequest
adalah tiga permintaan khusus yang secara default akan diterapkan ke semua tab.
Lihat
Request
dokumentasi yang spesifik.
Perubahan pada link internal
Pengguna dapat membuat link internal ke tab, bookmark, dan judul dalam dokumen.
Dengan diperkenalkannya fitur tab, link.bookmarkId
dan
link.headingId
kolom di
Resource Link
tidak dapat lagi
menunjukkan {i>bookmark<i} atau {i>heading<i} di tab tertentu dalam dokumen.
Developer harus memperbarui kodenya untuk menggunakan link.bookmark
dan
link.heading
dalam operasi baca dan tulis. Fitur ini mengekspos link internal menggunakan
BookmarkLink
dan
Objek HeadingLink
, masing-masing
berisi ID bookmark atau heading dan ID tab letaknya
inc. Selain itu, link.tabId
mengekspos link internal ke tab.
Menautkan konten documents.get
respons juga dapat bervariasi bergantung pada parameter includeTabsContent
:
- Jika
includeTabsContent
disetel ketrue
, semua link internal akan ditampilkan sebagailink.bookmark
danlink.heading
. Kolom lama tidak akan digunakan lagi. - Jika
includeTabsContent
tidak diberikan, maka dalam dokumen yang berisi tab tunggal, link internal apa pun ke bookmark atau judul dalam tab tunggal tersebut terus ditampilkan sebagailink.bookmarkId
danlink.headingId
. Dalam dokumen yang berisi beberapa tab, link internal akan ditampilkan sebagailink.bookmark
danlink.heading
.
Di document.batchUpdate
,
jika link internal dibuat menggunakan salah satu kolom lama, bookmark atau
akan dianggap berasal dari ID tab yang ditentukan dalam
Request
Jika tidak ada tab yang
tertentu, maka akan dianggap berasal dari {i>tab<i} pertama dalam dokumen.
Tujuan Representasi JSON link memberikan informasi yang lebih terperinci.
Pola penggunaan umum untuk tab
Contoh kode berikut menjelaskan berbagai cara berinteraksi dengan tab.
Membaca konten tab dari semua tab dalam dokumen
Kode lama yang melakukan hal ini sebelum fitur tab dapat dimigrasikan ke dukungan
tab dengan menyetel parameter includeTabsContent
ke true
, yang menelusuri
hierarki tab, dan memanggil metode pengambil dari
Tab
dan
DocumentTab
, bukan
Document
. Parsial berikut
contoh kode didasarkan pada cuplikan di
Ekstrak teks dari dokumen. Menunjukkan
cara mencetak semua isi teks
dari setiap tab dalam dokumen. Tab ini
kode traversal dapat diadaptasikan untuk banyak kasus penggunaan lain yang tidak terlalu penting
struktur tab yang sebenarnya.
Java
/** Prints all text contents from all tabs in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from each tab in the document. for (Tab tab: allTabs) { // Get the DocumentTab from the generic Tab. DocumentTab documentTab = tab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); } } /** * Returns a flat list of all tabs in the document in the order they would * appear in the UI (top-down ordering). Includes all child tabs. */ private List<Tab> getAllTabs(Document doc) { List<Tab> allTabs = new ArrayList<>(); // Iterate over all tabs and recursively add any child tabs to generate a // flat list of Tabs. for (Tab tab: doc.getTabs()) { addCurrentAndChildTabs(tab, allTabs); } return allTabs; } /** * Adds the provided tab to the list of all tabs, and recurses through and * adds all child tabs. */ private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) { allTabs.add(tab); for (Tab tab: tab.getChildTabs()) { addCurrentAndChildTabs(tab, allTabs); } } /** * Recurses through a list of Structural Elements to read a document's text * where text may be in nested elements. * * <p>For a code sample, see * <a href="https://developers.google.com/docs/api/samples/extract-text">Extract * the text from a document</a>. */ private static String readStructuralElements(List<StructuralElement> elements) { ... }
Membaca konten tab dari tab pertama dalam dokumen
Fungsi ini mirip dengan membaca semua tab.
Java
/** Prints all text contents from the first tab in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from the first tab in the document. Tab firstTab = allTabs.get(0); // Get the DocumentTab from the generic Tab. DocumentTab documentTab = firstTab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); }
Membuat Permintaan untuk memperbarui tab pertama
Contoh kode parsial berikut menunjukkan cara menargetkan tab tertentu dalam
Request
Kode ini
didasarkan pada sampel dalam
Panduan Menyisipkan, menghapus, dan memindahkan teks.
Java
/** Inserts text into the first tab of the document. */ static void insertTextInFirstTab(Docs service, String documentId) throws IOException { // Get the first tab's ID. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); Tab firstTab = doc.getTabs().get(0); String tabId = firstTab.getTabProperties().getTabId(); List<Request>requests = new ArrayList<>(); requests.add(new Request().setInsertText( new InsertTextRequest().setText(text).setLocation(new Location() // Set the tab ID. .setTabId(tabId) .setIndex(25)))); BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests); BatchUpdateDocumentResponse response = docsService.documents().batchUpdate(DOCUMENT_ID, body).execute(); }