Mit Tabs arbeiten

Mit der Google Docs API 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 Tabs gibt. 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 in einem anderen Tab verschachtelt sind.

Strukturelle Änderungen an der Darstellung von Dokumentinhalten in der Dokumentressource

Früher gab es in Dokumenten keine Tabs. Daher enthielt die Document-Ressource den gesamten Textinhalt direkt über die folgenden Felder:

Aufgrund der zusätzlichen strukturellen Hierarchie der Tabs repräsentieren diese Felder nicht mehr semantisch den Textinhalt aller Tabs im Dokument. Der textbasierte Inhalt wird jetzt in einer anderen Ebene dargestellt. Tab-Eigenschaften und ‑Inhalte in Google Docs sind über document.tabs zugänglich. Das ist eine Liste von Tab-Objekten, die jeweils alle oben genannten Textinhaltsfelder enthalten. In den folgenden Abschnitten erhalten Sie einen kurzen Überblick. Weitere Informationen finden Sie auf dem Tab JSON-Darstellung.

Eigenschaften des Tabs „Zugriff“

Über tab.tabProperties können Sie auf Tab-Properties zugreifen. Diese enthalten Informationen wie die ID, den Titel und die Position des Tabs.

Auf Textinhalte auf einem Tab zugreifen

Der tatsächliche Dokumentinhalt auf dem Tab wird als tab.documentTab angezeigt. Auf alle oben genannten Textinhaltsfelder kann über tab.documentTab zugegriffen werden. Verwenden Sie beispielsweise document.tabs[indexOfTab].documentTab.body anstelle von document.body.

Tab-Hierarchie

Untergeordnete Tabs werden in der API als Feld tab.childTabs unter Tab dargestellt. Um auf alle Tabs in einem Dokument zuzugreifen, 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

Wenn Sie Body auf Tab 3.1.2 abrufen möchten, greifen Sie auf document.tabs[2].childTabs[0].childTabs[1].documentTab.body zu. Im folgenden Abschnitt finden Sie Codeblöcke mit Beispielcode für die Iteration über alle Tabs in einem Dokument.

Änderungen an Methoden

Durch die 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 Tabinhalte zurückgegeben. Entwickler sollten ihren Code aktualisieren, um auf alle Tabs zugreifen zu können. Die Methode documents.get gibt den Parameter includeTabsContent zurück, mit dem konfiguriert werden kann, ob Inhalte aus allen Tabs in der Antwort enthalten sind.

  • Wenn includeTabsContent auf true gesetzt ist, gibt die Methode documents.get eine Document-Ressource zurück, bei der das Feld document.tabs ausgefüllt ist. 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 aus dem ersten Tab ausgefü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. Mit der zurückgegebenen Document-Ressource wird der leere Dokumentinhalt sowohl in den Textinhaltsfeldern des Dokuments als auch in document.tabs eingefügt.

document.batchUpdate

Bei jeder Request können Sie angeben, auf welche Tabs das Update angewendet werden soll. Wenn kein Tab angegeben ist, wird Request in den meisten Fällen 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.

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 Link-Ressource kein Lesezeichen oder eine Überschrift auf einem bestimmten Tab im Dokument mehr darstellen.

Entwickler sollten ihren Code so aktualisieren, dass link.bookmark und link.heading bei Lese- und Schreibvorgängen verwendet werden. Interne Links werden mithilfe von BookmarkLink- und HeadingLink-Objekten angezeigt, die jeweils die ID des Lesezeichens oder der Überschrift und die ID des Tabs enthalten, in dem sie sich befinden. Außerdem werden mit link.tabId interne Links zu Tabs angezeigt.

Der Linkinhalt einer documents.get-Antwort kann auch vom Parameter includeTabsContent abhängen:

  • Wenn includeTabsContent auf true gesetzt ist, werden alle internen Links als link.bookmark und link.heading angezeigt. 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.

Wenn in document.batchUpdate ein interner Link mit einem der alten Felder erstellt wird, wird der Lesezeichen- oder Überschriftentext als Teil der Tab-ID betrachtet, die in Request angegeben ist. Wenn kein Tab angegeben ist, wird davon ausgegangen, dass er sich auf dem ersten Tab im Dokument befindet.

Die JSON-Darstellung des Links enthält detailliertere Informationen.

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 vorhandene Codeelemente, die dies tun, können so migriert werden, dass sie Tabs unterstützen: Legen Sie dazu den Parameter includeTabsContent auf true fest, durchlaufen Sie die Tabs-Baumhierarchie und rufen Sie die Get-Methoden von Tab und DocumentTab statt von Document auf. Das folgende Codebeispiel basiert auf dem Snippet unter Text aus einem Dokument extrahieren. Hier wird gezeigt, wie Sie den gesamten Textinhalt aller Tabs in einem Dokument drucken. 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.

Java

/** 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/docs/api/samples/extract-text">Extract
 * the text from a document</a>.
 */
private static String readStructuralElements(List<StructuralElement> elements) {
  ...
}

Tabinhalte des ersten Tabs im Dokument lesen

Das entspricht dem Lesen aller Tabs.

Java

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

Aktualisierungsanfrage für den ersten Tab stellen

Im folgenden Codebeispiel wird gezeigt, wie Sie die Ausrichtung auf einen bestimmten Tab in einer Request vornehmen. Dieser Code basiert auf dem Beispiel im Leitfaden Text einfügen, löschen und verschieben.

Java

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