Mit Tabs arbeiten

Mit Google Apps Script für Google Docs können Sie auf Inhalte von jedem Tab im Dokument zugreifen.

Was sind Tabs?

In Google Docs gibt es eine Organisationsebene namens Tabs. Nutzer können in einem einzelnen Dokument einen oder mehrere Tabs erstellen, ähnlich wie in Google Sheets. Jeder Tab hat einen eigenen Titel und eine ID (die an die URL angehängt wird). Ein Tab kann auch untergeordnete Tabs, die unter einem anderen Tab verschachtelt sind.

Auf Tabs zugreifen

Auf Tab-Eigenschaften und -Inhalte kann mit Document.getTabszugegriffen werden. Diese Methode gibt eine Liste von Tabs zurück. In den folgenden Abschnitten finden Sie eine kurze Übersicht über die Tab Klasse. In der Tab class documentation finden Sie außerdem detailliertere Informationen.

Tab-Eigenschaften

Tab-Eigenschaften können mit Methoden wie Tab.getId und Tab.getTitle abgerufen werden.

Tab-Inhalte

Dokumentinhalte auf jedem Tab können mit Tab.asDocumentTab abgerufen werden. Im Abschnitt Änderungen an der Struktur der Klasse „Document“ wird beschrieben, wie diese Methode verwendet werden kann.

Tab-Hierarchie

Untergeordnete Tabs werden in Apps Script über Tab.getChildTabs verfügbar gemacht. Um auf Inhalte von allen Tabs zuzugreifen, muss die „Baumstruktur“ der untergeordneten Tabs durchlaufen werden. Angenommen, ein Dokument enthält die folgende Tab-Hierarchie:

Tablist-Benutzeroberfläche mit drei Tabs der obersten Ebene, von denen einige untergeordnete Tabs haben

So greifen Sie auf Tab 3.1.2 zu:

// 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());

Beispielcode, mit dem alle Tabs in einem Dokument durchlaufen werden, finden Sie in den Codebeispielen in den folgenden Abschnitten.

Weitere Möglichkeiten zum Abrufen von Tabs

Es gibt zwei weitere Möglichkeiten, Tabs abzurufen:

Änderungen an der Struktur der Klasse „Document“

Bisher gab es in Dokumenten keine Tabs. Daher wurden in der Klasse „Document“ Methoden bereitgestellt, mit denen direkt auf die Textinhalte des Dokuments zugegriffen und diese geändert werden konnten. Die folgenden Methoden fallen in diese Kategorie:

Mit der zusätzlichen strukturellen Hierarchie von Tabs stellen diese Methoden nicht mehr semantisch den Textinhalt aller Tabs im Dokument dar. Der Textinhalt wird jetzt in einer anderen Ebene dargestellt. Alle oben genannten Textmethoden sind über DocumentTab zugänglich.

Mit diesen vorhandenen Methoden der Klasse Document wird auf Inhalte zugegriffen oder diese werden geändert entweder vom aktiven Tab (in Skripts, die an ein bestimmtes Dokumentgebunden sind) oder vom ersten Tab (wenn kein aktiver Tab verfügbar ist).

Auf Textinhalte auf einem bestimmten Tab zugreifen

Anstatt die Textmethoden von Document zu verwenden, sollten Sie die Methoden verwenden, die in der Klasse DocumentTab verfügbar sind (die über die Tab.asDocumentTabMethode verfügbar sind). Beispiel:

// 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());

Änderungen an der Nutzerauswahl

Das Konzept der Nutzerauswahl ist nur relevant und kann nur von Skripts verwendet oder geändert werden, die an ein Dokument gebunden sind.

Methoden zur Textauswahl

Die Klasse Document bietet Getter und Setter, mit denen verwaltet werden kann, wo im Text der Nutzer im aktiven Dokument eine Auswahl trifft. Diese Methoden werden im Kontext des aktiven Tabs des Nutzers ausgeführt, der das Skript ausführt.

  • Document.getCursor: Gibt die Cursorposition des Nutzers im aktiven Tab zurück.
  • Document.getSelection: Gibt den Auswahlbereich des Nutzers im aktiven Tab zurück.
  • Document.setCursor: Legt die Cursorposition des Nutzers im aktiven Dokument fest. Wenn sich die Position auf einem inaktiven Tab befindet, wird der aktive Tab des Nutzers auch auf den Tab umgestellt, der mit dieser Position verknüpft ist.
  • Document.setSelection: Legt den Auswahlbereich des Nutzers im aktiven Dokument fest. Wenn sich der Bereich auf einem inaktiven Tab befindet, wird der aktive Tab des Nutzers auch auf den Tab umgestellt, der mit diesem Bereich verknüpft ist.

Methoden zur Tab-Auswahl und Anwendungsfälle

