Struktur eines Google Docs-Dokuments

In diesem Leitfaden wird die interne Struktur eines Google Docs-Dokuments beschrieben: die Elemente, aus denen ein Dokument besteht, und die Beziehung zwischen diesen Elementen.

Elemente der obersten Ebene

Zu den obersten Elementen eines Dokuments gehören der Text und mehrere andere Attribute des Dokuments als Ganzes:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

In diesem Leitfaden stellen wir Ihnen eine minimalistische Ansicht der strukturellen Elemente von Dokumenten vor. Der Einfachheit halber Für eine vollständige Darstellung der Dokumentstruktur können Sie das unter Ausgabeinhalt als JSON ausgeben beschriebene Dienstprogramm verwenden.

Um globale Dokumentfunktionen außerhalb des Textinhalts zu bearbeiten, 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.

Textinhalte

Die meisten Elemente, die Sie programmatisch verwenden können oder möchten, sind Elemente innerhalb des Textinhalts:

Strukturelle Elemente

Der Textinhalt ist nur eine Sequenz von StructuralElement-Objekten. Mit einem Inhaltselement wird jedes StructuralElement-Objekt personalisiert, wie im folgenden Diagramm dargestellt:

Die strukturellen Elemente und ihre Inhaltsobjekte enthalten den gesamten Text des Dokuments, Inlinebilder usw.

Die Typen Header, Footer und Fußnote enthalten Inhaltselemente, die auch eine Folge von strukturellen Elementen enthalten.

Absätze enthalten einen speziellen Elementtyp namens ParagraphElement, der in etwa so funktioniert: StructuralElement. Eine Reihe von Inhaltselementtypen personalisiert sein eigenes ParagraphElement, wie im folgenden Diagramm dargestellt:

Ein Beispiel für eine vollständige Dokumentstruktur finden Sie im Beispiel-Dump eines Dokuments im JSON-Format. In der Ausgabe sehen Sie viele der wichtigsten strukturellen und inhaltlichen Elemente sowie die Verwendung von Start- und Endindexen, wie im folgenden Abschnitt beschrieben.

Start- und Endindex

Die meisten Elemente im Textinhalt haben die Attribute startIndex und endIndex. Damit wird der Offset von Anfang und Ende eines Elements relativ zum Anfang des einschließenden Segments angegeben.

Ein Segment ist der Text, die Kopfzeile, die Fußzeile oder die Fußnote, die Struktur- oder Inhaltselemente enthält. Die Indexe der Elemente innerhalb eines Segments sind relativ zum Anfang dieses Segments.

Indexe werden in UTF-16-Codeeinheiten gemessen. Das bedeutet, dass Ersatzpaare 2 Indexe verbrauchen. Zum Beispiel würde das Emoji „GRINNING FACE“ (📲) als „\uD83D\uDE00“ dargestellt und 2 Indizes verbraucht.

Bei Elementen in einem Dokumenttext stellen Indexe Offsets ab dem Anfang des Textinhalts dar. Dies ist das Stammelement.

Elemente, die nicht in Inhalten enthalten sind, haben diese Indexeigenschaften nicht. Sie haben einen globalen Geltungsbereich und haben kein Positionskonzept.

Die Personalisierungstypen für strukturelle Elemente – SectionBreak, TableOfContents, Table und Paragraph – haben diese Indexe nicht, da ihre umschließenden StructuralElement diese Felder enthalten. Dies gilt auch für die Personalisierungstypen in ParagraphElement.

Absatzstruktur

Ein Absatz besteht aus Folgendem:

• elements: Eine Sequenz mit einer oder mehreren Instanzen von textRun.
• paragraphStyle: Ein optionales Element, mit dem Stileigenschaften für den Absatz explizit festgelegt werden.
• bullet: Ein optionales Element, das die Aufzählungszeichen angibt, wenn der Absatz Teil einer Liste ist.

Textausführungen

Ein textRun steht für einen zusammenhängenden Textstring mit demselben Textstil. Ein Absatz kann mehrere Textausführungen enthalten, Textausführungen dürfen jedoch keine Absatzgrenzen überschreiten. Stellen Sie sich beispielsweise ein winziges Dokument wie das folgende vor:

Das folgende Diagramm zeigt, wie Sie die Abfolge von Absätzen im obigen Dokument mit jeweils eigenen Textläufen und optionalen Aufzählungseinstellungen visualisieren können.

Zugriffselemente

Viele Elemente können mit der Methode BatchUpdate geändert werden. Mit dem Anfragetyp InsertTextRequest können Sie beispielsweise den Inhalt von Elementen ändern, die Text enthalten. Auf ähnliche Weise können Sie mithilfe von UpdateTextStyleRequest die Formatierung auf einen Textbereich in einem oder mehreren Elementen anwenden.

Verwenden Sie zum Lesen von Elementen des Dokuments die Methode get, um einen JSON-Dump des vollständigen Dokuments abzurufen. Eine entsprechende Anleitung finden Sie im Beispiel Inhalt des Dokuments als JSON ausgeben. Sie können dann das resultierende JSON-Objekt parsen, um die Werte einzelner Elemente zu finden.

Das Parsen des Inhalts kann für verschiedene Anwendungsfälle nützlich sein. Stellen Sie sich beispielsweise ein Dokument vor, in dem eine gefundene App aufgelistet wird. Diese App möchte möglicherweise den Titel, die Überarbeitungs-ID und die Startseitennummer eines Dokuments extrahieren, wie im folgenden Diagramm dargestellt:

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.