Structure et style du texte

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.

À l'avenir, l'API Slides pourra inclure d'autres types d'éléments textuels. Le code qui traite le texte doit gérer correctement les nouveaux genres d'éléments textuels, généralement en ignorant les genres inconnus.

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ément AutoText.

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ément ParagraphMarker du parent.
• Couleur de premier plan: le texte s'affiche avec une couleur de premier plan DARK1, héritée de la première TextRun 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 valeur TextRun 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.

Si vous définissez le style d'une forme enfant pour qu'il corresponde exactement à celui de sa forme parent (elle hérite alors du style), vous obtenez le même résultat lorsque vous annulez le style de la forme enfant.

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 à la foregroundColor héritée. Ce style reste donc inchangé et hérite toujours.
• Deuxième paragraphe: la nouvelle foregroundColor ne correspond pas à la foregroundColor héritée. La couleur de premier plan du deuxième paragraphe est donc remplacée par DARK1.

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.

1. À un certain niveau d'imbrication, une puce hérite d'abord de l'élément TextStyle défini dans le champ NestingLevel.bullet_style au sein de l'objet List de la puce.
2. Il hérite ensuite du NestingLevel.bullet_style correspondant dans le List de son espace réservé parent.
3. Enfin, il cherche à hériter des objets d'espace réservé parents restants.

Les puces des espaces réservés dans les mises en page et les masques présentent un paramètre "TextStyle" vide dans le champ "ParagraphMarker.bullet", et les modifications de style de texte apportées à ces paragraphes ne seront reflétées que dans les messages "List".