Praca z kartami

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:

Interfejs listy kart obejmujący 3 karty najwyższego poziomu, z których część zawiera karty podrzędne

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:

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:

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:

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żej znajduje się przykładowy fragment kodu, który 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żej znajduje się przykładowy częściowy kod pokazujący, 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());
  }
}