Textstruktur und -stil

In der Slides API kann Text in Formen oder Tabellenzellen enthalten sein. Bevor Sie Text bearbeiten und gestalten können, müssen Sie seine Struktur und die Funktionsweise der Gestaltung verstehen.

Auf dieser Seite wird beschrieben, wie Text in der Slides API dargestellt wird.

Sequenzen von Textelementen

Der in einer Form oder einer Tabellenzelle enthaltene Text besteht aus einer Folge von TextElement-Strukturen. Diese Sequenz stellt die Struktur von Text in der Reihenfolge dar, in der er von Anfang bis Ende erscheint.

Sehen wir uns zum Beispiel den Inhalt dieser Folie an, der alle in einem Textfeld enthalten ist:

Die Folie oben enthält ein Textfeld, dessen text-Feld eine Reihe von Textelementen enthält, wie im folgenden Diagramm dargestellt:

Konkret wird diese Textsequenz in der Slides API so dargestellt:

"textElements": [ {
    "endIndex": 224,
    "paragraphMarker": { "style": {} }
  }, {
    "endIndex": 130,
    "textRun": { "content": "Li lingues differe in li grammatica e li vocabules. Omnicos directe al desirabilite de un nov ", "style": {} }
  }, {
    "endIndex": 143,
    "startIndex": 130,
    "textRun": { "content": "lingua franca", "style": { "italic": True } }
  }, {
    "endIndex": 224,
    "startIndex": 143,
    "textRun": { "content": ": solmen va esser necessi far:\n", "style": {} }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "paragraphMarker": {
      "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
      "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "textRun": { "content": "uniform grammatica\n", "style": {} }
  }, {
    "endIndex": 257,
    "startIndex": 243,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 257,
    "startIndex": 243,
    "textRun": { "content": "Pronunciation\n", "style": {} }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "textRun": { "content": "plu sommun paroles.\n", "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "paragraphMarker": { "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "textRun": { "content": "Ka swu thefognay, tay waddeant varpa u inzo.\n", "style": {} }
}]

TextElement-Inhalte

Jedes Textelement enthält einen nullbasierten Startindex und einen Endindex, die die Position des Elements im vollständigen Text des Seitenelements beschreiben, sowie einen der folgenden Textobjekttypen:

Textart	Beschreibung
ParagraphMarker	Dieses Textelement stellt den Beginn eines neuen Absatzes dar. Der Start- und Endindex des Textelements stellt die gesamte Spanne des Absatzes dar, einschließlich des Zeilenumbruchzeichens, das den Absatz beendet. Ein Absatz überschneidet sich nie mit einem anderen Absatz. Absätze enden immer mit einem Zeilenumbruchzeichen. Deshalb steht am Ende des Textinhalts einer Form oder Tabellenzelle immer ein Zeilenumbruch. Absätze können zu Aufzählungslisten oder nummerierten Listen gehören. In diesem Fall enthält der Inhalt des Felds ParagraphMarker.bullet eine Listen-ID. Diese ID verweist auf ein Listenelement, das in TextContent neben der TextElement-Sequenz vorhanden ist. Absätze in derselben logischen Liste verweisen auf dieselbe Listen-ID.
TextRun	Dieses Textelement stellt eine zusammenhängende Textzeichenfolge dar, die alle denselben Textstil hat. Text übertritt nie Absatzgrenzen: Selbst wenn der Text, der einen Absatz endet, denselben Stil wie der Text hat, der den nächsten Absatz beginnt, wird der Inhalt nach dem Zeilenumbruchzeichen aufgeteilt, um separate Textausführungen zu bilden. Wenn Sie den vollständigen Textstring innerhalb eines Seitenelements verarbeiten müssen, durchgehen Sie alle Textelemente und verketten Sie die Strings in allen Textausführungen.
AutoText	Autotext bezieht sich auf Stellen im Text, die sich je nach Kontext dynamisch ändern. In Google Präsentationen wird damit die aktuelle Foliennummer im Text dargestellt.

Die Slides API kann in Zukunft weitere Textelementarten enthalten. Code, der Text verarbeitet, sollte neue Textelementtypen ordnungsgemäß verarbeiten, in der Regel, indem unbekannte Typen ignoriert werden.

Textinhalte ändern

Wenn Sie Text mit der Slides API ändern möchten, müssen Sie nicht alle entsprechenden Textelemente explizit erstellen. Stattdessen können Sie Text wie im Präsentationen-Editor bearbeiten: indem Sie Text einfügen, Bereiche löschen und Stile für Bereiche aktualisieren. Durch diese Vorgänge werden nach Bedarf implizit ParagraphMarker- und TextRun-Elemente erstellt, um Ihre Änderungen widerzuspiegeln.

Text einfügen

Mit der InsertTextRequest-Anfrage in einem Aufruf von batchUpdate können Sie Text in einen Index einfügen. Das Feld insertionIndex dieser Methode gibt an, wo der Text eingefügt werden soll. Sie können diesen Index mithilfe der Start- und Endindexfelder innerhalb von Textelementen berechnen.

Einige Nebeneffekte entsprechen dem Verhalten des Folieneditors für das Einfügen von Text:

• Durch das Einfügen eines Zeilenumbruchzeichens wird implizit ein neuer Absatz mit einem ParagraphMarker-Textelement erstellt, das beim Index des Zeilenumbruchs beginnt und am folgenden Zeilenumbruch endet. Der Absatzstil (einschließlich Aufzählungs- und Listendetails) wird vom aktuellen Absatz in den neuen Absatz kopiert.
• Der Stil der eingefügten Zeichen wird automatisch bestimmt, wobei in der Regel der Textstil beibehalten wird, der für den Einfügungsindex festgelegt war. Dadurch wird der Text normalerweise an diesem Index in die vorhandene TextRun-Datei eingefügt. Sie können diesen Stil später über eine UpdateTextStyle-Anfrage aktualisieren.

Text wird gelöscht

Mit der Nachricht DeleteTextRequest in einem Aufruf von batchUpdate können Sie einen Textbereich löschen. Das Löschen von Text erfordert einige Feinheiten:

• Beim Löschen, das eine Absatzgrenze überschreitet, werden die beiden Absätze zusammengeführt und das trennende Textelement ParagraphMarker wird gelöscht.
• Für den neu zusammengeführten Absatz wird ein kombinierter Absatzstil verwendet, der im Präsentationen-Editor entsprechend angepasst wird.
• Ein Löschvorgang, dessen Bereich eine Textausführung umfasst, entfernt den gesamten Inhalt aus einer Textausführung sowie die Textausführung selbst.
• Bei Löschvorgängen, deren Bereich ein AutoText-Element umfasst, wird auch das AutoText-Element gelöscht.

Textstil wird aktualisiert

Die gerenderte Darstellung von Text auf einer Folie wird durch die Eigenschaften des Textstils bestimmt:

• Absatzstile wie Einzug, Ausrichtung und Aufzählungszeichen werden durch Eigenschaften von Absatzmarkierungen definiert.
• Zeichenstile wie Fett-, Kursiv- und Unterstrich werden durch Eigenschaften in einzelnen Textläufen definiert.

Zeichenstil wird aktualisiert

Sie können Zeichenstile mithilfe der Nachricht UpdateTextStyleRequest in einem Aufruf von batchUpdate aktualisieren.

Wie bei anderen Textvorgängen wird der Zeichenstil auf einen Textbereich angewendet und erstellt bei Bedarf implizit neue TextRun-Objekte.

Wenn Sie einige Zeichenstile festlegen, werden andere verwandte Stile implizit aktualisiert, damit sie dem Verhalten im Präsentationen-Editor entsprechen. Wenn du z. B. einen Link hinzufügst, werden die Farbe für den Textvordergrund und das Unterstreichen automatisch geändert. Weitere Informationen finden Sie in der Referenzdokumentation zu TextStyle.

Absatzstil wird aktualisiert

Sie können Absatzstile mit der Nachricht UpdateParagraphStyleRequest in einem Aufruf von batchUpdate aktualisieren.

Die Slides API unterstützt eine CreateParagraphBulletsRequest, die die Funktionalität der Voreinstellungen für Aufzählungszeichen im Präsentationen-Editor zum Erstellen von Aufzählungslisten und nummerierten Listen widerspiegelt. In ähnlicher Weise entfernt DeleteParagraphBulletsRequest alle vorhandenen Aufzählungspunkte in Absätzen.

Übernommene Stile

Einige Formen, die als placeholders bezeichnet werden, können Textstile von anderen übergeordneten Formen übernehmen. Weitere Informationen zur Übernahme von Formen im Allgemeinen finden Sie unter placeholders.

In diesem Abschnitt wird beschrieben, wie die Stilübernahme funktioniert, um die endgültigen, gerenderten Textstile zu erstellen, die auf einer Folie angezeigt werden.

Stildarstellung in Platzhaltern

Im Abschnitt zu placeholders wird beschrieben, wie übergeordnete und untergeordnete Formen übernommen werden. Die Übernahme von Textstilen erfolgt durch zusätzliche Funktionen im Übernahmemodell:

• Mit den Eigenschaften von ParagraphMaker-Textelementen definieren Sie die Absatzformatierung.
• Mit den Eigenschaften von TextRun-Textelementen wird die Zeichenformatierung definiert.
• Der Inhalt übergeordneter Platzhalter enthält acht solcher ParagraphMarker/TextRun-Paare (zur Unterstützung der Listenverschachtelung auf acht Ebenen).
• Ein untergeordneter Platzhalter übernimmt die Standardtexteigenschaften von diesen Textelementen im Textinhalt des übergeordneten Platzhalters.

Das folgende Diagramm zeigt eine Möglichkeit, diese Beziehungen zu visualisieren:

Der erste ParagraphMarker/TextRun in der übergeordneten Form bestimmt den Großteil des übernommenen Textstils. Der Stil in den verbleibenden sieben Paaren wirkt sich nur auf Absätze in zunehmend tiefer verschachtelten Aufzählungsebenen aus:

Übergeordnetes Textelementpaar	Untergeordnete Formatierung, die damit gesteuert wird
Erste ParagraphMarker Erste TextRun	Textstil von Absätzen, die auf Ebene 0 (am Ende) stehen, und aller Absätze, die nicht zur Liste gehören.
Zweite ParagraphMarker Zweite TextRun	Textstil der verbleibenden (verschachtelten) Listenebenen 1 bis 7
Dritter ParagraphMarker Dritter TextRun
Vierter ParagraphMarker Vierter TextRun
Fünfter ParagraphMarker 5. TextRun
Sechste ParagraphMarker Sechste TextRun
7. ParagraphMarker 7. TextRun
Achte ParagraphMarker 8. TextRun

Für den Zugriff auf diese Textelementpaare verwenden Sie den expliziten Index im Feld textElements, wie im folgenden Snippet gezeigt. Hier wird der Standardstil (übernommen) für Ebene 0 und Absätze ohne Liste festgelegt:

"text": {
  "textElements": [  {
     "startIndex": 0,
     "endIndex": 1,
     "paragraphMarker": {
       "style": {  "alignment": "START",  ...  },
       "bullet": {  "nestingLevel": 0,  ...  }
     }
   },{
     "startIndex": 0,
     "endIndex": 1,
     "textRun": {
       "content": "\n",
       "style": {  "foregroundColor": {  "opaqueColor": {  "themeColor": "DARK1"  }  },  }
     }
   },{
     ...
   } ]
 }

Das Feld content der TextRun einer übergeordneten Form besteht immer aus einem einzelnen Zeilenumbruchzeichen.

Übernommene Stile können überschrieben werden

Mit einer untergeordneten Form können Stileigenschaften für die Elemente ParagraphMarker und TextRun in ihrem Inhalt festgelegt werden. Diese lokal angegebenen Attribute überschreiben alle übernommenen Attribute innerhalb ihres lokalen Geltungsbereichs. Für Elemente, für die kein Stil angegeben ist, wird der entsprechende, vom übergeordneten Element übernommene Stil verwendet.

Wenn Sie eine explizite Stileigenschaft aus einer untergeordneten Form entfernen, sodass sie nicht mehr festgelegt ist, wird sie von der übergeordneten Form übernommen.

Beispiel

Angenommen, die Form ParentPlaceholder hat bei der im obigen Diagramm gezeigten Vererbung folgenden Textinhalt:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {"alignment": "START", ...},
        "bullet": {"nestingLevel": 0, ...}
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, }
        ...
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {"alignment": "END", ...},
        "bullet": {"nestingLevel": 1, ...}
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "LIGHT1"} }, ...}
      }
    },
   ...
  ]
}