Mit der Einführung von Tabs können Sie den aktiven Tab des Nutzers, der das Skript ausführt, abrufen und festlegen. Verwenden Sie dazu die folgenden Methoden:

  • Document.getActiveTab: Gibt den aktiven Tab des Nutzers im aktiven Dokument zurück.
  • Document.setActiveTab: Legt den ausgewählten Tab des Nutzers im aktuellen Dokument auf den Tab mit der angegebenen ID fest.

Die ganzheitliche „Auswahl“ des Nutzers besteht aus einer Kombination aus dem aktiven Tab und entweder der aktuellen Cursorposition oder dem Auswahlbereich. Es gibt zwei Muster für die Arbeit mit einer aktiven Auswahl: Entweder ändern Sie den aktiven Tab des Nutzers explizit in einen bestimmten Tab oder Sie verwenden den aktiven Tab des Nutzers.

Ändern Sie den aktiven Tab des Nutzers explizit mit Document.setActiveTab. Alternativ wird ein Tab durch Aufrufen von Document.setCursor oder Document.setSelection mit einem Position oder Range aus einem inaktiven Tab neu aktiviert.

Wenn das Skript den aktiven Tab des Nutzers verwenden soll ohne ihn zu ändern, dann Document.setActiveTab ist nicht erforderlich. Die Document.getCursor und Document.getSelection Methoden werden auf dem aktiven Tab ausgeführt, basierend auf dem Tab, von dem aus der Nutzer das Skript ausführt.

Ein Dokument unterstützt keine Mehrfachauswahl von Tabs oder mehrere Positionen oder Bereiche auf verschiedenen Tabs. Wenn Sie Document.setActiveTab verwenden, werden daher die vorherige Cursorposition oder der vorherige Auswahlbereich gelöscht.

Methoden für Position und Bereich für einen bestimmten Tab

Der bestimmte Tab gibt den Konzepten der Textauswahl Position und Range eine Bedeutung. Eine Cursorposition oder ein Auswahlbereich ist nur dann sinnvoll, wenn das Skript den bestimmten Tab kennt, in dem sich die Position oder der Bereich befindet.

Dies wird mit den DocumentTab.newPosition und DocumentTab.newRange Methoden erreicht, die eine Position oder einen Bereich erstellen, der auf den bestimmten DocumentTab ausgerichtet ist, von dem aus die Methode aufgerufen wird. Im Gegensatz dazu Document.newPosition und Document.newRange erstellen eine Position oder einen Bereich auf dem aktiven Tab (oder dem ersten Tab, wenn das Skript nicht gebunden ist).

Beispielcode für die Arbeit mit Auswahlmöglichkeiten finden Sie in den Codebeispielen in den folgenden Abschnitten.

Häufige Verwendungsmuster für Tabs

Die folgenden Codebeispiele beschreiben verschiedene Möglichkeiten zur Interaktion mit Tabs.

Tab-Inhalte von allen Tabs im Dokument lesen

Vorhandener Code, der dies vor der Einführung der Tabs-Funktion getan hat, kann migriert werden, um Tabs zu unterstützen. Dazu müssen Sie die Baumstruktur der Tabs durchlaufen und Getter-Methoden von Tab und DocumentTab anstelle von Document aufrufen. Das folgende Codebeispiel zeigt, wie Sie alle Textinhalte von jedem Tab in einem Dokument ausgeben. Dieser Code zum Durchlaufen von Tabs kann für viele andere Anwendungsfälle angepasst werden, bei denen die tatsächliche Struktur der Tabs keine Rolle spielt.

/** 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);
  }
}

Tab-Inhalte vom ersten Tab im Dokument lesen

Dies ähnelt dem Lesen aller Tabs.

/** 
 * 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());
}

Tab-Inhalte auf dem ersten Tab aktualisieren

Das folgende Codebeispiel zeigt, wie Sie bei Aktualisierungen einen bestimmten Tab auswählen.

/** 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();
}

Tab-Inhalte auf dem aktiven oder ausgewählten Tab aktualisieren

Das folgende Codebeispiel zeigt, wie Sie bei Aktualisierungen den aktiven Tab auswählen.

/**
 * 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();
}

Cursorposition oder Auswahlbereich auf dem aktiven Tab festlegen

Das folgende Codebeispiel zeigt, wie Sie die Cursorposition oder den Auswahlbereich auf dem aktiven Tab des Nutzers aktualisieren. Dies ist nur in gebundenen Skripts relevant.

/**
 * 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());
}

Aktiven oder ausgewählten Tab festlegen

Das folgende Codebeispiel zeigt, wie Sie den aktiven Tab des Nutzers ändern. Dies ist nur in gebundenen Skripts relevant.

/**
 * 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());
  }
}