Bekerja dengan tab

Google Docs API memungkinkan Anda mengakses konten dari tab mana pun dalam dokumen.

Apa itu tab?

Google Dokumen memiliki lapisan organisasi yang disebut tab. Dokumen memungkinkan pengguna membuat satu atau beberapa tab dalam satu dokumen, mirip dengan cara kerja tab di Spreadsheet saat ini. Setiap tab memiliki judul dan ID-nya sendiri (ditambahkan di URL). Tab juga dapat memiliki tab turunan, yaitu tab yang bertingkat di bawah tab lain.

Perubahan struktural pada cara konten dokumen ditampilkan di Resource Dokumen

Sebelumnya, dokumen tidak memiliki konsep tab, sehingga Resource Document secara langsung berisi semua konten teks melalui kolom berikut:

Dengan hierarki struktural tambahan tab, kolom ini tidak lagi secara semantik merepresentasikan konten teks dari semua tab dalam dokumen. Konten berbasis teks kini ditampilkan di lapisan yang berbeda. Properti dan konten tab di Google Dokumen dapat diakses dengan document.tabs, yang merupakan daftar objek Tab, yang masing-masing berisi semua kolom konten teks yang disebutkan di atas. Bagian selanjutnya memberikan ringkasan singkat; Tab JSON representation juga memberikan informasi yang lebih mendetail.

Mengakses properti Tab

Akses properti tab menggunakan tab.tabProperties, yang mencakup informasi seperti ID, judul, dan posisi tab.

Mengakses konten teks dalam Tab

Isi dokumen sebenarnya dalam tab ditampilkan sebagai tab.documentTab. Semua kolom konten teks yang disebutkan di atas dapat diakses menggunakan tab.documentTab. Misalnya, Anda harus menggunakan document.tabs[indexOfTab].documentTab.body, bukan document.body.

Hierarki tab

Tab turunan direpresentasikan dalam API sebagai kolom tab.childTabs di Tab. Mengakses semua tab dalam dokumen memerlukan penelusuran "pohon" tab turunan. Misalnya, pertimbangkan dokumen yang berisi hierarki tab sebagai berikut:

UI Tablist yang berisi tiga tab tingkat teratas, beberapa di antaranya memiliki tab turunan

Untuk mengambil Body dari Tab 3.1.2, Anda akan mengakses document.tabs[2].childTabs[0].childTabs[1].documentTab.body. Lihat blok kode contoh di bagian selanjutnya, yang menyediakan kode contoh untuk melakukan iterasi di semua tab dalam dokumen.

Perubahan pada metode

Dengan diperkenalkannya tab, setiap metode dokumen memiliki beberapa perubahan yang mungkin mengharuskan Anda memperbarui kode.

documents.get

Secara default, tidak semua konten tab ditampilkan. Developer harus memperbarui kode mereka untuk mengakses semua tab. Metode documents.get mengekspos parameter includeTabsContent yang memungkinkan konfigurasi apakah konten dari semua tab disediakan dalam respons.

  • Jika includeTabsContent disetel ke true, metode documents.get akan menampilkan Resource Document dengan kolom document.tabs diisi. Semua kolom teks langsung di document (misalnya, document.body) akan dibiarkan kosong.
  • Jika includeTabsContent tidak diberikan, kolom teks di Resource Document (misalnya, document.body) akan diisi dengan konten dari tab pertama saja. Kolom document.tabs akan kosong dan konten dari tab lain tidak akan ditampilkan.

documents.create

Metode documents.create menampilkan Resource Document yang merepresentasikan dokumen kosong yang dibuat. Resource Document yang ditampilkan akan mengisi konten dokumen yang kosong di kolom konten teks dokumen serta document.tabs.

document.batchUpdate

Setiap Request mencakup cara untuk menentukan tab yang akan diterapkan update-nya. Secara default, jika tab tidak ditentukan, Request dalam sebagian besar kasus akan diterapkan ke tab pertama dalam dokumen. ReplaceAllTextRequest, DeleteNamedRangeRequest, dan ReplaceNamedRangeContentRequest adalah tiga permintaan khusus yang akan diterapkan ke semua tab secara default.

Lihat dokumentasi Requests untuk mengetahui detailnya.

Pengguna dapat membuat link internal ke tab, bookmark, dan heading dalam dokumen. Dengan diperkenalkannya fitur tab, kolom link.bookmarkId dan link.headingId dalam resource Link tidak dapat lagi merepresentasikan bookmark atau heading di tab tertentu dalam dokumen.

Developer harus memperbarui kode mereka untuk menggunakan link.bookmark dan link.heading dalam operasi baca dan tulis. Link internal ditampilkan menggunakan objek BookmarkLink dan HeadingLink, yang masing-masing berisi ID penanda atau judul dan ID tab tempatnya berada. Selain itu, link.tabId mengekspos link internal ke tab.

Isi link respons documents.get juga dapat bervariasi bergantung pada parameter includeTabsContent:

  • Jika includeTabsContent disetel ke true, semua link internal akan ditampilkan sebagai link.bookmark dan link.heading. Kolom lama tidak akan digunakan lagi.
  • Jika includeTabsContent tidak diberikan, maka dalam dokumen yang berisi satu tab, semua link internal ke bookmark atau judul dalam satu tab tersebut akan terus ditampilkan sebagai link.bookmarkId dan link.headingId. Dalam dokumen yang berisi beberapa tab, link internal akan ditampilkan sebagai link.bookmark dan link.heading.

Di document.batchUpdate, jika link internal dibuat menggunakan salah satu kolom lama, penanda atau judul akan dianggap berasal dari ID tab yang ditentukan dalam Request. Jika tidak ada tab yang ditentukan, tab tersebut akan dianggap berasal dari tab pertama dalam dokumen.

Representasi JSON Link memberikan informasi yang lebih mendetail.

Pola penggunaan umum untuk tab

Contoh kode berikut menjelaskan berbagai cara berinteraksi dengan tab.

Membaca konten tab dari semua tab dalam dokumen

Kode yang ada yang melakukan hal ini sebelum fitur tab dapat dimigrasikan untuk mendukung tab dengan menetapkan parameter includeTabsContent ke true, melintasi hierarki struktur tab, dan memanggil metode getter dari Tab dan DocumentTab, bukan Document. Contoh kode parsial berikut didasarkan pada cuplikan di Mengekstrak teks dari dokumen. Bagian ini menunjukkan cara mencetak semua konten teks dari setiap tab dalam dokumen. Kode penelusuran tab ini dapat diadaptasi untuk banyak kasus penggunaan lain yang tidak memedulikan 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/workspace/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

Hal 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 di Request. Kode ini didasarkan pada contoh 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();
}