Apps Script dla Dokumentów Google pozwala uzyskać dostęp do materiałów w dokumencie.
Co to są karty?
Dokumenty Google zawierają warstwę organizacyjną zwaną kartami. Dokumenty, umożliwia użytkownikom tworzenie jednej lub kilku kart w jednym dokumencie, podobnie jak Liczba kart w Arkuszach: Każda karta ma własny tytuł i identyfikator (dołączony w adresie URL). Karta może też mieć karty podrzędne, czyli zagnieżdżone karty. poniżej innej karty.
Obsługa interfejsów API w kartach podrzędnych jest obecnie dostępna, ale wkrótce będzie też można korzystać z interfejsu użytkownika. Już dziś możesz zapewnić obsługę kart podrzędnych w kodzie, aby po wprowadzeniu obsługi interfejsu użytkownika nie musisz aktualizować kodu.
Dostęp do kart
Właściwości i zawartość karty są dostępne przy użyciu:
Document.getTabs()
, która zwraca listę Tab
. Późniejsze sekcje zawierają krótkie omówienie
Zajęcia: Tab
; dokumentację zajęć Tab
zawiera też bardziej szczegółowe informacje.
Właściwości karty
Właściwości karty można pobrać za pomocą takich metod jak:
Tab.getId()
i
Tab.getTitle()
Zawartość karty
Zawartość dokumentów z każdej karty można pobrać za pomocą
Tab.asDocumentTab()
Zmiany w strukturze klasy dokumentu
.
Hierarchia kart
Karty podrzędne są widoczne w Google Apps Script przez
Tab.getChildTabs()
Dostęp do treści ze wszystkich kart wymaga przemierzania „drzewa” kart podrzędnych.
Weźmy na przykład taki dokument, który zawiera taką hierarchię kart:
Aby otworzyć kartę 3.1.2, wykonaj te czynności:
// 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());
Zapoznaj się z przykładowymi blokami kodu w dalszych sekcjach, które zawierają przykładowy kod na wszystkich kartach w dokumencie.
Inne sposoby pobierania kart
Istnieją 2 inne sposoby pobierania kart:
Document.getTab(tabId)
: Zwraca kartę o określonym identyfikatorze.Document.getActiveTab()
: Zwraca aktywną kartę użytkownika. Działa tylko w tych krajach: skryptów powiązanych z dokumentem. omówiono to bardziej szczegółowo w dalszej części tego artykułu.
Zmiany w strukturze klas dokumentu
W przeszłości w dokumentach brak było kart, więc klasa dokumentu ujawnione metody bezpośredniego dostępu do tekstu dokumentu i modyfikowania go. Do tej kategorii należą następujące metody:
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()
Dzięki dodatkowej hierarchii strukturalnej kart metody te nie są już
semantycznie przedstawiają treść tekstową ze wszystkich kart w dokumencie. Tekst
treści będą teraz reprezentowane w innej warstwie, wszystkie wspomniane wyżej
metody tekstowe są dostępne w usłudze DocumentTab
.
Te istniejące metody w klasie Document
będą uzyskiwać dostęp do treści lub je modyfikować
z aktywnej karty (w skryptach powiązanych z
określonego dokumentu) lub pierwszej karty (jeśli aktywna jest niedostępna).
Uzyskiwanie dostępu do tekstu na określonej karcie
Zamiast metod tekstowych z Document
zalecamy użycie
metod, które są dostępne poza klasą DocumentTab
(czyli
dostępne w
Tab.asDocumentTab()
.
). Na przykład:
// 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());
Zmiany dotyczące wyboru użytkowników
Metody zaznaczania tekstu
Klasa Document
udostępnia moduły pobierania i seterów, które pozwalają określić miejsce w tekście
wybranego przez użytkownika w aktywnym dokumencie. Te metody działają w
kontekst aktywnej karty użytkownika, który uruchamia skrypt.
Document.getCursor()
: Zwraca pozycję kursora użytkownika na karcie aktywnej.Document.getSelection()
: Zwraca zakres wyboru użytkownika na karcie aktywnej.Document.setCursor(position)
: Ustawia pozycję kursora użytkownika w aktywnym dokumencie. Jeśli Pozycja jest nieaktywna karta, aktywna karta użytkownika jest przenoszona na powiązaną kartę z daną pozycją.Document.setSelection(range)
: Określa zakres wyboru użytkownika w aktywnym dokumencie. Jeśli Zakres jest wartością nieaktywna karta, aktywna karta użytkownika jest przenoszona na powiązaną kartę z danym Zakresem.
Metody wyboru kart i przypadki użycia
Dzięki wprowadzeniu kart można pobrać i ustawić aktywną kartę użytkownik uruchamiający skrypt. Można to zrobić za pomocą następujących metod:
Document.getActiveTab()
: Zwraca aktywny elementTab
użytkownika w aktywnym dokumencie.Document.setActiveTab(tabId)
: Ustawia elementTab
wybrany przez użytkownika w bieżącym dokumencie na kartę z określony identyfikator.
Całościowy „wybór” użytkownika składa się z aktywnej karty wraz z bieżącą pozycją kursora lub zakresem zaznaczenia. Obie wzorcem do pracy z aktywnym zaznaczeniem jest albo jawne zmodyfikowanie użytkownika na określoną kartę lub użyj aktywnej karty użytkownika.
Jednoznaczną zmianę aktywnej karty użytkownika można użyć za pomocą
Document.setActiveTab(tabId)
Możesz też zadzwonić
Document.setCursor(position)
lub Document.setSelection(range)
z kartą Position
lub Range
z nieaktywnej karty spowoduje, że ta karta będzie nowa
aktywne.
Czy zamierzonym działaniem skryptu jest użycie aktywnej karty użytkownika
bez zmiany,
Document.setActiveTab(tabId)
nie jest konieczne.
Document.getCursor()
i Document.getSelection()
będą już działać na aktywnej karcie, w zależności od karty,
użytkownik uruchomił skrypt.
Pamiętaj, że dokument nie obsługuje wielu opcji wyboru kart ani wielu elementów.
położenie lub zakresy na różnych kartach. Dlatego korzystając z funkcji
Document.setActiveTab(tabId)
spowoduje wyczyszczenie poprzedniej pozycji kursora lub zakresu zaznaczenia.
Metody określania pozycji i zakresu na określonej karcie
To właśnie konkretna karta nadaje znaczenie koncepcjom wyboru tekstu
Position
i Range
. Innymi słowy, pozycja kursora lub zakres zaznaczenia
mają znaczenie tylko wtedy, gdy skrypt zna konkretną kartę, na której położenie lub
mieści się w zakresie.
Jest to możliwe dzięki
DocumentTab.newPosition(element, offset)
i
DocumentTab.newRange()
które tworzą pozycję lub zakres ukierunkowany na określoną wartość
DocumentTab
, z którego jest wywoływana metoda. W przeciwieństwie do tego:
Document.newPosition(element, offset)
i Document.newRange()
utworzy Pozycja lub Zakres kierowany na aktywną kartę (albo
, jeśli skrypt nie jest powiązany).
Zapoznaj się z przykładowymi blokami kodu w dalszych sekcjach, które zawierają przykładowy kod pracy z zaznaczonymi elementami.
Typowe wzorce używania kart
Poniżej znajduje się przykładowy kod opisujący różne sposoby korzystania z kart.
Odczytywanie zawartości wszystkich kart w dokumencie
Dotychczasowy kod, który to umożliwiał, zanim funkcja kart została przeniesiona do obsługi
kart, przechodząc przez drzewo kart i wywołując metody pobierania z interfejsów Tab
oraz
DocumentTab
zamiast Document
. Poniższy przykładowy fragment kodu pokazuje,
, aby wydrukować całą zawartość tekstu z każdej karty w dokumencie. Ta karta
który można dostosować do wielu innych zastosowań,
rzeczywistej struktury kart.
/** 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); } }
Odczytywanie zawartości pierwszej karty w dokumencie
Przypomina to odczytywanie wszystkich kart.
/** * 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()); }
Zaktualizuj zawartość pierwszej karty
Poniższy przykładowy częściowy kod pokazuje, jak kierować reklamy na określoną kartę podczas tworzenia aktualizacje.
/** 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(); }
Zaktualizuj zawartość aktywnej lub wybranej karty
Poniższy przykładowy częściowy kod pokazuje, jak ustawić kierowanie na aktywną kartę podczas tworzenia aktualizacje.
/** * 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(); }
Ustaw pozycję kursora lub zakres zaznaczenia na aktywnej karcie
Poniżej znajduje się przykładowy częściowy kod pokazujący, jak zaktualizować pozycję kursora lub parametr zakresu zaznaczenia na aktywnej karcie użytkownika. To dotyczy tylko w powiązaniach skryptów.
/** * 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()); }
Ustawianie aktywnej lub wybranej karty
Poniższy przykładowy częściowy kod pokazuje, jak zmienić aktywną kartę użytkownika. Dotyczy to tylko powiązanych skryptów.
/** * 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()); } }