Angenommen, die Form ChildPlaceholder hat folgenden Textinhalt:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    {  "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {
          "nestingLevel": 1,
          "listId": "someListId",
          "glyph": "●"
        }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {},
        ...
      }
    }
  ]
}

Daraus ergeben sich die in den folgenden Abschnitten beschriebenen Ergebnisse.

Stilübernahme für einen einfachen Absatz

Der erste Absatz der untergeordneten Form, der den Text "Dies ist mein erster Absatz" enthält, ist ein einfacher Absatz und nicht in einer Liste. In seinem Textinhalt sind keine Stileigenschaften angegeben. Daher werden alle Zeichen- und Absatzstile des übergeordneten Elements übernommen. Dies führt zu folgendem Rendering:

• Text: „Das ist mein erster Absatz“ ist der gerenderte Text. Der Text selbst wird nie übernommen.
• Ausrichtung: Der Text wird mit der START-Ausrichtung gerendert, die vom ersten ParagraphMarker-Element des übergeordneten Elements übernommen wird.
• Vordergrundfarbe: Der Text wird mit der Vordergrundfarbe DARK1 gerendert, die von der ersten TextRun des übergeordneten Elements übernommen wird.

Stilübernahme für einen Listenabsatz

Der nächste Absatz, der den Text „Dieser Absatz befindet sich in einer Liste“ enthält, wird auf Verschachtelungsebene 1 in einer Aufzählungsliste aufgeführt, da das Feld bullet für das entsprechende ParagraphMarker-Feld auf diese Ebene gesetzt ist. Daher wird der Text- und Absatzstil der Verschachtelungsebene 1 der übergeordneten Ebene übernommen. Dies führt zu folgendem Rendering:

