Bekerja dengan tab

Apps Script untuk Google Dokumen memungkinkan Anda mengakses konten dari tab dalam dokumen.

Apa yang dimaksud dengan tab?

Google Dokumen memiliki lapisan organisasi yang disebut tab. Dokumen memungkinkan pengguna untuk membuat satu atau beberapa tab dalam satu dokumen, mirip dengan sekarang ada tab di Spreadsheet. Setiap tab memiliki judulnya sendiri dan ID (ditambahkan di URL). Tab juga dapat memiliki tab turunan, yaitu tab yang disusun bertingkat di bawah tab lainnya.

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.

Tab Akses

Properti dan konten tab dapat diakses dengan Document.getTabs(), yang menampilkan daftar Tab. Bagian selanjutnya memberikan gambaran singkat tentang Class Tab; Dokumentasi class tab juga memberikan informasi yang lebih rinci.

Properti tab

Properti tab dapat diambil menggunakan metode seperti Tab.getId() dan Tab.getTitle().

Konten tab

Konten dokumen dalam setiap tab dapat diambil menggunakan Tab.asDocumentTab() Perubahan pada struktur Class Dokumen menjelaskan cara penggunaannya.

Hierarki tab

Tab turunan diekspos di Google Apps Script melalui Tab.getChildTabs() Untuk mengakses konten dari semua tab, Anda harus melewati "hierarki" tab turunan. Misalnya, perhatikan dokumen yang berisi hierarki tab seperti berikut:

UI daftar tab yang berisi tiga tab tingkat atas, beberapa di antaranya memiliki tab turunan

Untuk mengakses Tab 3.1.2, Anda dapat melakukan hal berikut:

// Print the ID of Tab 3.1.2.
const doc = DocumentApp.getActiveDocument();
const tab = doc.getTabs()[2].getChildTabs()[0].getChildTabs()[1];
console.log(tab.getId());

Lihat blok kode contoh di bagian selanjutnya, yang menyediakan kode contoh untuk melakukan iterasi di semua tab dalam sebuah dokumen.

Cara lain untuk mengambil tab

Ada dua cara lain untuk mengambil tab:

Perubahan pada struktur Class Dokumen

Dahulu, dokumen tidak memiliki konsep tab, sehingga Kelas Dokumen terbuka untuk mengakses dan mengubah isi teks dokumen secara langsung. Metode berikut termasuk dalam kategori ini:

Dengan hierarki struktural tambahan pada tab, metode ini tidak lagi merepresentasikan konten teks secara semantik dari semua tab dalam dokumen. Teks konten sekarang akan direpresentasikan dalam lapisan yang berbeda; semua hal yang disebutkan di atas metode teks dapat diakses melalui DocumentTab.

Metode yang sudah ada di class Document ini akan mengakses atau mengubah konten dari tab aktif (dalam skrip yang terikat ke dokumen tertentu) atau tab pertama (jika tidak ada yang aktif).

Mengakses konten teks dalam Tab tertentu

Daripada menggunakan metode teks dari Document, sebaiknya gunakan metode yang tersedia dari class DocumentTab (yang yang tersedia melalui Tab.asDocumentTab() ). Contoh:

// Print the text from the body of the active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const body = documentTab.getBody();
console.log(body.getText());

Perubahan pada pilihan pengguna

Metode pemilihan teks

Class Document menyediakan pengambil dan penyetel untuk mengelola posisi dalam teks dipilih pengguna, dalam dokumen aktif. Metode-metode ini beroperasi di dalam konteks tab aktif dari pengguna yang menjalankan skrip.

  • Document.getCursor(): Menampilkan posisi kursor pengguna di tab aktif.
  • Document.getSelection(): Menampilkan rentang pilihan pengguna di tab aktif.
  • Document.setCursor(position): Menetapkan posisi kursor pengguna di dokumen yang aktif. Jika Posisi berada di tab tidak aktif, tab aktif pengguna juga dialihkan ke tab yang terkait dengan Posisi tersebut.
  • Document.setSelection(range): Menetapkan rentang pilihan pengguna dalam dokumen aktif. Jika Rentang berada dalam kolom tab tidak aktif, tab aktif pengguna juga dialihkan ke tab yang terkait dengan Rentang tersebut.

