Mit Tabs arbeiten

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

Was sind Tabs?

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

API-Unterstützung für untergeordnete Tabs ist bereits verfügbar, UI-Unterstützung ist jedoch bald verfügbar. Sie können jetzt untergeordnete Tabs in Ihrem Code verarbeiten, damit bei Einführung der UI-Unterstützung müssen Sie den Code nicht mehr aktualisieren.

Strukturelle Änderungen an der Darstellung von Dokumentinhalten in der Dokumentressource

Früher hatten Dokumente keine Registerkarten, sodass der Tab Document Ressource direkt enthalten den gesamten Textinhalt in die folgenden Felder ein:

Durch die zusätzliche strukturelle Hierarchie der Tabs werden diese Felder den Textinhalt aller Tabs im Dokument semantisch darzustellen. Die werden textbasierte Inhalte jetzt in einer anderen Ebene dargestellt. Tab-Eigenschaften und Inhalte in Google Docs sind mit document.tabs, eine Liste mit Tab-Objekte, die jeweils enthält alle oben genannten Textinhaltsfelder. In den nachfolgenden Abschnitten erhalten Sie einen kurzen Überblick die Tab-JSON-Darstellung liefert auch detailliertere Informationen.

Auf Eigenschaften des Tabs zugreifen

Auf Tabeigenschaften zugreifen mit tab.tabProperties, die Informationen wie die ID, den Titel und die Position des Tabs enthält.

Auf Textinhalte in einem Tab zugreifen

Der eigentliche Dokumentinhalt auf dem Tab wird als tab.documentTab Alle von Die oben genannten Textinhaltsfelder sind über tab.documentTab zugänglich. Anstatt document.body zu verwenden, sollten Sie beispielsweise document.tabs[indexOfTab].documentTab.body.

Tabhierarchie

Untergeordnete Tabs werden im API als Feld tab.childTabs aktiviert Tab 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:

Benutzeroberfläche für Tablisten mit drei Tabs der obersten Ebene, von denen einige untergeordnete Tabs haben

Um den Body abzurufen, auf Tab 3.1.2 öffnen Sie document.tabs[2].childTabs[0].childTabs[1].documentTab.body Beispiel ansehen Codeblöcke weiter unten, die Beispielcode für die Iteration auf allen Tabs in einem Dokument.

Änderungen an Methoden

Durch die Einführung von Tabs hat jede der Dokumentmethoden einige Änderungen. für die Sie möglicherweise Ihren Code aktualisieren müssen.

documents.get

Standardmäßig wird nicht der gesamte Tabinhalt zurückgegeben. Entwickler sollten ihre um auf alle Tabs zuzugreifen. Die documents.get stellt eine includeTabsContent, mit dem konfiguriert werden kann, ob Inhalte aus werden in der Antwort alle Tabs bereitgestellt.

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

documents.create

Methode documents.create gibt eine Document-Ressource zurück für das leere Dokument, das erstellt wurde. Die zurückgegebene Document Ressource füllt den leere Dokumentinhalte sowohl in den Textinhaltsfeldern des Dokuments als auch document.tabs.

document.batchUpdate

Jedes Request enthält eine Möglichkeit, die Tabs anzugeben, auf die das Update angewendet werden soll. Wenn eine Registerkarte nicht angegeben ist, wird der Request wird in den meisten Fälle werden auf die erste Registerkarte im Dokument angewendet. ReplaceAllTextRequest, DeleteNamedRangeRequest, und ReplaceNamedRangeContentRequest sind drei Sonderanforderungen, die standardmäßig auf alle Tabs angewendet werden.

Weitere Informationen finden Sie in der Requests in der Dokumentation.

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

Entwickler sollten ihren Code so aktualisieren, dass link.bookmark und link.heading bei Lese- und Schreibvorgängen verwendet werden. Sie decken interne Links mithilfe von BookmarkLink und HeadingLink Objekte, jedes die die ID des Lesezeichens oder der Überschrift und die ID des Tabs enthält, auf dem es sich befindet . Außerdem zeigt link.tabId interne Links zu Tabs an.

Link-Inhalte von documents.get Antwort kann auch abhängig vom includeTabsContent-Parameter variieren:

  • Wenn includeTabsContent auf true gesetzt ist, werden alle internen Links offengelegt als link.bookmark und link.heading. Die bisherigen Felder werden nicht mehr verwendet.
  • Wenn includeTabsContent nicht angegeben ist, kann in Dokumenten mit einem einem einzelnen Tab, alle internen Links zu Lesezeichen oder Überschriften innerhalb dieses einzelnen Tabs weiterhin als link.bookmarkId und link.headingId bereitgestellt. In Dokumenten mit mehreren Tabs werden interne Links als link.bookmark angezeigt und link.heading.

In document.batchUpdate: wenn ein interner Link mit einem der alten Felder, das Lesezeichen oder wird davon ausgegangen, dass die Überschrift der Tab-ID entspricht, die im Request Wenn kein Tab vorhanden ist angegeben ist, wird davon ausgegangen, dass sie vom ersten Tab im Dokument stammt.

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

Häufige Nutzungsmuster für Tabs

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

Tab-Inhalt aller Tabs im Dokument lesen

Vorhandener Code, der dies vor der Migration der Tab-Funktion zur Unterstützung indem Sie den Parameter includeTabsContent auf true setzen und die Tab-Baumhierarchie und das Aufrufen von Getter-Methoden Tab und DocumentTab statt Document Der folgende Teil Das Codebeispiel basiert auf dem Snippet unter Text aus einem Dokument extrahieren Er zeigt wie der gesamte Textinhalt aller Registerkarten in einem Dokument gedruckt wird. Dieser Tab Durchlaufcode kann für viele andere Anwendungsfälle angepasst werden, für die die eigentliche Struktur der Registerkarten.

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) {
  ...
}

Tab-Inhalt aus dem ersten Tab 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()));
}

Anfrage zum Aktualisieren des ersten Tabs stellen

Im folgenden Codebeispiel sehen Sie, wie die Ausrichtung auf einen bestimmten Tab in einem Request Dieser Code basiert auf der Stichprobe im Leitfaden zum Einfügen, Löschen und Verschieben von Text

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