Um die Google Docs API effektiv nutzen zu können, müssen Sie die Architektur eines Google Docs-Dokuments und die Elemente, aus denen es besteht, sowie die Beziehung zwischen diesen beiden Elementen kennen. Auf dieser Seite finden Sie eine detaillierte Übersicht über diese Themen:
- Ein 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 weitere 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, die Sie als Grundlage für die programmatische Erstellung neuer Dokumente verwenden können. Weitere Informationen finden Sie unter Text in einem Dokument zusammenführen.
Text
Body enthält normalerweise den vollständigen Dokumentinhalt. Die meisten Elemente, die Sie programmatisch verwenden können oder wahrscheinlich verwenden möchten, sind Elemente innerhalb des Body-Inhalts:
Strukturelement
Ein StructuralElement beschreibt Inhalte, die dem Dokument Struktur verleihen. Der Inhalt von Body 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 im Dokument. Dazu gehören der Text, Inline-Bilder und die Formatierung.
Absatzstruktur
Ein Paragraph ist eine StructuralElement, die einen Absatz darstellt. Sie umfasst einen Bereich von Inhalten,
der mit einem Zeilenumbruchzeichen beendet wird. Es besteht aus den folgenden Objekten:
ParagraphElement: Beschreibt den Inhalt in einem Absatz.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ählungszeichenspezifikation bereitstellt.
Das ParagraphElement funktioniert in etwa wie ein StructuralElement. Mit 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 findest du im Dokumentbeispiel im JSON-Format. In der Ausgabe sehen Sie viele der wichtigsten strukturellen und inhaltsbezogenen Elemente sowie die im folgenden Abschnitt beschriebene Verwendung von Start- und Endindexen.
Textausführungen
Ein TextRun ist ein ParagraphElement, der einen zusammenhängenden Textstring mit demselben Textstil darstellt. Ein Absatz kann mehrere Textdurchläufe enthalten, die jedoch niemals die Absatzgrenzen überschreiten. Der Inhalt wird nach einem Zeilenumbruchzeichen aufgeteilt, um separate Textläufe zu bilden. Betrachten Sie zum Beispiel ein kleines Dokument, das wie folgt aussieht:
Das folgende Diagramm zeigt, wie Sie die Abfolge der Absätze im vorherigen Dokument mit jeweils eigenen Einstellungen für TextRun und Bullet visualisieren können.
AutoText
AutoText ist ein ParagraphElement, der einen Textplatz darstellt, der dynamisch durch Inhalte ersetzt wird, die sich im Laufe der Zeit ändern können. In Docs wird dies für
Seitennummern verwendet.
Start- und Endindexe
Wenn Sie den Inhalt eines Dokuments aktualisieren, wird jede Aktualisierung an einer Stelle oder in einem Bereich innerhalb des Dokuments durchgeführt. Diese Positionen und Bereiche werden mithilfe von Indexen angegeben, die einen Offset innerhalb eines Segments dieses Dokuments darstellen. Ein Segment ist ein Textkörper, eine Kopfzeile, eine Fußzeile oder eine Fußnote, die Struktur- oder Inhaltselemente enthält. Die Indexe der Elemente in einem Segment beziehen sich auf den Anfang des Segments.
Die meisten Elemente im Textinhalt haben die nullbasierten Eigenschaften startIndex und endIndex. Sie geben den Versatz von Anfang und Ende eines Elements bezogen auf den Anfang des einschließenden Segments an. Weitere Informationen zum Bestellen Ihrer Docs API-Batchaufrufe finden Sie unter Batch-Updates.
Indexe werden in UTF-16-Codeeinheiten gemessen. Dies bedeutet, dass Ersatzwertpaare zwei Indexe verbrauchen. Das Emoji „Grinnendes Gesicht“ 👀 wird als \uD83D\uDE00 dargestellt und verbraucht zwei Indexe.
Bei Elementen innerhalb eines Dokumenttexts stellen Indexe Offsets vom Anfang des Textinhalts dar, der das „Stammelement“ ist.
Die Typen „Personalisieren“ von Strukturelementen – 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, z. B. TextRun, AutoText und PageBreak.
Auf Elemente zugreifen
Viele Elemente können mit der Methode documents.batchUpdate geändert werden. Beispielsweise können Sie mit InsertTextRequest den Inhalt jedes Elements ändern, das Text enthält. In ähnlicher Weise können Sie UpdateTextStyleRequest verwenden, um Formatierungen auf einen Textbereich anzuwenden, der in einem oder mehreren Elementen enthalten ist.
Verwenden Sie zum Lesen von Elementen des Dokuments die Methode documents.get, um einen JSON-Dump des vollständigen Dokuments abzurufen. Sie können die resultierende JSON-Datei dann parsen, um die Werte einzelner Elemente zu ermitteln. Weitere Informationen finden Sie unter Inhalt des Ausgabedokuments als JSON.
Das Parsen des Inhalts kann für verschiedene Anwendungsfälle von Vorteil sein. Nehmen wir als Beispiel eine Katalogisierungsanwendung, die gefundene Dokumente auflistet. Mit dieser Anwendung können der Titel, die Überarbeitungs-ID und die Startseitennummer eines Dokuments extrahiert werden, wie im folgenden Diagramm dargestellt:
Da es keine Methoden zum expliziten Lesen dieser Einstellungen gibt, muss Ihre Anwendung das gesamte Dokument abrufen und dann den JSON-Code parsen, um diese Werte zu extrahieren.
Übernahme aus Properties
Ein StructuralElement kann Eigenschaften von seinen übergeordneten Objekten übernehmen. Die Eigenschaften eines Objekts, einschließlich der definierter und übernommener Eigenschaften, bestimmen das endgültige visuelle Erscheinungsbild.
Die Formatierung von Textzeichen legt fest, 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 wurde. Umgekehrt werden alle Zeichen, deren Formatierung Sie nicht festlegen, weiterhin von den Absatzstilen übernommen.
Mit der Absatzformatierung wird festgelegt, 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 alle Formatierungsfunktionen, die Sie nicht festlegen, weiterhin vom Absatzstil übernommen.