Um die Google Docs API effektiv nutzen zu können, müssen Sie die Architektur eines Google Docs-Dokuments, die Elemente, aus denen ein Dokument besteht, und die Beziehung zwischen diesen 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: Macht alle untergeordneten Tabs eines Tabs sichtbar, also 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 Tab-JSON-Darstellung enthält auch ausführlichere Informationen. Weitere Informationen zur Tab-Funktion finden Sie unter Mit Tabs arbeiten.
Wenn Sie globale Dokument-Tab-Features außerhalb des Body-Inhalts bearbeiten möchten, ist es fast immer besser, eine oder mehrere Dokumentvorlagen zu verwenden, die Sie als Grundlage zum programmatischen Generieren neuer Dokumente verwenden können. Weitere Informationen finden Sie unter Text in ein Dokument einfügen.
Textinhalt
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 innerhalb des Dokuments. Dazu gehören Text, Inline-Bilder und Formatierung.
Absatzstruktur
Ein Paragraph ist ein StructuralElement, das einen Absatz darstellt. Es umfasst eine Reihe von Inhalten,
die mit einem Zeilenumbruchzeichen abgeschlossen sind. 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.
Die ParagraphElement funktioniert in etwa wie eine StructuralElement. Bei einer Reihe von Inhaltselementtypen (z. B. ColumnBreak und Equation) wird der eigene ParagraphElement personalisiert, 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 wichtige Struktur- und Inhaltselemente sowie die Verwendung der Start- und Endindexe, 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 nie Absatzgrenzen. Inhalte werden nach einem Zeilenumbruchzeichen aufgeteilt, um separate Textläufe zu bilden. Stellen Sie sich ein winziges Dokument wie das folgende vor:
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-, Fußzeile oder Fußnote, die Struktur- oder Inhaltselemente enthalten. 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.
Für Elemente innerhalb eines Dokumenttexts stellen Indexe den Versatz vom Anfang des Textinhalts, dem Stammelement, dar.
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 einer ParagraphElement, 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 mit Text ändern. Mit UpdateTextStyleRequest können Sie einen Textbereich formatieren, der in einem oder mehreren Elementen enthalten ist.
Wenn Sie Elemente des Dokuments lesen möchten, verwenden Sie die Methode documents.get, um einen JSON-Dump des gesamten Dokuments abzurufen. 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. Diese Anwendung kann den Titel, die Überarbeitungs-ID und die Startseite der Seitenzahl 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 derjenigen, die es definiert und der übernommenen, bestimmen sein endgültiges visuelles 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 wird. Umgekehrt werden alle Zeichen, deren Formatierung Sie nicht festlegen, weiterhin von den Stilen des Absatzes übernommen.
Die Absatzformatierung bestimmt, wie Textblöcke in einem Dokument gerendert werden, z. B. Ausrichtung, Ränder und Einrückung. 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.