• Text: „Dieser Absatz befindet sich in einer Liste“ ist der gerenderte Text. Der Text selbst wird nie übernommen.
• Ausrichtung: Der Text wird mit der Endung-Ausrichtung gerendert, die von der zweiten ParagraphMarker des übergeordneten Elements übernommen wird.
• Vordergrundfarbe: Der Text wird mit der Textvordergrundfarbe LIGHT1 gerendert, die von der zweiten TextRun des übergeordneten Elements übernommen wird.

Interaktionen zwischen dem Aktualisieren und Übernehmen von Text- und Absatzstilen

Textstile, die nicht in einer untergeordneten Form festgelegt sind, übernehmen die Werte der übergeordneten Form. Textstile, die in der untergeordneten Datei festgelegt werden, „überschreiben“ die übergeordneten Werte in einem lokalen Bereich.

Mithilfe von UpdateTextStyleRequest können Sie den Textstil einer untergeordneten Form aufheben, sodass diese keine lokale Überschreibung mehr hat und daher deren Stile von der übergeordneten Form übernimmt. Wenn Sie außerdem den Textstil des untergeordneten Elements aktualisieren, damit er mit dem von einem übergeordneten Element übernommenen Wert übereinstimmt, wird der Stil implizit deaktiviert, sodass der übernommene Wert verwendet wird.

