Dans l'API Slides, le texte peut être contenu dans des formes ou dans des cellules de tableau. Avant de pouvoir manipuler et styliser le texte, vous devez comprendre sa structure et son fonctionnement.
Cette page explique comment le texte est représenté dans l'API Slides.
Séquences d'éléments de texte
Le texte contenu dans une forme ou une cellule de tableau est constitué d'une séquence de structures TextElement. Cette séquence représente la structure du texte, dans l'ordre dans lequel il apparaît du début à la fin.
Par exemple, considérez le contenu de cette diapositive, qui se trouve dans une seule zone de texte:
La diapositive ci-dessus comporte une zone de texte, dont le champ text
contient une séquence d'éléments de texte, comme illustré dans le schéma suivant:
Plus concrètement, cette séquence de texte est représentée dans l'API Slides comme suit:
"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": {} }
}]
Contenu de TextElement
Chaque élément textuel contient un index de départ et un index de fin de base zéro, qui décrivent l'emplacement de l'élément dans le texte complet de l'élément de page, ainsi que l'un des types d'objet texte suivants:
Type de texte | Description |
---|---|
ParagraphMarker | Cet élément de texte représente le début d'un nouveau paragraphe. Les index de début et de fin de l'élément textuel représentent toute la longueur du paragraphe, y compris le caractère de retour à la ligne qui termine le paragraphe. Un paragraphe ne chevauche jamais un autre paragraphe. Les paragraphes se terminent toujours par une nouvelle ligne. Par conséquent, une nouvelle ligne apparaît toujours à la fin du contenu textuel d'une forme ou d'une cellule de tableau. Les paragraphes peuvent appartenir à des listes à puces ou numérotées. Si tel est le cas, le contenu du champ ParagraphMarker.bullet inclut un ID de liste. Cet ID fait référence à un élément de liste qui existe dans TextContent , à côté de la séquence TextElement . Les paragraphes d'une même liste logique font référence au même ID de liste. |
TextRun | Cet élément de texte représente une chaîne de texte contiguë ayant le même style. Le texte ne dépasse jamais les limites du paragraphe. Même si le texte qui se termine au paragraphe suivant a le même style que celui du paragraphe suivant, le contenu est divisé après le caractère de retour à la ligne pour former un texte distinct. Si vous devez traiter la chaîne de texte complète dans un élément de page, itérez tous les éléments de texte en concaténant les chaînes trouvées dans tous les affichages de texte. |
AutoText | Le texte automatique désigne des parties du texte qui changent de façon dynamique en fonction du contexte. Dans Slides, il est utilisé pour représenter le numéro de diapositive actuel dans le texte. |
Modification du contenu du texte
Lorsque vous devez modifier du texte à l'aide de l'API Slides, vous n'avez pas besoin de créer explicitement tous les éléments de texte appropriés. À la place, vous pouvez effectuer des opérations sur du texte comme vous le feriez dans l'éditeur Slides: en insérant du texte, en supprimant des plages et en modifiant les styles des plages. Ces opérations créent implicitement des éléments ParagraphMarker
et TextRun
si nécessaire pour refléter vos modifications.
Insertion de texte
Vous pouvez insérer du texte au niveau d'un index à l'aide de la requête InsertTextRequest dans un appel à batchUpdate. Le champ insertionIndex
de cette méthode spécifie où insérer le texte. Vous pouvez calculer cet index à l'aide des champs d'index de début et de fin dans les éléments de texte.
L'insertion de texte présente des effets secondaires qui reflètent le comportement de l'éditeur Slides:
- L'insertion d'un caractère de nouvelle ligne crée implicitement un paragraphe et crée un élément de texte
ParagraphMarker
qui commence à l'index de la nouvelle ligne et se termine à la ligne suivante. Le style de paragraphe, y compris les détails des puces et des listes, est copié du paragraphe actuel vers le nouveau. - Le style des caractères insérés est déterminé automatiquement et conserve généralement le même style de texte que celui qui existait au niveau de l'index d'insertion. Par conséquent, le texte est généralement inséré dans le
TextRun
existant au niveau de cet indice. Vous pourrez mettre à jour ce style ultérieurement à l'aide d'une requête UpdateTextStyle.
Suppression du texte...
Vous pouvez supprimer une plage de texte à l'aide du message DeleteTextRequest dans un appel à batchUpdate. La suppression de texte implique certaines subtilités:
- Une suppression qui traverse une limite de paragraphe fusionne les deux paragraphes, en supprimant l'élément de texte
ParagraphMarker
qui le sépare. - Le nouveau paragraphe fusionné utilisera un style de paragraphe combiné, qui correspond au comportement dans l'éditeur Slides.
- Une suppression dont la plage englobe une exécution de texte supprime tout le contenu d'une exécution de texte et supprime également l'exécution de texte elle-même.
- Une suppression dont la plage comprend un élément
AutoText
supprime l'élémentAutoText
.
Modification du style du texte...
L'apparence du texte d'une diapositive est déterminée par les propriétés du style de texte:
- Les styles de paragraphe, comme le retrait, l'alignement et les glyphes de puces, sont définis par les propriétés des repères de paragraphe.
- Les styles de caractères (gras, italique et souligné, par exemple) sont définis par les propriétés de chaque exécution de texte.
Modifier le style des personnages
Vous pouvez mettre à jour les styles de caractères à l'aide du message UpdateTextStyleRequest dans un appel à batchUpdate.
Comme pour d'autres opérations textuelles, le style de caractère est appliqué à une plage de texte et crée implicitement de nouveaux objets TextRun
si nécessaire.
La définition de certains styles de caractères met implicitement à jour d'autres styles associés pour qu'ils correspondent au comportement dans l'éditeur Slides. Par exemple, l'ajout d'un lien modifie automatiquement les propriétés de couleur de premier plan et de soulignement du texte. Pour en savoir plus, consultez la documentation de référence sur TextStyle.
Mise à jour du style de paragraphe
Vous pouvez mettre à jour les styles de paragraphe à l'aide du message UpdateParagraphStyleRequest dans un appel à batchUpdate.
L'API Slides accepte une requête CreateParagraphBulletsRequest qui reflète la fonctionnalité des préréglages de puce dans l'éditeur Slides pour créer des listes à puces et des listes numérotées. De même, DeleteParagraphBulletsRequest supprime toutes les puces existantes dans les paragraphes.
Styles hérités
Certaines formes, appelées placeholders, peuvent hériter des styles de texte d'autres formes parentes. Consultez la section placeholders pour en savoir plus sur l'héritage des formes en général.
Cette section se concentre sur le fonctionnement de l'héritage des styles pour créer les styles de texte finaux affichés dans une diapositive.
Représentation du style dans les espaces réservés
La section sur les placeholders décrit le fonctionnement de l'héritage entre les formes parentes et enfants. L'héritage des styles de texte est géré par des fonctionnalités supplémentaires dans le modèle d'héritage:
- Les propriétés des éléments de texte ParagraphMaker définissent la mise en forme des paragraphes.
- Les propriétés des éléments de texte TextRun définissent la mise en forme des caractères.
- Le contenu des espaces réservés parents contient huit paires ParagraphMarker/TextRun de ce type (pour prendre en charge huit niveaux d'imbrication de liste).
- Un espace réservé enfant hérite ses propriétés de texte par défaut de ces éléments de texte dans le contenu textuel de son parent.
Le diagramme suivant montre une façon de visualiser ces relations:
Le premier ParagraphMarker/TextRun de la forme parente détermine la majeure partie du style de texte hérité. Le style des sept paires restantes n'affecte que les paragraphes à des niveaux de puces de plus en plus imbriqués:
Paire d'éléments textuels parent | Mise en forme enfant qu'il contrôle |
---|---|
Premières ParagraphMarker premières TextRun |
Style de texte des paragraphes de liste de niveau 0 (le plus externe) et de tous les paragraphes qui ne sont pas de type liste. |
Deuxième ParagraphMarker Deuxième TextRun |
Style de texte des niveaux de liste (imbriqués) restants 1 à 7 |
Troisième ParagraphMarker Troisième TextRun |
|
Quatrième ParagraphMarker Quatrième TextRun |
|
Cinquième ParagraphMarker Cinquième TextRun |
|
Sixième ParagraphMarker Sixième TextRun |
|
Septième ParagraphMarker Septième TextRun |
|
Huitième ParagraphMarker Huitième TextRun |
Pour accéder à ces paires d'éléments de texte, utilisez leur index explicite dans le champ textElements
, comme indiqué dans l'extrait ci-dessous, qui montre comment définir le style par défaut (hérité) des paragraphes de niveau 0 et qui ne sont pas des listes:
"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" } }, }
}
},{
...
} ]
}
Notez que le champ content
du TextRun
d'une forme parente se compose toujours d'un seul caractère de retour à la ligne.
Les styles hérités peuvent être remplacés
Une forme enfant peut spécifier des propriétés de style sur les éléments ParagraphMarker et TextRun dans son contenu. Ces propriétés spécifiées localement remplacent toutes les propriétés héritées dans leur champ d'application local. Les éléments qui ne spécifient aucun style utiliseront le style correspondant hérité du parent.
Si vous supprimez une propriété de style explicite d'une forme enfant pour qu'elle ne soit plus définie, elle héritera de la forme parente.
Exemple
Compte tenu de l'héritage présenté dans le schéma ci-dessus, supposons que la forme ParentPlaceholder
ait le contenu textuel suivant:
"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"} }, ...}
}
},
...
]
}
Supposons aussi que la forme ChildPlaceholder
ait le contenu textuel suivant:
"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": {},
...
}
}
]
}
Vous obtenez ainsi les résultats décrits dans les paragraphes suivants.
Héritage des styles pour un paragraphe simple
Le premier paragraphe de la forme enfant, qui comprend le texte "This is my first paragraph", est un paragraphe simple (pas dans une liste). Aucun élément dans son contenu textuel ne spécifie de propriétés de style. Il hérite donc de tous ses styles de caractères et de paragraphe de son parent. Cela entraîne l'affichage suivant:
- Text: "Ceci est mon premier paragraphe" correspond au texte affiché. Le texte lui-même n'est jamais hérité.
- Alignement: le texte est affiché avec un alignement
START
, hérité du premier élémentParagraphMarker
du parent. - Couleur de premier plan: le texte s'affiche avec une couleur de premier plan
DARK1
, héritée de la premièreTextRun
du parent.
Héritage des styles pour un paragraphe de liste
Le paragraphe suivant, qui inclut le texte "This paragraph is in a list" (Ce paragraphe se trouve dans une liste), se trouve dans une liste à puces au niveau d'imbrication 1, car le champ bullet
du ParagraphMarker
correspondant est défini sur ce niveau. Par conséquent, il hérite du style de texte et de paragraphe du niveau d'imbrication 1 dans le parent. Cela se traduit par le rendu suivant:
- Texte: "Ce paragraphe figure dans une liste" correspond au texte affiché. Le texte lui-même n'est jamais hérité.
- Alignement: le texte est affiché avec un alignement "END", hérité de l'élément
ParagraphMarker
du parent. - Couleur de premier plan: le texte s'affiche avec une couleur de premier plan
LIGHT1
, héritée de la deuxième valeurTextRun
du parent.
Interactions entre la mise à jour et l'héritage des styles de texte et de paragraphe
Les styles de texte qui ne sont pas définis dans une forme enfant héritent des valeurs de son parent. Les styles de texte définis dans l'élément enfant "remplacent" les valeurs parentes dans certains champs d'application locaux.
Vous pouvez utiliser une requête UpdateTextStyleRequest pour annuler la définition du style de texte d'une forme enfant, afin qu'elle ne présente plus de forçage local et qu'elle hérite ainsi des syltes de la forme parente. En outre, la mise à jour du style de texte de l'élément enfant pour qu'il corresponde à la valeur héritée d'un parent désactive implicitement le style afin qu'il utilise la valeur héritée.
Cela n'affecte pas l'apparence visuelle du texte immédiatement après une mise à jour, mais cela peut être important si vous mettez à jour ultérieurement un style de paragraphe ou de texte dans un espace réservé parent. Ce comportement d'héritage correspond à celui de l'éditeur Slides. Vous pouvez donc tester les résultats des changements de style avant de travailler avec l'API.
Exemple
Examinez les définitions de ChildPlaceholder
et ParentPlaceholder
de l'exemple précédent.
Supposons maintenant que vous envoyez cette requête UpdateTextStyleRequest:
{ "updateTextStyle": {
"objectId": "ChildPlaceholder",
"style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
"textRange": { "type": "ALL" },
"fields": "foregroundColor"
}
}
Cette requête tente de définir une couleur de premier plan DARK1
pour tout le texte de ChildPlaceholder en utilisant un masque de champ pour indiquer que seule la couleur de premier plan de l'élément doit être modifiée. Cette requête aboutit aux résultats suivants:
- Premier paragraphe: la nouvelle
foregroundColor
correspond à laforegroundColor
héritée. Ce style reste donc inchangé et hérite toujours. - Deuxième paragraphe: la nouvelle
foregroundColor
ne correspond pas à laforegroundColor
héritée. La couleur de premier plan du deuxième paragraphe est donc remplacée parDARK1
.
Désormais, le contenu textuel de ChildPlaceholder est le suivant:
"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"} }, },
...
}
}
]
}
Style de texte du glyphe à puces
Comme pour le texte normal, les glyphes des puces ont un style de texte qui contrôle leur rendu. Ces styles de texte ne peuvent pas être modifiés directement à l'aide de l'API Slides. Toutefois, si vous utilisez UpdateTextStyleRequest pour mettre à jour un paragraphe complet incluant une puce, l'API Slides met à jour le style de texte du glyphe de la puce en conséquence.
Les styles de texte des glyphes à puces suivent une hiérarchie d'héritage légèrement différente de celle des styles de texte normaux.
- À un certain niveau d'imbrication, une puce hérite d'abord de l'élément
TextStyle
défini dans le champNestingLevel.bullet_style
au sein de l'objetList
de la puce. - Il hérite ensuite du
NestingLevel.bullet_style
correspondant dans leList
de son espace réservé parent. - Enfin, il cherche à hériter des objets d'espace réservé parents restants.