Metode pemilihan tab dan kasus penggunaan

Dengan diperkenalkannya tab, mungkin berguna untuk mendapatkan dan mengatur tab aktif pengguna yang menjalankan skrip. Hal ini dapat dilakukan menggunakan metode berikut:

"Pemilihan" menyeluruh pengguna terdiri dari kombinasi tab aktif beserta posisi kursor atau rentang pilihan saat ini. Dua pola untuk bekerja dengan pilihan aktif adalah dengan memodifikasi secara eksplisit tab aktif pengguna ke tab tertentu atau gunakan tab aktif pengguna.

Mengubah tab aktif pengguna secara eksplisit dapat dilakukan dengan menggunakan Document.setActiveTab(tabId) Atau, memanggil Document.setCursor(position) atau Document.setSelection(range) dengan Position atau Range dari tab tidak aktif akan membuat tab tersebut menjadi baru aktif.

Jika perilaku skrip yang diinginkan adalah menggunakan tab aktif pengguna tanpa mengubahnya, maka Document.setActiveTab(tabId) tidak diperlukan. Tujuan Document.getCursor() dan Document.getSelection() akan beroperasi di tab aktif, berdasarkan tab yang tempat pengguna menjalankan skrip tersebut.

Perhatikan bahwa dokumen tidak mendukung pilihan lebih dari satu atau beberapa tab posisi atau rentang di berbagai tab. Oleh karena itu, menggunakan Document.setActiveTab(tabId) akan menghapus posisi kursor atau rentang pilihan sebelumnya.

Metode posisi dan rentang untuk Tab tertentu

{i>Tab<i} spesifik adalah elemen yang memberi makna pada konsep pemilihan teks dari Position dan Range. Dengan kata lain, posisi kursor atau rentang pilihan hanya berarti jika skrip mengetahui tab tertentu di mana posisi atau rentangnya dalam rentang.

Hal ini dicapai dengan menggunakan DocumentTab.newPosition(element, offset) dan DocumentTab.newRange() , yang menyusun Posisi atau Rentang yang menargetkan DocumentTab yang menjadi asal pemanggilan metode. Sebaliknya, Document.newPosition(element, offset) dan Document.newRange() akan membuat Posisi atau Rentang yang menargetkan tab aktif (atau tab pertama , jika skrip tidak terikat).

Lihat blok kode contoh di bagian selanjutnya, yang menyediakan kode contoh untuk bekerja dengan pilihan.

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 menelusuri hierarki tab dan memanggil metode pengambil dari Tab dan DocumentTab, bukan Document. Contoh kode parsial berikut menunjukkan cara untuk 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.

/** Logs all text contents from all tabs in the active document. */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs. DocumentApp.openById('abc123456') can also
  // be used instead of DocumentApp.getActiveDocument().
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from each tab in the document.
  for (const tab of allTabs) {
    // Get the DocumentTab from the generic Tab object.
    const documentTab = tab.asDocumentTab();
    // Get the body from the given DocumentTab.
    const body = documentTab.getBody();
    // Get the body text and log it to the console.
    console.log(body.getText());
  }
}

/**
 * Returns a flat list of all tabs in the document, in the order
 * they would appear in the UI (i.e. top-down ordering). Includes
 * all child tabs.
 */
