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, die Tabs genannt wird. In Google Docs können Nutzer einen oder mehrere Tabs in einem einzelnen Dokument erstellen, ähnlich wie es in Google Tabellen bereits der Fall ist. Jeder Tab hat einen eigenen Titel und eine ID, die an die URL angehängt wird. Ein Tab kann auch untergeordnete Tabs haben, die in einem anderen Tab verschachtelt sind.

Tabs aufrufen

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 der Dokumentklasse 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. Angenommen, ein Dokument enthält die folgende Tab-Hierarchie:

Tablist-UI 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());

In den folgenden Abschnitten finden Sie Codeblöcke mit Beispielcode für die Iteration über alle Tabs in einem Dokument.

Weitere Möglichkeiten zum Abrufen von Tabs

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

Änderungen an der Struktur der Dokumentklasse

Früher gab es in Dokumenten keine Tabs. Daher gab die Dokumentklasse Methoden zum direkten Zugriff auf den Textinhalt des Dokuments und zum Ändern dieses Inhalts frei. 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 in einer anderen Ebene dargestellt. Alle oben genannten Textmethoden sind über DocumentTab zugänglich.

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 auf 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 Script 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 zu dem Tab mit dem Bereich gewechselt.

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

Mit der Einführung von Tabs kann es nützlich sein, den aktiven Tab des Nutzers abzurufen und festzulegen, der das Script ausführt. Dazu haben Sie folgende Möglichkeiten:

Die „Gesamtauswahl“ 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. Wenn Sie also Document.setActiveTab(tabId) verwenden, wird 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 werden mit Document.newPosition(element, offset) und Document.newRange() eine Position oder ein Bereich erstellt, die bzw. der auf den aktiven Tab (oder den ersten Tab, wenn das Script 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 zur 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 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);
  }
}

Tabinhalte des ersten Tabs 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 auf dem 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

Im folgenden Codebeispiel wird gezeigt, wie die Cursorposition oder der Auswahlbereich auf dem aktiven Tab des Nutzers aktualisiert wird. Dies ist nur in gebundenen Scripts 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

Im folgenden Codebeispiel wird gezeigt, wie der aktive Tab des Nutzers geändert wird. Dies ist nur in gebundenen Scripts 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());
  }
}