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. |
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 dasAutoText
-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 erstenParagraphMarker
-Element des übergeordneten Elements übernommen wird. - Vordergrundfarbe: Der Text wird mit der Vordergrundfarbe
DARK1
gerendert, die von der erstenTextRun
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 zweitenTextRun
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.
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 übernommenenforegroundColor
überein, sodass dieser Stil unverändert bleibt und weiterhin übernommen wird. - Zweiter Absatz: Der neue
foregroundColor
stimmt nicht mit dem übernommenenforegroundColor
überein. Daher wird die Vordergrundfarbe des zweiten Absatzes inDARK1
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.
- Für einen Aufzählungspunkt auf einer bestimmten Verschachtelungsebene wird zuerst die im Feld
NestingLevel.bullet_style
imList
-Objekt des Aufzählungszeichens festgelegteTextStyle
übernommen. - Als Nächstes wird der entsprechende
NestingLevel.bullet_style
imList
des übergeordneten Platzhalters übernommen. - Schließlich wird versucht, die Elemente von den verbleibenden übergeordneten Platzhalterobjekten zu übernehmen.