Struktur eines Google Docs-Dokuments

Um die Google Docs API effektiv nutzen zu können, müssen Sie die Architektur eines Google Docs-Dokuments und der Elemente, aus denen ein Dokument besteht Dokument und die Beziehung zwischen ihnen. Auf dieser Seite finden Sie eine ausführliche Ü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 aktualisiert werden kann. mit Text und Bildern.

Die Elemente der obersten Ebene eines documents Ressourcen enthalten Tabs, SuggestionsViewMode, und weitere Attribute:

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

Tabs

Ein einzelnes Dokument kann mehrere Tabs enthalten, die unterschiedliche Inhalte auf Textebene haben. Die Eigenschaft tabs des Dokuments ist ein Sequenz 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 (direkt verschachtelte Tabs) sichtbar darunter).
  • DocumentTab: Stellt den Textinhalt eines Tabs dar.
Struktur der Tabs eines Dokuments.
Abbildung 1: Struktur der Tabs eines Dokuments.

In den nachfolgenden Abschnitten erhalten Sie einen kurzen Überblick über die Hierarchie der Dokument-Tabs. die Tab-JSON-Darstellung ebenfalls erhalten Sie genauere Informationen. Weitere Informationen finden Sie unter Mit Tabs arbeiten. finden Sie weitere Informationen zur Registerkartenfunktion.

Um globale Dokument-Tab-Funktionen außerhalb des Body-Inhalts zu bearbeiten, ist es fast immer besser, eine oder mehrere Dokumentvorlagen zu verwenden, die Sie als eine Grundlage für die programmatische Generierung neuer Dokumente. Weitere Informationen finden Sie unter Text in ein Dokument zusammenführen

Inhalt des Texts

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 den Body-Inhalt:

Struktur des Textinhalts
Abbildung 2: Struktur des Textinhalts

Strukturelement

StructuralElement beschreibt Inhalte, die dem Dokument Struktur verleihen. Der Body-Inhalt ist Sequenz von StructuralElement-Objekten Ein Inhaltselement personalisiert jedes StructuralElement-Objekt, wie im folgenden Diagramm dargestellt:

Strukturelle Elemente.
Abbildung 3: Strukturelle Elemente.

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, die für einen Absatz steht. Die Inhalte sind breit gefächert mit einem Zeilenumbruchzeichen abgeschlossen werden. Es besteht aus den folgenden Objekten:

  • ParagraphElement: Beschreibt den Inhalt eines Absatzes.
  • ParagraphStyle: Ein optionales -Element, das explizit Stileigenschaften für den Absatz festlegt.
  • Bullet: Wenn der Absatz ist Teil einer Liste, ein optionales Element, das den Aufzählungspunkt zur Verfügung stellt. Spezifikation zu ändern.

Die ParagraphElement funktioniert in etwa wie eine StructuralElement. Eine Reihe von Arten von Inhaltselementen (z. B. ColumnBreak und Equation) personalisieren eigene ParagraphElement haben, wie im folgenden Diagramm dargestellt:

Struktur der Absatzelemente
Abbildung 4: Struktur der Absatzelemente

Ein Beispiel für eine vollständige Dokumentstruktur finden Sie im Dokument Beispiel im JSON-Format. In der Ausgabe können Sie die wichtigsten Struktur- und Inhaltselemente sowie die Verwendung von Anfangs- und Endindexe, wie in einem folgenden Abschnitt beschrieben.

Textausführungen

Ein TextRun ist ein ParagraphElement repräsentiert eine zusammenhängende Textzeichenfolge mit demselben Textstil. A „Absatz“ kann mehrere Textläufe enthalten, aber der Text darf nie quer durch einen Absatz verlaufen. grenzen. Inhalte werden nach einem Zeilenumbruchzeichen getrennt, um separaten Text zu bilden ausgeführt wird. Stellen Sie sich ein winziges Dokument wie das folgende vor:

Kleines Dokument mit Absätzen und Aufzählungsliste.
Abbildung 5: Ein kleines Dokument.

Das folgende Diagramm zeigt, wie Sie die Abfolge von Absätzen visualisieren können. im vorherigen Dokument, jeweils mit eigener TextRun und optionalem Bullet Einstellungen.

Struktur eines Textlaufs.
Abbildung 6: Struktur eines Textlaufs.

AutoText

AutoText ist ein ParagraphElement, die einen Punkt im Text darstellt, der dynamisch ersetzt wird mit Inhalten, die sich im Laufe der Zeit ändern können. In Google Docs wird dies für Seitennummern.

