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:
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:
Document.getTab(tabId)
: Menampilkan Tab dengan ID yang ditentukan.Document.getActiveTab()
: Menampilkan Tab aktif pengguna. Hanya berfungsi di skrip yang terikat dengan dokumen. Tujuan bagian selanjutnya menjelaskan ini secara lebih rinci.
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:
Document.addBookmark(position)
Document.addFooter()
Document.addHeader()
Document.addNamedRange(name, range)
Document.getBody()
Document.getBookmark(id)
Document.getBookmarks()
Document.getFooter()
Document.getFootnotes()
Document.getHeader()
Document.getNamedRangeById(id)
Document.getNamedRanges()
Document.getNamedRanges(name)
Document.newPosition(element, offset)
Document.newRange()
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:
Document.getActiveTab()
: MenampilkanTab
pengguna yang aktif di dokumen yang aktif.Document.setActiveTab(tabId)
: MenyetelTab
yang dipilih pengguna dalam dokumen saat ini ke tab dengan ID yang ditentukan.
"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 beberapa tab atau lebih
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()); } }