Mit Tabs arbeiten

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

Was sind Tabs?

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

Auf Tabs zugreifen

Tab-Eigenschaften und -Inhalte sind über Document.getTabs() zugänglich. Dadurch wird eine Liste von Tabs zurückgegeben. In den folgenden Abschnitten erhalten Sie einen kurzen Überblick über die Klasse Tab. Weitere Informationen finden Sie in der Tab-Klassendokumentation.

Tab-Eigenschaften

Tab-Properties können mithilfe von Methoden wie Tab.getId() und Tab.getTitle() abgerufen werden.

Tabinhalt

Der Inhalt von Dokumenten auf den einzelnen Tabs kann mit Tab.asDocumentTab() abgerufen werden. Im Abschnitt Änderungen an der Struktur von Dokumentklassen wird beschrieben, wie diese verwendet werden kann.

Tab-Hierarchie

Untergeordnete Tabs werden in Google Apps Script über Tab.getChildTabs() freigegeben. Wenn Sie auf Inhalte von allen Tabs zugreifen möchten, müssen Sie den „Baum“ der untergeordneten Tabs durchlaufen. Betrachten Sie zum Beispiel ein Dokument, das eine Tabhierarchie wie folgt enthält:

Tablist-UI mit drei Tabs der obersten Ebene, von denen einige untergeordnete Tabs haben

So können Sie auf Tab 3.1.2 zugreifen:

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

Die Blöcke mit Beispielcode finden Sie weiter unten in den Abschnitten. Sie enthalten Beispielcode zum Iterieren auf allen Tabs in einem Dokument.

Weitere Möglichkeiten zum Abrufen von Tabs

Es gibt noch zwei weitere Möglichkeiten, Tabs abzurufen:

Änderungen an der Struktur von Dokumentklassen

Früher gab es in Dokumenten keine Tabs. Daher wurden über die Dokumentklasse Methoden zum direkten Zugriff auf den Textinhalt des Dokuments und zum Ändern dieses Inhalts bereitgestellt. Die folgenden Methoden fallen in diese Kategorie:

Aufgrund der zusätzlichen strukturellen Hierarchie der Tabs stellen diese Methoden den Textinhalt aller Tabs im Dokument nicht mehr semantisch dar. Der Textinhalt wird jetzt auf einer anderen Ebene dargestellt. Auf alle oben genannten Textmethoden kann über DocumentTab zugegriffen werden.

Mit diesen vorhandenen Methoden der Klasse Document können Inhalte entweder über den aktiven Tab (in Scripts, die an ein bestimmtes Dokument gebunden sind) oder über den ersten Tab (falls kein aktiver Tab verfügbar ist) abgerufen oder geändert werden.

Auf Textinhalte in einem bestimmten Tab zugreifen

Anstatt die Textmethoden von Document zu verwenden, empfehlen wir, stattdessen die Methoden der Klasse DocumentTab zu verwenden, die über die Methode Tab.asDocumentTab() verfügbar ist. 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

Methoden zur Textauswahl

Die Klasse Document bietet Getter und Setter, um festzulegen, wo im Text der Nutzer im aktiven Dokument etwas auswählt. Diese Methoden werden im Kontext des aktiven Tabs des Nutzers ausgeführt, der das Skript ausführt.

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

Methoden und Anwendungsfälle für die Tab-Auswahl

Durch die Einführung von Tabs kann es hilfreich sein, den aktiven Tab des Nutzers, der das Skript ausführt, abzurufen und festzulegen. Dazu haben Sie folgende Möglichkeiten:

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: Sie können entweder den aktiven Tab des Nutzers explizit in einen bestimmten Tab ändern oder den aktiven Tab des Nutzers verwenden.

Mit Document.setActiveTab(tabId) können Sie den aktiven Tab des Nutzers explizit ändern. Alternativ kannst du Document.setCursor(position) oder Document.setSelection(range) mit einem Position oder Range auf einem inaktiven Tab aufrufen, um diesen Tab zu aktivieren.

Wenn das Skript den aktiven Tab des Nutzers verwenden soll, ohne ihn zu ändern, ist Document.setActiveTab(tabId) nicht erforderlich. Die Methoden Document.getCursor() und Document.getSelection() werden bereits auf dem aktiven Tab ausgeführt, je nachdem, auf welchem Tab der Nutzer das Script ausführt.

Hinweis: Ein Dokument unterstützt keine Auswahl mehrerer Tabs, Positionen oder Bereiche auf verschiedenen Tabs. Daher wird mit Document.setActiveTab(tabId) die vorherige Cursorposition oder der vorherige Auswahlbereich gelöscht.

Positionierungs- und Bereichsmethoden für einen bestimmten Tab

Der jeweilige Tab gibt den Textauswahlkonzepten Position und Range einen Sinn. Mit anderen Worten: Eine Cursorposition oder ein Auswahlbereich sind nur dann sinnvoll, wenn das Script den Tab kennt, in dem sich die Position oder der Bereich befindet.

Dazu werden die Methoden DocumentTab.newPosition(element, offset) und DocumentTab.newRange() verwendet, mit denen eine Position oder ein Bereich erstellt wird, der auf die spezifische DocumentTab ausgerichtet ist, von der aus die Methode aufgerufen wird. Im Gegensatz dazu wird mit Document.newPosition(element, offset) und Document.newRange() eine Position oder ein Bereich erstellt, die auf den aktiven Tab bzw. den ersten Tab, wenn das Skript nicht gebunden ist, ausgerichtet ist.

In den folgenden Abschnitten finden Sie Codeblöcke mit Beispielcode für die Arbeit mit Auswahlen.

Gängige Nutzungsmuster für Tabs

In den folgenden Codebeispielen werden verschiedene Möglichkeiten für die Interaktion mit Tabs beschrieben.

Tabinhalte aller Tabs im Dokument lesen

Vor der Einführung der Tabs-Funktion erstellter Code kann so migriert werden, dass er Tabs unterstützt: Durchlaufen Sie den Tabs-Baum und rufen Sie die Get-Methoden von Tab und DocumentTab statt von Document auf. Im folgenden Codebeispiel wird gezeigt, wie der gesamte Textinhalt aller Tabs in einem Dokument gedruckt wird. Dieser Code für den Tabdurchlauf kann für viele andere Anwendungsfälle angepasst werden, für die die tatsächliche Struktur der Tabs nicht von Bedeutung ist.

/** 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-Inhalt aus dem ersten Tab im Dokument lesen

Das entspricht 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());
}

Tabinhalte auf dem ersten Tab aktualisieren

Im folgenden Codebeispiel wird gezeigt, wie Sie bei Aktualisierungen einen bestimmten Tab anvisieren.

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

Tabinhalte im aktiven oder ausgewählten Tab aktualisieren

Im folgenden Codebeispiel wird gezeigt, wie Sie bei Aktualisierungen den aktiven Tab anvisieren.

/**
 * 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 die Cursorposition oder der Auswahlbereich auf dem aktiven Tab des Nutzers aktualisiert wird. 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());
  }
}