Structure et style du texte

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Dans l'API Slides, le texte peut être contenu dans des formes ou dans des cellules de tableau. Avant de pouvoir manipuler et styliser du texte, vous devez comprendre sa structure et le fonctionnement du style.

Cette page explique comment le texte est représenté dans l'API Slides.

Séquences d'éléments textuels

Le texte contenu dans une forme ou une cellule de tableau est composé 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.

Prenons l'exemple du contenu de cette diapositive, qui est entièrement contenu 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 diagramme 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": {} }
}]

Contenus TextElement

Chaque élément de texte contient un index de début et un index de fin basés sur 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'objets de texte suivants:

Modifier le contenu textuel

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. Vous pouvez plutôt travailler sur le texte comme vous le feriez dans l'éditeur Slides: en insérant du texte, en supprimant des plages et en mettant à jour les styles sur les plages. Ces opérations créent implicitement des éléments ParagraphMarker et TextRun si nécessaire pour refléter vos modifications.

Insérer du texte

Vous pouvez insérer du texte à 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 indice à l'aide des champs d'index de début et de fin dans les éléments de texte.

L'insertion de texte a des effets secondaires qui reflètent le comportement de l'éditeur de diapositives:

• L'insertion d'un caractère de nouvelle ligne crée implicitement un nouveau paragraphe, créant un élément de texte ParagraphMarker qui commence à l'index de la nouvelle ligne et se termine à la nouvelle ligne suivante. Le style de paragraphe, y compris les puces et les détails de la liste, est copié du paragraphe actuel vers le nouveau paragraphe.
• Le style des caractères insérés est déterminé automatiquement, en conservant généralement le même style de texte que celui qui existait à l'index d'insertion. Par conséquent, le texte est généralement inséré dans l'TextRun existant à cet indice. Vous pouvez modifier ce style ultérieurement à l'aide d'une requête UpdateTextStyle.

Supprimer 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, supprimant l'élément de texte ParagraphMarker séparateur.
• Le nouveau paragraphe fusionné utilisera un style de paragraphe combiné, correspondant au comportement dans l'éditeur de diapositives.
• Une suppression dont la plage englobe une séquence de texte supprime tout le contenu d'une séquence de texte, et supprime également la séquence de texte elle-même.
• Une suppression dont la plage englobe un élément AutoText supprime l'élément AutoText.

Modifier le style du texte

L'apparence du texte affiché sur une diapositive est déterminée par les propriétés du style de texte:

• Les styles de paragraphe, tels que l'indentation, 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, tels que le gras, l'italique et le souligné, sont définis par des propriétés sur des passages de texte individuels.

Modifier le style des personnages

Vous pouvez modifier les styles de caractères à l'aide du message UpdateTextStyleRequest dans un appel à batchUpdate.

Comme les autres opérations de texte, le style de caractère est appliqué à une plage de texte et crée implicitement de nouveaux objets TextRun si nécessaire.

Définir certains styles de caractères met à jour implicitement d'autres styles associés pour qu'ils correspondent au comportement dans l'éditeur de diapositives. Par exemple, l'ajout d'un lien modifie automatiquement la couleur de premier plan du texte et les propriétés de soulignement. Pour en savoir plus, consultez la documentation de référence sur TextStyle.

Modifier le style de paragraphe

Vous pouvez mettre à jour les styles de paragraphe à l'aide du message UpdateParagraphStyleRequest dans un appel à batchUpdate.

L'API Slides est compatible avec une CreateParagraphBulletsRequest qui reflète les fonctionnalités des préréglages de puces dans l'éditeur Slides pour créer des listes à puces et numérotées. De même, DeleteParagraphBulletsRequest supprime tous les puces existantes des paragraphes.

Styles hérités

Certaines formes, appelées espaces réservés, peuvent hériter de styles de texte d'autres formes parentes. Pour en savoir plus sur l'héritage de formes en général, consultez la section Espaces réservés.

Cette section explique comment l'héritage de style fonctionne pour créer les styles de texte finalisés affichés dans une diapositive.

Représentation du style dans les espaces réservés

