Mit Tabs arbeiten

Mit der Google Docs API können Sie auf Inhalte von jedem Tab im Dokument zugreifen.

Was sind Tabs?

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

Strukturelle Änderungen an der Darstellung von Dokumentinhalten in der Dokumentressource

Früher gab es in Dokumenten keine Tabs. Die Document-Ressource enthielt daher direkt alle Textinhalte über die folgenden Felder:

• document.body
• document.headers
• document.footers
• document.footnotes
• document.documentStyle
• document.suggestedDocumentStyleChanges
• document.namedStyles
• document.suggestedNamedStylesChanges
• document.lists
• document.namedRanges
• document.inlineObjects
• document.positionedObjects

Durch die zusätzliche Strukturhierarchie von Tabs stellen diese Felder nicht mehr semantisch den Textinhalt aller Tabs im Dokument dar. Die textbasierten Inhalte werden jetzt in einer anderen Ebene dargestellt. Auf Tab-Attribute und ‑Inhalte in Google Docs kann mit document.tabs zugegriffen werden. Dabei handelt es sich um eine Liste von Tab-Objekten, die jeweils alle oben genannten Textinhaltsfelder enthalten. In den folgenden Abschnitten finden Sie einen kurzen Überblick. Die JSON-Darstellung des Tabs enthält ebenfalls detailliertere Informationen.

Auf Tab-Eigenschaften zugreifen

Auf die Tab-Properties kann mit tab.tabProperties zugegriffen werden. Diese enthalten Informationen wie die ID, den Titel und die Positionierung des Tabs.

Auf Textinhalte auf einem Tab zugreifen

Der tatsächliche Dokumentinhalt auf dem Tab wird als tab.documentTab bereitgestellt. Alle oben genannten Textinhaltsfelder sind über tab.documentTab zugänglich. Verwenden Sie beispielsweise document.tabs[indexOfTab].documentTab.body anstelle von document.body.

Tab-Hierarchie

Untergeordnete Tabs werden in der API als Feld tab.childTabs für Tab dargestellt. Um auf alle Tabs in einem Dokument zuzugreifen, muss der „Baum“ der untergeordneten Tabs durchlaufen werden. Angenommen, ein Dokument enthält eine Tab-Hierarchie wie folgt:

Um die Body aus Tab 3.1.2 abzurufen, greifen Sie auf document.tabs[2].childTabs[0].childTabs[1].documentTab.body zu. Im späteren Abschnitt finden Sie Beispielcodeblöcke, die zeigen, wie Sie alle Tabs in einem Dokument durchlaufen.

Änderungen an Methoden

Mit der Einführung von Tabs wurden einige Änderungen an den Dokumentmethoden vorgenommen, die möglicherweise eine Aktualisierung Ihres Codes erfordern.

documents.get

Standardmäßig werden nicht alle Tab-Inhalte zurückgegeben. Entwickler sollten ihren Code aktualisieren, um auf alle Tabs zugreifen zu können. Die Methode documents.get stellt einen includeTabsContent-Parameter zur Verfügung, mit dem konfiguriert werden kann, ob Inhalte von allen Tabs in der Antwort enthalten sein sollen.

• Wenn includeTabsContent auf true gesetzt ist, gibt die Methode documents.get eine Document-Ressource mit dem Feld document.tabs zurück. Alle Textfelder direkt in document (z.B. document.body) bleiben leer.
• Wenn includeTabsContent nicht angegeben ist, werden die Textfelder in der Document-Ressource (z.B. document.body) nur mit Inhalten vom ersten Tab gefüllt. Das Feld document.tabs ist leer und Inhalte von anderen Tabs werden nicht zurückgegeben.

documents.create

Die Methode documents.create gibt eine Document-Ressource zurück, die das erstellte leere Dokument darstellt. Die zurückgegebene Document-Ressource füllt den leeren Dokumentinhalt sowohl in den Textinhaltsfeldern des Dokuments als auch in document.tabs aus.

document.batchUpdate

Jede Request enthält eine Möglichkeit, die Tabs anzugeben, auf die die Aktualisierung angewendet werden soll. Wenn kein Tab angegeben ist, wird Request in den meisten Fällen standardmäßig auf den ersten Tab im Dokument angewendet. ReplaceAllTextRequest, DeleteNamedRangeRequest> und ReplaceNamedRangeContentRequest sind drei spezielle Anfragen, die standardmäßig auf alle Tabs angewendet werden.

Weitere Informationen finden Sie in der Dokumentation zu Request.

Änderungen an internen Links

Nutzer können interne Links zu Tabs, Lesezeichen und Überschriften in einem Dokument erstellen. Mit der Einführung der Tab-Funktion können die Felder link.bookmarkId und link.headingId in der Ressource Link nicht mehr für ein Lesezeichen oder eine Überschrift auf einem bestimmten Tab im Dokument stehen.

Entwickler sollten ihren Code aktualisieren, damit link.bookmark und link.heading in Lese- und Schreibvorgängen verwendet werden. Sie machen interne Links mithilfe von BookmarkLink- und HeadingLink-Objekten verfügbar, die jeweils die ID der Lesezeichen oder Überschrift und die ID des Tabs enthalten, auf dem sie sich befinden. Außerdem werden mit link.tabId interne Links zu Tabs verfügbar gemacht.

Die Inhalte einer documents.get-Antwort können auch je nach includeTabsContent-Parameter variieren:

