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:

• 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 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 über documents.tabs zugänglich, eine Liste von Tabs, wobei jedes Feld alle oben genannten Textinhaltsfelder enthält. In den nachfolgenden Abschnitten erhalten Sie einen kurzen Überblick. die Tab-JSON-Darstellung liefert auch detailliertere Informationen.

Auf Eigenschaften des Tabs zugreifen

Auf Tabeigenschaften mit tab.tabProperties zugreifen, einschließlich Informationen wie als ID, Titel und Position des Tabs.

Auf Textinhalte in einem Tab zugreifen

Der eigentliche Dokumentinhalt auf dem Tab wird als tab.documentTab angezeigt. Alle der oben genannten Textinhaltsfelder sind mit tab.documentTab Anstatt document.body zu verwenden, sollten Sie beispielsweise document.tabs[indexOfTab].documentTab.body.

Tabhierarchie

Untergeordnete Tabs werden in der API als tab.childTabs-Feld auf Tab dargestellt. Für den Zugriff auf alle Tabs in einem Dokument muss die Baumstruktur durchlaufen werden untergeordneten Tabs. Betrachten Sie zum Beispiel ein Dokument, das eine Tabhierarchie wie die folgende enthält:

Um die body aus Tab 3.1.2 abzurufen, würden 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 Methode documents.get stellt eine includeTabsContent-Parameter, mit dem konfiguriert werden kann, ob Inhalte aus werden in der Antwort alle Tabs bereitgestellt.

• 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 unter document (z.B. document.body) bleiben 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

Die Methode documents.create gibt eine Document-Ressource, die den Leeres Dokument, das erstellt wurde. Die zurückgegebene Document Ressource wird in den leeren Dokumentinhalt 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.

Ä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 werden die link.bookmarkId und link.headingId-Felder dürfen nicht mehr für ein Lesezeichen oder eine Überschrift in einem bestimmte Registerkarte im Dokument.

Entwickler sollten ihren Code aktualisieren, um link.bookmark und link.heading in Lese- und Schreibvorgängen. 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.

Linkinhalte einer documents.get-Antwort können auch je nach includeTabsContent-Parameter:

• Wenn includeTabsContent auf true gesetzt ist, werden alle internen Links offengelegt als link.bookmark und link.heading. Legacy-Felder (link.bookmarkId und link.headingId) wird 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.

Wenn in document.batchUpdate ein interner Link mit einer der enthalten, wird davon ausgegangen, dass das Lesezeichen oder die Überschrift aus der Tab-ID stammt. in den Request Wenn kein Tab vorhanden ist angegeben ist, wird davon ausgegangen, dass sie vom ersten Tab im Dokument stammt.

Die Die Link-JSON-Darstellung bietet um ausführlichere Informationen zu erhalten.

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 Aufruf von Getter-Methoden aus Tab und DocumentTab anstelle von Document Der folgende partielle Code basiert auf dem Snippet unter Text aus einem Dokument extrahieren Sie erfahren, wie Sie den gesamten Textinhalt aller Tabs in einem Dokument drucken. Dieser Code zum Tabdurchlauf kann für viele andere Anwendungsfälle angepasst werden, die tatsächliche Struktur der Tabs.

/** 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

Dies ähnelt dem 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

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

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