Pages, éléments de page et propriétés

Pour utiliser efficacement l'API Slides, vous devez comprendre l'architecture des présentations et de leurs composants, ainsi que les interactions entre ces composants. Cette page fournit une présentation détaillée des sujets suivants :

Modèle conceptuel des composants de la présentation
Comment l'API représente ces composants
Propriétés de style des composants

La lecture de cette présentation et des autres présentations de concepts vous permettra de mieux comprendre et d'utiliser les guides pratiques, la documentation de référence et les exemples de recettes.

Présentations, pages et éléments de page

L'élément conteneur le plus externe dans Google Slides est une présentation. Il s'agit de l'unité qui peut être enregistrée dans Google Drive, partagée avec d'autres utilisateurs, etc.

Chaque présentation contient différents types de pages. Un type de page est une diapositive, c'est-à-dire les pages que les utilisateurs voient et entre lesquelles ils basculent lorsque la présentation est affichée à l'écran.

Chaque page contient un certain nombre d'éléments de page qui, ensemble, constituent le contenu de la page, comme le montre le schéma suivant :

Schéma de l'architecture des diapositives

En plus des diapositives, il existe d'autres types de pages qui vous permettent d'appliquer une conception à plusieurs diapositives différentes, ce qui crée une apparence cohérente. Ces autres types de pages sont les masques et les mises en page. Leurs propriétés déterminent la façon dont les diapositives sont affichées, comme le montre le schéma suivant :

Schéma de l'architecture des thèmes

Pages maîtres : la page maître a une double finalité. Les espaces réservés du masque contiennent les valeurs par défaut des styles de texte utilisés dans votre présentation. L'arrière-plan et toutes les autres formes du masque constituent l'arrière-plan par défaut de toutes les diapositives basées sur ce masque. Si vous souhaitez que le logo de votre entreprise s'affiche sur chaque diapositive de votre présentation, placez-le sur le masque.

Mises en page : les modèles de mise en page déterminent la façon dont le contenu est organisé sur chaque type de diapositive. Si vous souhaitez que toutes vos diapositives de titre aient une certaine apparence, vous pouvez par exemple modifier le modèle de mise en page du titre.

Il existe deux autres types de pages (pages de notes et pages de notes principales) qui sont surtout utiles pour travailler avec les notes du présentateur.

Types et structure de représentation de l'API

Cette section décrit comment le modèle conceptuel Google Slides, tel que décrit ci-dessus, est représenté dans l'API Slides.

Le diagramme suivant illustre la relation entre les présentations, les pages et les éléments de page en tant que types dans l'API Slides :

diagramme de style ERD

Les sections suivantes montrent comment ces types sont représentés au format JSON.

Présentations

Une présentation inclut un certain nombre de propriétés et contient les pages qui la composent :

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

Pages

Une page inclut un ensemble de propriétés et contient les éléments de page qui s'y trouvent :

{
  "objectId": string,
  "pageType": enum(PageType),
  "pageElements": [ { object(PageElement) } ],
  "pageProperties": { object(PageProperties) },

  // Union field properties can be only one of the following:
  "slideProperties": { object(SlideProperties) },
  "layoutProperties": { object(LayoutProperties) },
  "notesProperties": { object(NotesProperties) },
  // End of list of possible types for union field properties.
}

Éléments de la page

Les éléments de page sont les composants visuels placés sur les pages. Un élément de page dans l'API contient un certain nombre de propriétés, y compris un champ qui varie en fonction du type d'élément de page :

{
  "objectId": string,
  "size": { object(Size) },
  "transform": { object(AffineTransform) },
  "title": string,
  "description": string,

  // Union field element_kind can be only one of the following:
  "elementGroup": { object(Group) },
  "shape": { object(Shape) },
  "image": { object(Image) },
  "video": { object(Video) },
  "line": { object(Line) },
  "table": { object(Table) },
  "wordArt": { object(WordArt) },
  "sheetsChart": { object(SheetsChart) },
  // End of list of possible types for union field element_kind.
}

Il existe plusieurs types d'éléments de page, comme défini par le champ union element_kind dans la définition ci-dessus. Ces types d'éléments de page sont décrits dans le tableau suivant :

