Bekerja dengan tab

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, yang tab yang disusun 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:

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

Mengakses 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:

UI daftar tab yang berisi tiga tab tingkat atas, 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 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 ke true, Metode documents.get akan ditampilkan 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) hanya akan diisi dengan konten dari tab pertama. Kolom document.tabs akan kosong dan konten dari tab lain tidak akan ditampilkan.

documents.create

Metode documents.create menampilkan Resource Document merepresentasikan dokumen kosong yang dibuat. URL yang dikembalikan Document Referensi akan mengisi isi dokumen kosong, baik di bidang isi teks pada dokumen maupun 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.

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 kode mereka untuk menggunakan link.bookmark dan link.heading dalam operasi baca dan tulis. Iklan 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 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 tab tunggal, link internal apa pun ke bookmark atau judul dalam tab tunggal tersebut 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, 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 mengupdate 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();
}