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 ihnen.

Elemente der obersten Ebene

Zu den Elementen auf oberster Ebene 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 präsentieren wir eine minimalistische Ansicht der strukturellen Elemente von Dokumenten. Dies dient der Einfachheit und Übersichtlichkeit. Für eine vollständige Darstellung der Dokumentstruktur sollten Sie das Dienstprogramm verwenden, das unter Dokumentinhalte als JSON ausgeben beschrieben wird.

Um globale Dokumentfunktionen außerhalb des Textkörpers zu bearbeiten, ist es fast immer besser, eine oder mehrere Dokumentvorlagen zu verwenden, die Sie als Grundlage für die programmatische Erstellung neuer Dokumente verwenden können.

Textinhalt

Die meisten Elemente, die Sie programmatisch verwenden können oder wahrscheinlich verwenden möchten, sind Elemente im Textinhalt:

Strukturelemente

Der Textinhalt ist nur eine Abfolge von StructuralElement-Objekten. Ein Inhaltselement personalisiert jedes StructuralElement-Objekt, wie im folgenden Diagramm dargestellt:

Die Strukturelemente und ihre Inhaltsobjekte enthalten unter anderem den gesamten Text des Dokuments und die Inline-Bilder.

Die Typen Header, Footer und Footnote enthalten Inhaltselemente, die auch eine Folge von Strukturelementen enthalten.

Absätze enthalten einen speziellen Elementtyp namens ParagraphElement, der ähnlich wie StructuralElement funktioniert. Ein Satz von Inhaltselementtypen personalisiert seine eigene ParagraphElement, wie im folgenden Diagramm dargestellt:

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

Start- und Endindex

Die meisten Elemente im Textkörper haben die Properties startIndex und endIndex. Sie geben den Versatz zwischen Anfang und Ende eines Elements bezogen auf den Anfang des einschließenden Segments an.

Ein Segment ist der Textkörper, die Kopf-/Fußzeile oder die Fußnote, die Struktur- oder Inhaltselemente enthält. Die Indexe der Elemente in einem Segment beziehen sich auf den Anfang des Segments.

Indexe werden in UTF-16-Codeeinheiten gemessen. Das bedeutet, dass Ersatzzeichenpaare 2 Indexe verbrauchen. Das Emoji „GRINNENES GESICHT“ 👀 wird beispielsweise als „\uD83D\uDE00“ dargestellt und verbraucht 2 Indexe.

Bei Elementen im Textkörper eines Dokuments stellen Indexe den Versatz vom Anfang des Textinhalts dar, der das "Stammelement" ist.

Elemente, die nicht in den Inhalt eingeschlossen sind, haben diese Indexattribute nicht. Sie sind global und haben nicht das Konzept der Position.

Die Typen „Personalisierung“ für Strukturelemente – SectionBreak, TableOfContents, Table und Paragraph – haben diese Indexe nicht, da ihr einschließendes StructuralElement diese Felder enthält. Dies gilt auch für die Personalisierungstypen, die in einem ParagraphElement enthalten sind.

Absatzstruktur

Ein Absatz besteht aus Folgendem:

• elements: Eine Sequenz, die mindestens eine Instanz von textRun enthält.
• paragraphStyle: Ein optionales Element, mit dem explizit Stileigenschaften für den Absatz festgelegt werden.
• bullet: Ein optionales Element, mit dem Aufzählungspunkte angegeben werden können, wenn der Absatz Teil einer Liste ist.

Textausführungen

Ein textRun stellt einen zusammenhängenden Textstring mit demselben Textstil dar. Ein Absatz kann mehrere Textläufe enthalten, die jedoch keine Absatzgrenzen überschreiten. Betrachten Sie zum Beispiel ein kleines Dokument wie das folgende:

Das folgende Diagramm zeigt, wie Sie die Reihenfolge der Absätze im obigen Dokument mit jeweils eigenen Textausführungen und optionalen Einstellungen für Aufzählungszeichen visualisieren können.

Auf Elemente zugreifen

Viele Elemente können mithilfe der Methode BatchUpdate geändert werden. Mit dem Anfragetyp InsertTextRequest können Sie beispielsweise den Inhalt jedes Elements ändern, das Text enthält. Ebenso können Sie UpdateTextStyleRequest verwenden, um Formatierungen auf einen Textbereich anzuwenden, der in einem oder mehreren Elementen enthalten ist.

Wenn Sie Elemente des Dokuments lesen möchten, rufen Sie mit der Methode get einen JSON-Dump des vollständigen Dokuments ab. Eine Möglichkeit dafür finden Sie im Beispiel Dokumentinhalt als JSON ausgeben. Anschließend können Sie das resultierende JSON-Objekt parsen, um die Werte einzelner Elemente zu ermitteln.

Das Parsen des Inhalts kann für verschiedene Anwendungsfälle nützlich sein. Nehmen wir zum Beispiel eine Anwendung zur Katalogisierung von Dokumenten, die gefundene Dokumente auflistet. Diese Anwendung 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.