function getAllTabs(doc) {
  const allTabs = [];
  // Iterate over all tabs and recursively add any child tabs to
  // generate a flat list of Tabs.
  for (const tab of 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.
 */
function addCurrentAndChildTabs(tab, allTabs) {
  allTabs.push(tab);
  for (const childTab of tab.getChildTabs()) {
    addCurrentAndChildTabs(childTab, allTabs);
  }
}

Membaca konten tab dari tab pertama dalam dokumen

Fungsi ini mirip dengan membaca semua tab.

/** 
 * Logs all text contents from the first tab in the active 
 * document. 
 */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs.
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from the first tab in the document.
  const firstTab = allTabs[0];
  // Get the DocumentTab from the generic Tab object.
  const documentTab = firstTab.asDocumentTab();
  // Get the body from the DocumentTab.
  const body = documentTab.getBody();
  // Get the body text and log it to the console.
  console.log(body.getText());
}

Perbarui konten tab di tab pertama

Contoh kode parsial berikut menunjukkan cara menargetkan tab tertentu saat melakukan pembaruan.

/** Inserts text into the first tab of the active document. */
function insertTextInFirstTab() {
  // Get the first tab's body.
  const doc = DocumentApp.getActiveDocument();
  const firstTab = doc.getTabs()[0];
  const firstDocumentTab = firstTab.asDocumentTab();
  const firstTabBody = firstDocumentTab.getBody();

  // Append a paragraph and a page break to the first tab's body
  // section.
  firstTabBody.appendParagraph("A paragraph.");
  firstTabBody.appendPageBreak();
}

Perbarui konten tab di tab yang aktif atau dipilih

Contoh kode parsial berikut menunjukkan cara menargetkan tab aktif saat melakukan pembaruan.

/**
 * Inserts text into the active/selected tab of the active
 * document.
 */
function insertTextInActiveTab() {
  // Get the active/selected tab's body.
  const doc = DocumentApp.getActiveDocument();
  const activeTab = doc.getActiveTab();
  const activeDocumentTab = activeTab.asDocumentTab();
  const activeTabBody = activeDocumentTab.getBody();

  // Append a paragraph and a page break to the active tab's body
  // section.
  activeTabBody.appendParagraph("A paragraph.");
  activeTabBody.appendPageBreak();
}

Menetapkan posisi kursor atau rentang pilihan di tab aktif

Contoh kode parsial berikut menunjukkan cara memperbarui posisi kursor atau rentang pilihan dalam tab aktif pengguna. Hal ini hanya relevan pada skrip.

/**
 * Changes the user's selection to select all tables within the tab
 * with the provided ID.
 */
function selectAllTables(tabId) {
  const doc = DocumentApp.getActiveDocument();
  const tab = doc.getTab(tabId);
  const documentTab = tab.asDocumentTab();

  // Build a range that encompasses all tables within the specified
  // tab.
  const rangeBuilder = documentTab.newRange();
  const tables = documentTab.getBody().getTables();
  for (let i = 0; i < tables.length; i++) {
    rangeBuilder.addElement(tables[i]);
  }
  // Set the document's selection to the tables within the specified
  // tab. Note that this actually switches the user's active tab as
  // well.
  doc.setSelection(rangeBuilder.build());
}

Setel tab aktif atau yang dipilih

Contoh kode parsial berikut menunjukkan cara mengubah tab aktif pengguna. Ini hanya relevan dalam skrip terikat.

/**
 * Changes the user's selected tab to the tab immediately following
 * the currently selected one. Handles child tabs.
 *
 * 
Only changes the selection if there is a tab following the
 * currently selected one.
 */
function selectNextTab() {
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);
  const activeTab = doc.getActiveTab();

  // Find the index of the currently active tab.
  let activeTabIndex = -1;
  for (let i = 0; i < allTabs.length; i++) {
    if (allTabs[i].getId() === activeTab.getId()) {
      activeTabIndex = i;
    }
  }

  // Update the user's selected tab if there is a valid next tab.
  const nextTabIndex = activeTabIndex + 1;
  if (nextTabIndex < allTabs.length) {
    doc.setActiveTab(allTabs[nextTabIndex].getId());
  }
}