• Wenn includeTabsContent auf true gesetzt ist, werden alle internen Links als link.bookmark und link.heading verfügbar gemacht. Die alten Felder werden nicht mehr verwendet.
• Wenn includeTabsContent nicht angegeben ist, werden in Dokumenten mit einem einzelnen Tab alle internen Links zu Lesezeichen oder Überschriften auf diesem Tab weiterhin als link.bookmarkId und link.headingId angezeigt. In Dokumenten mit mehreren Tabs werden interne Links als link.bookmark und link.heading angezeigt.

In document.batchUpdate wird bei einem internen Link, der mit einem der alten Felder erstellt wurde, die Lesezeichen- oder Überschriften-ID aus der Tab-ID im Request verwendet. Wenn kein Tab angegeben ist, wird davon ausgegangen, dass er sich auf den ersten Tab im Dokument bezieht.

Weitere Informationen finden Sie in der JSON-Darstellung von Links.

Häufige Nutzungsmuster für Tabs

Die folgenden Codebeispiele beschreiben verschiedene Möglichkeiten, mit Tabs zu interagieren.

Tabinhalte aus allen Tabs im Dokument lesen

Vorhandener Code, der dies vor der Einführung der Tab-Funktion getan hat, kann migriert werden, um Tabs zu unterstützen. Dazu muss der Parameter includeTabsContent auf true gesetzt, die Tab-Baumstruktur durchlaufen und Getter-Methoden für Tab und DocumentTab anstelle von Document aufgerufen werden. Das folgende teilweise Codebeispiel basiert auf dem Snippet unter Text aus einem Dokument extrahieren. Hier wird gezeigt, wie Sie den gesamten Textinhalt von jedem Tab in einem Dokument ausdrucken. Dieser Code für die Tab-Navigation kann für viele andere Anwendungsfälle angepasst werden, bei denen die tatsächliche Struktur der Tabs keine Rolle spielt.

/** Prints all text contents from all tabs in the document. */
static void printAllText(Docs service, String documentId) throws IOException {
  // Fetch the document with all of the tabs populated, including any nested
  // child tabs.
  Document doc =
      service.documents().get(documentId).setIncludeTabsContent(true).execute();
  List<Tab> allTabs = getAllTabs(doc);

  // Print the content from each tab in the document.
  for (Tab tab: allTabs) {
    // Get the DocumentTab from the generic Tab.
    DocumentTab documentTab = tab.getDocumentTab();
    System.out.println(
        readStructuralElements(documentTab.getBody().getContent()));
  }
}

/**
 * Returns a flat list of all tabs in the document in the order they would
 * appear in the UI (top-down ordering). Includes all child tabs.
 */
private List<Tab> getAllTabs(Document doc) {
  List<Tab> allTabs = new ArrayList<>();
  // Iterate over all tabs and recursively add any child tabs to generate a
  // flat list of Tabs.
  for (Tab tab: 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.
 */
private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) {
  allTabs.add(tab);
  for (Tab tab: tab.getChildTabs()) {
    addCurrentAndChildTabs(tab, allTabs);
  }
}

/**
 * Recurses through a list of Structural Elements to read a document's text
 * where text may be in nested elements.
 *
 * <p>For a code sample, see
 * <a href="https://developers.google.com/workspace/docs/api/samples/extract-text">Extract
 * the text from a document</a>.
 */
private static String readStructuralElements(List<StructuralElement> elements) {
  ...
}

Tab-Inhalte aus dem ersten Tab im Dokument lesen

Das ist ähnlich wie das Lesen aller Tabs.

/** Prints all text contents from the first tab in the document. */
static void printAllText(Docs service, String documentId) throws IOException {
  // Fetch the document with all of the tabs populated, including any nested
  // child tabs.
  Document doc =
      service.documents().get(documentId).setIncludeTabsContent(true).execute();
  List<Tab> allTabs = getAllTabs(doc);

  // Print the content from the first tab in the document.
  Tab firstTab = allTabs.get(0);
  // Get the DocumentTab from the generic Tab.
  DocumentTab documentTab = firstTab.getDocumentTab();
  System.out.println(
      readStructuralElements(documentTab.getBody().getContent()));
}

Anfrage zum Aktualisieren des ersten Tabs stellen

Das folgende teilweise Codebeispiel zeigt, wie Sie einen bestimmten Tab in einem Request ansprechen. Dieser Code basiert auf dem Beispiel im Leitfaden Text einfügen, löschen und verschieben.

/** Inserts text into the first tab of the document. */
static void insertTextInFirstTab(Docs service, String documentId)
    throws IOException {
  // Get the first tab's ID.
  Document doc =
      service.documents().get(documentId).setIncludeTabsContent(true).execute();
  Tab firstTab = doc.getTabs().get(0);
  String tabId = firstTab.getTabProperties().getTabId();

  List<Request>requests = new ArrayList<>();
  requests.add(new Request().setInsertText(
      new InsertTextRequest().setText(text).setLocation(new Location()
                                                            // Set the tab ID.
                                                            .setTabId(tabId)
                                                            .setIndex(25))));

  BatchUpdateDocumentRequest body =
      new BatchUpdateDocumentRequest().setRequests(requests);
  BatchUpdateDocumentResponse response =
      docsService.documents().batchUpdate(DOCUMENT_ID, body).execute();
}