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 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:
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
auftrue
gesetzt ist, gibt der Parameterdocuments.get
zurückgegeben, eineDocument
-Ressource mit dem Das Felddocument.tabs
ist ausgefüllt. Alle Textfelder direkt aufdocument
(z.B.document.body
) bleibt leer. - Wenn
includeTabsContent
nicht angegeben ist, werden die Textfelder in der RessourceDocument
(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
Request
s
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 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
auftrue
gesetzt ist, werden alle internen Links offengelegt alslink.bookmark
undlink.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 alslink.bookmarkId
undlink.headingId
bereitgestellt. In Dokumenten mit mehreren Tabs werden interne Links alslink.bookmark
angezeigt undlink.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(); }