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 über diese Themen:
- Konzeptionelles Modell der Dokumentelemente
- Darstellung dieser Elemente durch die Docs API
- Die Stileigenschaften der Elemente
Elemente der obersten Ebene
Das äußerste Containerelement in Google Docs ist ein Dokument. Dies ist die Einheit, die in Google Drive gespeichert, für andere Nutzer freigegeben und mit Text und Bildern aktualisiert werden kann.
Zu den Elementen der obersten Ebene einer documents-Ressource gehören Body, Header, Footer und mehrere andere Attribute:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Wenn Sie globale Dokumentfunktionen außerhalb des Body-Inhalts bearbeiten möchten, ist es fast immer besser, eine oder mehrere Dokumentvorlagen zu verwenden. Diese können Sie als Grundlage für das programmatische Generieren neuer Dokumente verwenden. Weitere Informationen finden Sie unter Text in einem Dokument zusammenführen.
Inhalt des Texts
Body enthält in der Regel den vollständigen Dokumentinhalt. 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 Abfolge von StructuralElement-Objekten. Ein Inhaltselement personalisiert jedes StructuralElement-Objekt, 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 eine StructuralElement, die einen Absatz darstellt. Es umfasst eine Reihe von Inhalten,
die mit einem Zeilenumbruchzeichen abgeschlossen sind. Es besteht aus den folgenden Objekten:
ParagraphElement: Beschreibt den Inhalt eines Absatzes.ParagraphStyle: Ein optionales Element, mit dem explizit Stileigenschaften für den Absatz festgelegt werden.Bullet: Wenn der Absatz Teil einer Liste ist, ein optionales Element, das die Aufzählungspunktspezifikation bereitstellt.
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.
Textausführungen
Ein TextRun ist ein ParagraphElement, der einen zusammenhängenden Textstring mit demselben Textstil darstellt. Ein Absatz kann mehrere Textläufe enthalten, jedoch nie über Absatzgrenzen hinweg. 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 von Absätzen im vorherigen Dokument mit jeweils eigenen TextRun- und optionalen Bullet-Einstellungen visualisieren können.
AutoText
AutoText ist eine ParagraphElement, die einen Punkt im Text darstellt, der dynamisch durch Inhalte ersetzt wird, die sich im Laufe der Zeit ändern können. In Docs wird das für Seitennummern verwendet.
Start- und Endindexe
Wenn Sie den Inhalt eines Dokuments aktualisieren, wird jede Aktualisierung an einem Speicherort oder in einem Bereich innerhalb des Dokuments vorgenommen. Diese Standorte und Bereiche werden mithilfe von Indexen angegeben, die einen Offset innerhalb eines Segments, das ein Dokument enthält, darstellen. Ein Segment ist der Textkörper, die Kopf-, Fußzeile oder Fußnote, die Struktur- oder Inhaltselemente enthalten. Die Indexe der Elemente innerhalb eines Segments beziehen sich auf den Anfang des Segments.
Die meisten Elemente im Textinhalt haben die nullbasierten Eigenschaften startIndex und endIndex. Diese geben den Versatz von Anfang und Ende eines Elements relativ zum Anfang des einschließenden Segments an. Weitere Informationen zum Anordnen der Docs API-Batchaufrufe finden Sie unter Batchaktualisierungen.
Indexe werden in UTF-16-Codeeinheiten gemessen. Dies bedeutet, dass Ersatzzeichenpaare zwei Indexe verbrauchen. Zum Beispiel wird das Emoji „GRINNING GESICHT“ Marktplatz als \uD83D\uDE00 dargestellt und verbraucht zwei Indexe.
Für Elemente innerhalb eines Dokumenttexts stellen Indexe den Versatz vom Anfang des Textinhalts, dem Stammelement, dar.
Die Personalisierungstypen für strukturelle Elemente – SectionBreak, TableOfContents, Table und Paragraph – enthalten diese Indexe nicht, da ihre einschließende StructuralElement-Felder diese Felder enthalten. Dies 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 jedes Elements ändern, das Text enthält. 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. Anschließend können Sie den resultierenden JSON-Code parsen, um die Werte einzelner Elemente zu ermitteln. Weitere Informationen finden Sie unter Dokumentinhalte als JSON ausgeben.
Das Parsen des Inhalts kann für verschiedene Anwendungsfälle von Vorteil sein. Nehmen wir als Beispiel ein Dokument zur Katalogisierung einer Anwendung mit einer Auflistung der gefundenen Dokumente. Diese App kann den Titel, die Überarbeitungs-ID und die Seitennummer eines Dokuments extrahieren, wie im folgenden Diagramm gezeigt:
Da es keine Methoden zum expliziten Lesen dieser Einstellungen gibt, muss Ihre Anwendung das gesamte Dokument abrufen und dann die JSON-Datei parsen, um diese Werte zu extrahieren.
Übernahme aus Properties
Ein StructuralElement kann Eigenschaften von seinen übergeordneten Objekten erben. Die Eigenschaften eines Objekts, einschließlich derjenigen, die definiert und übernommen werden, bestimmen sein endgültiges visuelles Erscheinungsbild.
Die Textzeichenformatierung bestimmt, wie Text in einem Dokument gerendert 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 aus den Stilen des Absatzes übernommen.
Die Absatzformatierung bestimmt, wie Textblöcke in einem Dokument gerendert werden, z. B. Ausrichtung, Rahmen und Einrückung. Die von Ihnen angewendete Formatierung überschreibt die Standardformatierung, die vom zugrunde liegenden ParagraphStyle übernommen wurde.
Umgekehrt werden Formatierungsfunktionen, die Sie nicht festlegen, weiterhin vom Absatzstil übernommen.