Damit Sie die Google Docs API effektiv nutzen können, müssen Sie die Architektur eines Google Docs-Dokuments, die Elemente, aus denen ein Dokument besteht, sowie die Beziehung zwischen ihnen verstehen. Auf dieser Seite finden Sie eine detaillierte Übersicht zu den 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. Diese Einheit kann in Google Drive gespeichert, für andere Nutzer freigegeben und mit Text und Bildern aktualisiert werden.
Zu den Elementen der obersten Ebene einer documents-Ressource gehören 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: Representiert den Textinhalt eines Tabs.
In den folgenden Abschnitten erhalten Sie einen kurzen Überblick über die Tab-Hierarchie des Dokuments. Die JSON-Darstellung des Tabs enthält auch ausführlichere Informationen. Weitere Informationen zur Tab-Funktion finden Sie unter Mit Tabs arbeiten.
Wenn Sie globale Funktionen des Dokumenttabs außerhalb der Body-Inhalte bearbeiten möchten, ist es fast immer besser, eine oder mehrere Dokumentvorlagen zu verwenden, die Sie als Grundlage für die programmatische Generierung neuer Dokumente verwenden können. Weitere Informationen finden Sie unter Text in ein Dokument einfügen.
Textinhalt
Die Body enthält in der Regel den vollständigen Inhalt des Tabs eines Dokuments. Die meisten Elemente, die Sie programmatisch verwenden können oder möchten, sind Elemente innerhalb der Body-Inhalte:
Strukturelement
Mit einer StructuralElement werden Inhalte beschrieben, die dem Dokument Struktur verleihen. Der Body-Inhalt ist eine Sequenz von StructuralElement-Objekten. Mit einem Inhaltselement wird jedes StructuralElement-Objekt personalisiert, wie im folgenden Diagramm dargestellt:
Strukturelemente und ihre Inhaltsobjekte enthalten alle visuellen Komponenten im Dokument. Dazu gehören Text, Inline-Bilder und Formatierung.
Absatzstruktur
Ein Paragraph ist ein StructuralElement, das einen Absatz darstellt. Er enthält verschiedene Inhalte, die mit einem Zeilenumbruchzeichen abgeschlossen werden. Er besteht aus den folgenden Objekten:
ParagraphElement: Beschreibt den Inhalt eines Absatzes.ParagraphStyle: Ein optionales Element, mit dem Stileigenschaften für den Absatz explizit festgelegt werden.Bullet: Wenn der Absatz Teil einer Liste ist, ein optionales Element, das die Aufzählungszeichenspezifikation enthält.
ParagraphElement funktioniert ähnlich wie StructuralElement. Eine Reihe von Inhaltselementtypen (z. B. ColumnBreak und Equation) personalisiert seine 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 strukturellen und Inhaltselemente sowie die Verwendung von Start- und Endindizes, wie im folgenden Abschnitt beschrieben.
Textzeilen
Ein TextRun ist ein ParagraphElement, der einen zusammenhängenden Textstring mit demselben Textstil darstellt. Ein Absatz kann mehrere Textabläufe enthalten, aber Textabläufe überschreiten niemals Absatzgrenzen. Der Inhalt wird nach einem Zeilenvorschubzeichen in separate Textblöcke unterteilt. Betrachten wir beispielsweise ein kleines Dokument wie das folgende:
Das folgende Diagramm zeigt, wie Sie die Abfolge der Absätze im vorherigen Dokument mit jeweils eigenen TextRun- und optionalen Bullet-Einstellungen visualisieren können.
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 diese Funktion für Seitennummern verwendet.
Start- und Endindexe
Wenn Sie den Inhalt des Tabs eines Dokuments aktualisieren, wird jede Aktualisierung an einer Stelle oder in einem Bereich innerhalb des Dokuments vorgenommen. Diese Positionen und Bereiche werden mithilfe von Indexen angegeben, die einen Offset innerhalb eines enthaltenden Dokument-Segments darstellen. Ein Segment ist der Textkörper, die Kopf- oder Fußzeile oder die Fußnote, die strukturelle oder Inhaltselemente enthält. Die Indizes der Elemente innerhalb eines Segments beziehen sich auf den Anfang dieses Segments.
Die meisten Elemente im Textkörper haben die Attribute startIndex und endIndex, die von null ausgehen. Sie geben den Versatz des Anfangs und des Endes eines Elements relativ zum Anfang des umschließenden Segments an. Weitere Informationen zum Anfordern von Batch-Docs API-Aufrufen finden Sie unter Batch-Aktualisierungen.
Indexe werden in UTF-16-Codeeinheiten gemessen. Das bedeutet, dass Ersatzzeichenpaare zwei Indexe belegen. Das Emoji „LÄCHELNDES GESICHT“, 😄, wird beispielsweise als \uD83D\uDE00 dargestellt und belegt zwei Indexe.
Bei Elementen im Textkörper stellen Indizes Abweichungen vom Anfang des Textkörpers dar, also vom „Stammelement“.
Die Typen „Personalisierung“ für strukturelle Elemente – SectionBreak, TableOfContents, Table und Paragraph – haben diese Indexe nicht, da sie in einem umschließenden StructuralElement enthalten sind, das diese Felder hat. Das gilt auch für die Personalisierungstypen in einem ParagraphElement, z. B. TextRun, AutoText und PageBreak.
Elemente aufrufen
Viele Elemente können mit der Methode documents.batchUpdate geändert werden. Mit InsertTextRequest können Sie beispielsweise den Inhalt eines beliebigen Elements mit Text ändern. Ebenso können Sie mit UpdateTextStyleRequest einen Textbereich in einem oder mehreren Elementen formatieren.
Wenn Sie Elemente des Dokuments lesen möchten, verwenden Sie die Methode documents.get, um einen JSON-Dump des gesamten Dokuments zu erhalten. Sie können dann die resultierende JSON-Datei parsen, um die Werte der einzelnen Elemente zu ermitteln. Weitere Informationen finden Sie unter Inhalt des Dokuments als JSON ausgeben.
Das Parsen von Inhalten kann für verschiedene Anwendungsfälle von Vorteil sein. Nehmen wir als Beispiel eine Anwendung zum Katalogisieren von Dokumenten, die gefundene Dokumente auflistet. Mit dieser App können Sie den Titel, die Überarbeitungs-ID und die Startseitennummer der Tabs eines Dokuments extrahieren, 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 Eigenschaften von seinen übergeordneten Objekten übernehmen. Die Eigenschaften eines Objekts, einschließlich der von ihm definierten und der von ihm übernommenen, bestimmen sein endgültiges Erscheinungsbild.
Mit der Formatierung von Textzeichen wird festgelegt, wie Text in einem Dokument dargestellt wird, z. B. fett, kursiv oder unterstrichen. Die von Ihnen angewendete Formatierung überschreibt die Standardformatierung, die vom TextStyle des zugrunde liegenden Absatzes übernommen wurde. Umgekehrt werden alle Zeichen, deren Formatierung Sie nicht festlegen, weiterhin von den Stilen des Absatzes übernommen.
Mit der Absatzformatierung wird festgelegt, wie Textblöcke in einem Dokument dargestellt werden, z. B. Ausrichtung, Rahmen und Einzüge. Die von Ihnen angewendete Formatierung überschreibt die Standardformatierung, die von der zugrunde liegenden ParagraphStyle übernommen wurde.
Umgekehrt werden alle Formatierungsfunktionen, die Sie nicht festlegen, weiterhin vom Absatzstil übernommen.