Start- und Endindexe

Wenn Sie den Inhalt auf dem Tab eines Dokuments aktualisieren, an einem Ort oder innerhalb eines Bereichs innerhalb des Dokuments platzieren. Diese Standorte und Bereiche werden mithilfe von Indexen angegeben, die einen Offset innerhalb einer das Segment des Dokuments enthält. Ein Segment ist der Textkörper, die Kopf-, Fußzeile oder Fußnote, die Struktur- oder Inhaltselemente enthält. Die Indizes der Elemente innerhalb eines Segments relativ zum Anfang des Segments sind.

Die meisten Elemente im Textinhalt haben das nullbasierte startIndex und endIndex-Properties. Diese geben den Versatz des Anfangs und der Position Ende bezogen auf den Anfang des einschließenden Segments. Weitere Informationen zur Reihenfolge der Docs API-Batchaufrufe siehe Batch-Aufrufe. Aktualisierungen.

Indexe werden in UTF-16-Codeeinheiten gemessen. Dies bedeutet, dass Ersatzwertpaare aus zwei Indexen. Zum Beispiel: „GRINNENDES Gesichtserkennung“ Emoji smartling wird dargestellt als \uD83D\uDE00 und verbraucht zwei Indexe.

Für Elemente innerhalb eines Dokumenttexts stellen Indexe Offsets vom Anfang des Textinhalts, der der „Stamm“ ist -Elements.

Die „Personalisierung“ strukturelle Typen Elemente: SectionBreak, TableOfContents Table und Paragraph – verfügen nicht über diese Indexe, da ihr umschließender StructuralElement enthält diese Felder. Dies gilt auch für die Personalisierung Typen, die in einem ParagraphElement enthalten sind, z. B. TextRun, AutoText und PageBreak

Auf Elemente zugreifen

Viele Elemente können mit der Funktion documents.batchUpdate . Wenn Sie beispielsweise InsertTextRequest, können Sie den Inhalt jedes Elements, das Text enthält, ändern. Ebenso können Sie nutzen UpdateTextStyleRequest , um Formatierungen auf Textbereiche anzuwenden, die in einem oder mehreren Elementen enthalten sind.

Verwenden Sie zum Lesen von Elementen des Dokuments die documents.get-Methode, um eine JSON-Dump des vollständigen Dokuments. Anschließend können Sie die resultierenden JSON-Daten so parsen, die Werte einzelner Elemente zu ermitteln. Weitere Informationen finden Sie im Abschnitt zur Ausgabe Dokumentinhalt im JSON-Format.

Das Parsen des Inhalts kann für verschiedene Anwendungsfälle von Vorteil sein. Erwägen Sie, Beispiel: Eine Katalogisierungsanwendung mit einer Auflistung der gefundenen Dokumente. Diese App kann den Titel, die Überarbeitungs-ID und die Startseitennummer eines werden, wie im folgenden Diagramm dargestellt:

Struktur eines Dokumentenkatalogs.
Abbildung 7: Struktur eines Dokumentenkatalogs.

Da es keine Methoden zum expliziten Lesen dieser Einstellungen gibt, muss Ihre App um das gesamte Dokument abzurufen, und parsen Sie dann das JSON-Format, um diese Werte zu extrahieren.

Übernahme für Properties

Ein StructuralElement kann Eigenschaften von seinen übergeordneten Objekten erben. Eine -Objekteigenschaften enthält, einschließlich derjenigen, die definiert und übernommen werden, um ihr endgültiges visuelles Erscheinungsbild zu bestimmen.

Mit der Textzeichenformatierung wird bestimmt, wie Text in einem Dokument gerendert wird. Dazu gehören: fett, kursiv oder unterstrichen sein. Durch die angewendete Formatierung wird die Standardeinstellung überschrieben die aus den Einstellungen des zugrunde liegenden Absatzes TextStyle Umgekehrt können alle Zeichen, deren Formatierung Sie nicht festlegen, werden weiterhin aus dem Absatzstile.

Die Absatzformatierung bestimmt, wie Textblöcke in einem Dokument gerendert werden. wie Ausrichtung, Rahmen und Einzug. Die von Ihnen angewendete Formatierung überschreibt die Standardformatierung, die vom zugrunde liegenden ParagraphStyle übernommen wurde. Umgekehrt gilt für Formatierungsfunktionen, die Sie nicht festlegen, den Absatzstil ändern.