Type d'élément	Description
Groupe	Ensemble d'éléments de page traités comme une unité individuelle. Ils peuvent être déplacés, mis à l'échelle et pivotés ensemble.
Forme	Objet visuel simple, tel qu'un rectangle, une ellipse ou une zone de texte. Les formes peuvent contenir du texte. Elles sont donc les éléments de page les plus courants pour créer des diapositives.
Image	Graphique importé dans Slides.
Vidéo	Vidéo importée dans Slides
Ligne	Ligne, courbe ou connecteur visuel.
Tableau	Grille de contenu.
WordArt	Élément de texte visuel qui se comporte davantage comme une forme.
SheetsChart	Graphique importé dans Slides depuis Google Sheets.

Propriétés des pages et des éléments de page

L'API Slides vous permet de lire et de modifier l'apparence des pages et des éléments de page de votre présentation. Différents éléments de page sont compatibles avec différentes propriétés qui contrôlent la façon dont l'élément de page est affiché.

Chaque type d'élément de page possède un élément de propriétés et un message de mise à jour des propriétés correspondants. Par exemple :

Il existe un type d'élément de page Forme.
Son champ de propriété est shapeProperties.
La requête permettant de mettre à jour ces propriétés est UpdateShapePropertiesRequest.

Le même ensemble d'éléments/propriétés/requêtes de mise à jour existe pour chaque type d'élément de page : Image/imageProperties/UpdateImageProperties, etc.

Vous pouvez lire l'attribut "properties" chaque fois que vous le rencontrez lors de la lecture d'un élément. Pour modifier les valeurs qu'il contient, utilisez-le avec le type de requête correspondant comme charge utile pour la méthode batchUpdate, ce qui vous permet de modifier ces valeurs dans la présentation.

Types de propriétés

Certaines propriétés sont communes à plusieurs types d'objets dans l'API Slides :

Propriété	Description
Couleur	Dans l'API Slides, les couleurs peuvent être une valeur RVB ou une référence à une couleur de thème. Les couleurs du thème sont désignées par leur nom (par exemple, "DARK1") et peuvent être mappées à des valeurs RVB à l'aide du jeu de couleurs d'une page. Ce jeu de couleurs est généralement mis à jour lorsque vous modifiez le thème de la présentation dans l'éditeur Slides.
Remplissage	Le remplissage représente l'espace vide à l'intérieur d'un objet. Le remplissage le plus couramment accepté dans Slides est le remplissage uni, où l'intérieur d'un objet est rempli d'une seule couleur unie. Les remplissages peuvent également être utilisés pour les arrière-plans des pages.
Contour	Le contour représente l'ensemble des lignes qui entourent l'élément de la page. La couleur des lignes est contrôlée par un remplissage. Les appelants peuvent également ajuster la largeur et le style des tirets des contours.
Ombre	L'ombre représente un effet visuel destiné à imiter une ombre physique projetée par l'objet. Actuellement, les ombres dans l'API Slides sont en lecture seule.

Mettre à jour les propriétés

Pour mettre à jour une propriété, utilisez la requête Update...Properties appropriée dans un appel batchUpdate (par exemple, UpdateShapeProperties pour les formes). Ces requêtes acceptent un message de propriétés complet et peuvent utiliser des masques de champ pour déterminer les champs du message de propriétés à mettre à jour.

Un masque de champ * est traité comme un caractère générique et est une abréviation pour spécifier chaque champ d'un message. La syntaxe générique peut produire des résultats indésirables si l'API est mise à jour à l'avenir, car les champs en lecture seule et les champs nouvellement ajoutés peuvent entraîner des erreurs. Pour les applications de production, listez toujours les champs spécifiques mis à jour dans les masques de champ et évitez d'utiliser des caractères génériques *.

Héritage de la propriété

Une page ou un élément de page peuvent hériter des propriétés de leurs objets parents. Les propriétés d'un objet, y compris celles qu'il définit et celles qu'il hérite, déterminent son apparence visuelle finale.

Propriétés de la page : une page hérite de toutes les propriétés qu'elle ne définit pas, mais qui sont définies dans la mise en page ou le modèle sur lequel elle est basée.
Propriétés de forme : une forme peut être marquée comme espace réservé, ce qui vous permet de faire explicitement référence à une autre forme d'espace réservé (dans la mise en page ou le modèle parent de la page) à partir de laquelle hériter des propriétés.