La section sur les espaces réservés décrit le fonctionnement de l'héritage entre les formes parent et enfant. L'héritage des styles de texte est géré par des fonctionnalités supplémentaires du 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 parent contient huit paires ParagraphMarker/TextRun (pour prendre en charge huit niveaux d'imbrication de listes).
• Un espace réservé enfant hérite de ses propriétés de texte par défaut de ces éléments de texte dans le contenu textuel de son parent.

Le schéma suivant montre une façon de visualiser ces relations:

Le premier ParagraphMarker/TextRun de la forme parente détermine la plupart des styles de texte hérités. Le style des sept autres paires n'affecte que les paragraphes à des niveaux de puces de plus en plus imbriqués:

Pour accéder à ces paires d'éléments textuels, utilisez leur indice explicite dans le champ textElements, comme illustré dans l'extrait ci-dessous, qui montre comment définir le style par défaut (héréditaire) pour les paragraphes de niveau 0 et non de liste:

"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 de l'TextRun d'une forme parente se compose toujours d'un seul caractère de nouvelle ligne.

Les styles hérités peuvent être ignoré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 portée locale. 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, de sorte qu'elle ne soit plus définie, elle héritera du parent.

Exemple

Compte tenu de l'héritage illustré dans le diagramme 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 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": {},
        ...
      }
    }
  ]
}

Cela entraîne les résultats décrits dans les paragraphes suivants.

Héritage de style pour un paragraphe simple

Le premier paragraphe de la forme enfant, qui inclut le texte "Ceci est mon premier paragraphe", est un paragraphe simple (et non une liste). Aucun élément de 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 paragraphes de son parent. Le rendu suivant s'affiche:

• Texte: "This is my first paragraph" (Ceci est mon premier paragraphe) est le 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 ParagraphMarker du parent.
• Couleur de premier plan: le texte est affiché avec la couleur de premier plan DARK1, héritée du premier TextRun du parent.

Héritage de style pour un paragraphe de liste

Le paragraphe suivant, qui inclut le texte "Ce paragraphe figure dans une liste", se trouve dans une liste à puces au niveau d'imbrication 1, car son ParagraphMarker correspondant a son champ bullet 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. Le rendu suivant s'affiche:

• Texte: "Ce paragraphe figure dans une liste" est le texte affiché. Le texte lui-même n'est jamais hérité.
• Alignement: le texte est affiché avec un alignement "END", hérité du deuxième ParagraphMarker du parent.
• Couleur de premier plan: le texte est affiché avec la couleur de premier plan du texte LIGHT1, héritée du deuxième 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 un certain champ d'application local.

Vous pouvez utiliser une UpdateTextStyleRequest pour définir le style de texte d'une forme enfant afin qu'elle n'ait plus de forçage local et qu'elle hérite de ses styles de la forme parente. De plus, la mise à jour du style de texte de l'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'a aucune incidence sur l'apparence visuelle du texte immédiatement après une mise à jour, mais cela peut avoir de l'importance si vous mettez à jour ultérieurement un paragraphe ou un style de texte dans un espace réservé parent. Ce comportement d'héritage correspond à celui de l'éditeur de diapositives. Vous pouvez ainsi tester les résultats des modifications de style avant de travailler avec l'API.

Exemple

Prenons les définitions de ChildPlaceholder et ParentPlaceholder dans l'exemple précédent.

Supposons maintenant que vous envoyez cette 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 sur l'ensemble du texte de ChildPlaceholder, à l'aide d'un masque de champ pour spécifier que seule la couleur de premier plan de l'élément doit changer. Cette requête a les résultats suivants:

• Premier paragraphe: Le nouveau foregroundColor correspond au foregroundColor hérité. Ce style n'est donc pas modifié et hérite toujours.
• Deuxième paragraphe: le nouvel élément foregroundColor ne correspond pas à l'élément foregroundColor hérité. La couleur de premier plan du deuxième paragraphe est donc mise à jour avec DARK1.

Le contenu textuel de ChildPlaceholder est désormais 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 de puce

Comme le texte normal, les glyphes de puces ont un style de texte qui contrôle l'affichage du glyphe. Ces styles de texte ne peuvent pas être modifiés directement à l'aide de l'API Slides. Toutefois, si vous utilisez un UpdateTextStyleRequest pour mettre à jour un paragraphe complet incluant une puce, l'API Slides met à jour le style de texte du glyphe de puce pour qu'il corresponde.

Les styles de texte de glyphes de puces suivent une hiérarchie d'héritage légèrement différente de celle des styles de texte normaux.

1. Un point à un certain niveau d'imbrication hérite d'abord de l'TextStyle défini dans le champ NestingLevel.bullet_style de l'objet List du point.
2. Il hérite ensuite de l'NestingLevel.bullet_style correspondante dans le List de son espace réservé parent.
3. Enfin, il cherche à hériter des objets d'espace réservé parent restants.