Damit Sie die Google Docs API effektiv nutzen können, müssen Sie die Architektur eines Google-Dokuments und die Elemente, aus denen ein Dokument besteht, sowie die Beziehung zwischen ihnen verstehen. Auf dieser Seite finden Sie einen detaillierten Überblick über die folgenden Themen:
- Ein konzeptionelles Modell der Dokumentelemente
- Darstellung dieser Elemente in der Docs API
- Die Stileigenschaften der Elemente
Elemente der obersten Ebene
Das äußerste Containerelement in Google Docs ist ein Dokument. Das ist die Einheit, die in Google Drive gespeichert, mit anderen Nutzern geteilt und mit Text und Bildern aktualisiert werden kann.
Die Elemente der obersten Ebene einer documents-Ressource umfassen die Tabs, SuggestionsViewMode und andere Attribute:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Tabs
Ein einzelnes Dokument kann mehrere Tabs mit unterschiedlichen Inhalten auf Textebene enthalten. Die tabs-Eigenschaft des Dokuments ist eine Folge von Tab-Objekten. Ein Tab besteht aus den folgenden Feldern:
TabProperties: Enthält die Attribute eines Tabs, z. B. ID, Titel und Index.childTabs: Zeigt die untergeordneten Tabs eines Tabs an (Tabs, die direkt darunter verschachtelt sind).DocumentTab: Stellt den Textinhalt eines Tabs dar.
In den folgenden Abschnitten finden Sie einen kurzen Überblick über die Hierarchie der Dokumenttabs. Ausführlichere Informationen finden Sie auch unter Tab-JSON-Darstellung. Weitere Informationen zur Funktion „Tabs“ finden Sie unter Mit Tabs arbeiten.
Wenn Sie globale Dokumenttab-Funktionen außerhalb des Body-Inhalts bearbeiten möchten, ist es fast immer besser, eine oder mehrere Dokumentvorlagen zu verwenden, die Sie als Grundlage für das programmgesteuerte Generieren neuer Dokumente nutzen können. Weitere Informationen finden Sie unter Text in ein Dokument einfügen.
Textinhalt
Der Body enthält in der Regel den vollständigen Inhalt eines Dokumenttabs. Die meisten Elemente, die Sie programmatisch verwenden können oder möchten, sind Elemente im Body-Inhalt:
Strukturelement
Ein StructuralElement beschreibt Inhalte, die dem Dokument Struktur verleihen. Der Body-Inhalt ist eine Sequenz von StructuralElement-Objekten. Ein Inhaltselement personalisiert jedes StructuralElement-Objekt, wie im folgenden Diagramm dargestellt:
Strukturelemente und ihre Inhaltsobjekte enthalten alle visuellen Komponenten im Dokument. Dazu gehören der Text, Inlinebilder und die Formatierung.
Absatzstruktur
Ein Paragraph ist ein StructuralElement, der einen Absatz darstellt. Sie enthält eine Reihe von Inhalten, die mit einem Zeilenumbruchzeichen beendet werden. Es besteht aus den folgenden Objekten:
ParagraphElement: Beschreibt den Inhalt eines Absatzes.ParagraphStyle: Ein optionales Element, mit dem Stilattribute für den Absatz explizit festgelegt werden.Bullet: Wenn der Absatz Teil einer Liste ist, ein optionales Element, das die Aufzählungszeichenangabe enthält.
Die ParagraphElement funktioniert ähnlich wie eine StructuralElement. Eine Reihe von Inhaltselementtypen (z. B. ColumnBreak und Equation) personalisiert die eigene ParagraphElement, wie im folgenden Diagramm dargestellt:
Ein Beispiel für eine vollständige Dokumentstruktur finden Sie im Dokumentbeispiel im JSON-Format. In der Ausgabe sehen Sie viele der wichtigsten Struktur- und Inhaltselemente sowie die Verwendung von Start- und Endindexen, wie in einem der folgenden Abschnitte beschrieben.
Textblöcke
Ein TextRun ist ein ParagraphElement, der einen zusammenhängenden Textstring mit demselben Textstil darstellt. Ein Absatz kann mehrere Textläufe enthalten, aber Textläufe überschreiten niemals Absatzgrenzen. Inhalte werden nach einem Zeilenumbruchzeichen in separate Textblöcke unterteilt. Betrachten Sie beispielsweise das folgende kurze Dokument:
Das folgende Diagramm zeigt, wie Sie die Abfolge der Absätze im vorherigen Dokument visualisieren können. Jeder Absatz hat eigene TextRun- und optionale Bullet-Einstellungen.
AutoText
AutoText ist ein ParagraphElement, das eine Stelle im Text darstellt, die dynamisch durch Inhalte ersetzt wird, die sich im Laufe der Zeit ändern können. In Google Docs wird dies für Seitenzahlen verwendet.
Start- und Endindex
Wenn Sie den Inhalt eines Dokumenttabs aktualisieren, erfolgt jede Aktualisierung an einer bestimmten Stelle oder in einem bestimmten Bereich im Dokument. Diese Positionen und Bereiche werden mithilfe von Indexen angegeben, die einen Offset innerhalb eines enthaltenden Segments eines Dokuments darstellen. Ein Segment ist der Textkörper, der Header, der Footer oder die Fußnote, die Struktur- oder Inhaltselemente enthält. Die Indexe der Elemente innerhalb eines Segments sind relativ zum Anfang dieses Segments.
Die meisten Elemente im Hauptinhalt haben die nullbasierten Attribute startIndex und endIndex. Diese geben den Versatz des Beginns und Endes eines Elements relativ zum Beginn des umschließenden Segments an. Weitere Informationen zum Anordnen von Batch-API-Aufrufen für Google Docs finden Sie unter Batch-Aktualisierungen.
Die Indexierung erfolgt in UTF-16-Codeeinheiten. Das bedeutet, dass Ersatzzeichenpaare zwei Indexeinträge belegen. Das Emoji „GRINNING FACE“ (grinsendes Gesicht) 😄 wird beispielsweise als \uD83D\uDE00 dargestellt und belegt zwei Indexe.
Bei Elementen im Text eines Dokuments stellen die Indexe Offsets vom Anfang des Textinhalts dar, der das „Stammelement“ ist.
Die Typen „personalizing“ für strukturelle Elemente – SectionBreak, TableOfContents, Table und Paragraph – haben diese Indexe nicht, da ihr einschließendes StructuralElement diese Felder enthält. Das gilt auch für die Personalisierungstypen, die in einem ParagraphElement enthalten sind, z. B. TextRun, AutoText und PageBreak.
Auf Elemente zugreifen
Viele Elemente können mit der Methode documents.batchUpdate geändert werden. Mit InsertTextRequest können Sie beispielsweise den Inhalt eines beliebigen Elements ändern, das Text enthält. Ebenso können Sie mit UpdateTextStyleRequest Formatierungen auf einen Textbereich anwenden, der in einem oder mehreren Elementen enthalten ist.
Verwenden Sie die Methode documents.get, um Elemente des Dokuments zu lesen und einen JSON-Dump des gesamten Dokuments zu erhalten. Anschließend können Sie das resultierende JSON-Dokument parsen, um die Werte der einzelnen Elemente zu ermitteln. Weitere Informationen finden Sie unter Inhalte des Ausgabedokuments als JSON.
Das Parsen von Inhalten kann für verschiedene Anwendungsfälle von Vorteil sein. Stellen Sie sich beispielsweise eine Anwendung zur Katalogisierung von Dokumenten vor, in der die gefundenen Dokumente aufgeführt werden. Mit dieser App können der Titel, die Überarbeitungs-ID und die Startseitennummer der Tabs eines Dokuments extrahiert werden, wie im folgenden Diagramm dargestellt:
Da es keine Methoden zum expliziten Lesen dieser Einstellungen gibt, muss Ihre App das gesamte Dokument abrufen und dann das JSON parsen, um diese Werte zu extrahieren.
Übernahme für Properties
Ein StructuralElement kann Attribute von seinen übergeordneten Objekten übernehmen. Die Eigenschaften eines Objekts, einschließlich der von ihm definierten und der von ihm geerbten Eigenschaften, bestimmen sein endgültiges Erscheinungsbild.
Die Formatierung von Textzeichen bestimmt, wie Text in einem Dokument gerendert wird, z. B. fett, kursiv und unterstrichen. Die von Ihnen angewendete Formatierung überschreibt die Standardformatierung, die vom TextStyle des zugrunde liegenden Absatzes übernommen wurde.
Umgekehrt erben alle Zeichen, deren Formatierung Sie nicht festlegen, weiterhin die Formatierung des Absatzes.
Mit der Absatzformatierung wird festgelegt, wie Textblöcke in einem Dokument gerendert werden, z. B. Ausrichtung, Rahmen und Einzug. Die Formatierung, die Sie anwenden, überschreibt die Standardformatierung, die von der zugrunde liegenden ParagraphStyle übernommen wird.
Umgekehrt werden alle Formatierungsfunktionen, die Sie nicht festlegen, weiterhin vom Absatzstil übernommen.