Ces idées sont expliquées plus en détail dans les paragraphes suivants.

Héritage des propriétés de page

La structure des diapositives, des mises en page et des masques définit une hiérarchie d'héritage dans la présentation : les diapositives héritent des mises en page, et les mises en page héritent des masques. La mise en page et le masque parent d'une diapositive sont spécifiés dans le champ slideProperties de la diapositive.

Une page peut hériter des propriétés d'une page parente, telles que l'arrière-plan et le schéma de couleurs. Pour hériter d'une propriété, la page enfant ne définit simplement pas de valeur pour cette propriété dans son message PageProperties. En ne "remplaçant" pas la valeur définie par le parent, la page accepte la valeur héritée.

Le schéma suivant montre une diapositive qui hérite des propriétés d'une mise en page, qui elle-même hérite d'un masque :

héritage des propriétés des diapositives

Les propriétés utilisées pour afficher une diapositive sont une combinaison de celles qu'elle définit et de celles qu'elle hérite. Dans cet exemple, les valeurs résolues utilisées pour afficher la diapositive 1 sont les suivantes :

La propriété A est "Rouge".
PropertyB est "Orange".

Héritage des propriétés de forme

Les formes peuvent hériter des propriétés d'autres formes, telles que la couleur de remplissage, le contour ou l'ombre. Une forme est un espace réservé si son champ Shape.placeholder est défini. Le champ Shape.placeholder.parentObjectId de l'espace réservé enfant identifie son espace réservé parent. Lorsque vous créez une diapositive à partir d'une mise en page, tous les espaces réservés de cette mise en page apparaissent sous forme de formes enfants dans la nouvelle diapositive. De même, les espaces réservés sur les pages maîtres peuvent servir de parents aux espaces réservés des mises en page.

Avec cette hiérarchie d'héritage définie, la page enfant hérite d'une propriété en ne définissant pas cette valeur dans son message ShapeProperties. En ne remplaçant pas la valeur définie par le parent, la forme enfant accepte la valeur héritée.

Le schéma suivant illustre l'héritage des propriétés entre trois espaces réservés contenus dans une diapositive, une mise en page et un masque :

Les propriétés utilisées pour afficher une forme d'espace réservé sont une combinaison de celles qu'elle définit et de celles qu'elle hérite. Dans cet exemple, les valeurs résolues pour ces formes sont les suivantes :

Espace réservé 1 : propertyA est affiché sous la forme "Jaune", propertyB sous la forme "Vert".
Espace réservé 2 : propertyA est affiché comme "Jaune", propertyB comme "Violet".
Espace réservé 3 : propertyA est affiché comme "Jaune", propertyB comme "Violet".

Les formes sont le seul type d'élément de page pouvant avoir des parents. Les autres types, tels que les images, les tableaux et les graphiques, ne peuvent pas être des espaces réservés ni avoir de parents.

Masquer des propriétés à l'aide de PropertyState

L'énumération PropertyState contrôle si la propriété d'une forme est réellement utilisée pour le rendu ou si la valeur n'est utilisée que pour l'héritage par les formes enfants. Une propriété dont l'état est NOT_RENDERED ne sera pas utilisée lors du rendu de la forme sur sa page. Toutefois, les enfants dont l'état de propriété correspondant est RENDERED peuvent toujours hériter de cette propriété.

Le schéma suivant illustre l'héritage des propriétés entre trois espaces réservés qui manipulent le champ PropertyState :

l'état et l'héritage des propriétés.

Le rendu des propriétés de forme peut être affecté par le champ "PropertyState". Dans cet exemple, les valeurs résolues pour ces formes sont les suivantes :

Placeholder1 : la propriétéA est affichée comme "Rouge".
Placeholder2: propertyA is not rendered. Si la propriété de contour était définie, Placeholder2 n'aurait pas de contour.
Placeholder3 : propertyA n'est pas affiché.

Il existe une autre valeur possible pour l'énumération PropertyState : l'état de propriété INHERIT signifie que l'état de propriété lui-même est hérité et que la valeur du parent doit être utilisée. Les formes sans parent ne peuvent pas avoir un état de propriété INHERIT.