Wenn der Stil einer untergeordneten Form so festgelegt wird, dass er genau mit dem der übergeordneten Form übereinstimmt (wodurch der Stil übernommen wird), ist das Ergebnis genauso wie beim Aufheben des Stils der untergeordneten Form.

Dies hat keinen Einfluss auf die visuelle Darstellung von Text direkt nach einer Aktualisierung. Es kann jedoch eine Rolle spielen, wenn Sie später einen Absatz oder den Textstil in einem übergeordneten Platzhalter aktualisieren. Dieses Übernahmeverhalten entspricht dem Verhalten des Präsentationen-Editors, sodass Sie mit den Ergebnissen von Stiländerungen experimentieren können, bevor Sie mit der API arbeiten.

Beispiel

Sehen Sie sich die Definitionen im vorherigen Beispiel für ChildPlaceholder und ParentPlaceholder an.

Angenommen, Sie senden folgende UpdateTextStyleRequest:

{ "updateTextStyle": {
    "objectId": "ChildPlaceholder",
    "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
    "textRange": { "type": "ALL" },
    "fields": "foregroundColor"
  }
}

Bei dieser Anfrage wird versucht, eine Vordergrundfarbe von DARK1 auf den gesamten Text von ChildPlaceholder festzulegen. Dabei wird mit einer Feldmaske angegeben, dass sich nur die Vordergrundfarbe des Elements ändern soll. Diese Anfrage führt zu folgenden Ergebnissen:

• Erster Absatz: Der neue foregroundColor stimmt mit dem übernommenen foregroundColor überein, sodass dieser Stil unverändert bleibt und weiterhin übernommen wird.
• Zweiter Absatz: Der neue foregroundColor stimmt nicht mit dem übernommenen foregroundColor überein. Daher wird die Vordergrundfarbe des zweiten Absatzes in DARK1 geändert.

Der Textinhalt von ChildPlaceholder lautet jetzt:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {"nestingLevel": 1, "listId": "someListId", "glyph": "●" }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
        ...
      }
    }
  ]
}

Textstil für Aufzählungszeichen

Wie normaler Text haben Aufzählungszeichen einen Textstil, der steuert, wie das Symbol gerendert wird. Diese Textstile können nicht direkt mit der Slides API geändert werden. Wenn Sie jedoch mit UpdateTextStyleRequest einen vollständigen Absatz aktualisieren, der ein Aufzählungszeichen enthält, aktualisiert die Slides API den Textstil des Aufzählungszeichen-Symbols entsprechend.

Die Textstile des Aufzählungszeichens folgen einer etwas anderen Vererbungshierarchie als normale Textstile.

1. Für einen Aufzählungspunkt auf einer bestimmten Verschachtelungsebene wird zuerst die im Feld NestingLevel.bullet_style im List-Objekt des Aufzählungszeichens festgelegte TextStyle übernommen.
2. Als Nächstes wird der entsprechende NestingLevel.bullet_style im List des übergeordneten Platzhalters übernommen.
3. Schließlich wird versucht, die Elemente von den verbleibenden übergeordneten Platzhalterobjekten zu übernehmen.

Bei Aufzählungszeichen in Platzhaltern in Layouts und Mastern ist der Wert für „TextStyle“ im Feld „ParagraphMarker.bullet“ leer. Textstiländerungen in diesen Absätzen werden nur in den Nachrichten vom Typ „List“ berücksichtigt.