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 de ces sujets :
- Modèle conceptuel des composants de la présentation
- Représentation de ces composants par l'API
- Propriétés de style des composants
La lecture de cette présentation et des autres présentations conceptuelles vous permettra de comprendre et d’utiliser plus facilement les guides pratiques, la documentation de référence et les exemples de code.
Présentations, pages et éléments de page
L'élément conteneur le plus externe de 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 une diapositive, qui correspond aux pages que les utilisateurs voient et entre lesquelles ils passent lorsque la présentation est affichée à l'écran.
Chaque page contient un certain nombre d'éléments de page, qui constituent ensemble le contenu de la page, comme illustré dans le diagramme suivant :
Outre les diapositives, il existe d'autres types de pages qui vous permettent d'appliquer une conception à de nombreuses diapositives différentes, créant ainsi une apparence cohérente. Ces autres types de pages sont des masques et des mises en page, et leurs propriétés déterminent la façon dont les diapositives sont affichées, comme illustré dans le diagramme suivant :
Modèles : la page de modèle a deux objectifs. Les espaces réservés du modèle 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 de la diapositive de modèle constituent l'arrière-plan par défaut de toutes les diapositives basées sur ce modèle. Si vous souhaitez que le logo de votre entreprise apparaisse sur chaque diapositive de votre présentation, placez-le sur le modèle.
Mises en page : les modèles de mise en page déterminent la disposition du contenu sur chaque type de diapositive. Par exemple, si vous souhaitez que toutes vos diapositives de titre aient une apparence particulière, vous pouvez modifier le modèle de mise en page du titre.
Il existe deux autres types de pages (les pages de notes et les modèles de notes) qui sont principalement 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 de 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 :
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 s'y trouvent :
{
"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 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, tels que définis par le champ d'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 que des rectangles, des ellipses et des zones 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 | Image importée dans Slides. |
| Vidéo | Vidéo importée dans Slides. |
| Ligne | Ligne, courbe ou connecteur visuel. |
| Table | 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 correspondant et un message de mise à jour des propriétés, par exemple :
- Il existe un type d'élément de page Shape
- Son champ de propriété est shapeProperties
- La requête permettant de mettre à jour ces propriétés est UpdateShapePropertiesRequest
Le même ensemble de requête élément/propriétés/mise à jour existe pour chaque type d'élément de page : Image/imageProperties/UpdateImageProperties, et ainsi de suite.
Vous pouvez lire l'attribut properties partout où 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 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 | Les couleurs de l'API Slides peuvent être une valeur RVB ou une référence à une couleur de thème. Les couleurs de thème sont référencé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'affichage de l'espace vide à l'intérieur d'un objet. Le remplissage le plus couramment pris en charge dans Slides est un 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 page. La couleur des lignes est contrôlée par un remplissage. Les appelants peuvent également ajuster la largeur et le style de tirets des contours. |
| Ombre | L'ombre représente un effet visuel destiné à imiter une ombre physique projetée par l'objet. Actuellement, les ombres de l'API Slides sont en lecture seule. |
Mise à jour des propriétés
Pour mettre à jour une propriété, utilisez la requête appropriée
Update...Properties 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.
Héritage de la propriété
Une page ou un élément de page peut hériter des propriétés de ses objets parents. Les propriétés d'un objet, y compris celles qu'il définit et celles dont 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 la forme : une forme peut être marquée comme espace réservé, ce qui vous permet de référencer explicitement une autre forme d'espace réservé (dans la mise en page parent ou le masque 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 la page
La structure des diapositives, des mises en page et des modèles 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 modèles. La mise en page et le modèle parents d'une diapositive sont spécifiés dans le champ slideProperties de la diapositive.
Une page peut hériter de propriétés, telles que l'arrière-plan et le schéma de couleurs, d'une page parente. Pour hériter d'une propriété, la page enfant ne définit simplement pas de valeur pour cette propriété dans son PageProperties 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 héritant des propriétés d'une mise en page, qui hérite d'un modèle :
Les propriétés utilisées pour afficher une diapositive sont une combinaison de celles qu'elle définit et de celles dont 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".
- La propriété B est "Orange".
Héritage des propriétés de la forme
Les formes peuvent hériter de propriétés, telles que le remplissage, le contour ou l'ombre, d'autres formes. Une forme est un espace réservé si son
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 basée sur 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 des pages de modèle 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 ShapeProperties ShapeProperties. En ne remplaçant pas la valeur définie par le parent, la forme enfant accepte la valeur héritée.
Le diagramme 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 dont elle hérite. Dans cet exemple, les valeurs résolues pour ces formes sont les suivantes :
- Espace réservé 1 : la propriété A est affichée en "Jaune", la propriété B en "Vert".
- Espace réservé 2 : la propriété A est affichée en "Jaune", la propriété B en "Violet".
- Espace réservé 3 : la propriété A est affichée en "Jaune", la propriété B en "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 et ne peuvent pas avoir de parents.
"Masquer" les propriétés à l'aide de PropertyState
L'
PropertyState
PropertyState contrôle si la propriété d'une forme est réellement utilisée pour l'affichage,
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 n'est pas utilisée lors de l'affichage 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'affichage des propriétés de la forme peut être affecté par le champ PropertyState. Dans cet exemple, les valeurs résolues pour ces formes sont les suivantes :
- Espace réservé 1 : la propriété A est affichée en "Rouge".
- Espace réservé 2 : la propriété A n'est pas affichée. S'il s'agissait de la propriété de contour, l'espace réservé 2 n'aurait pas de contour.
- Espace réservé 3 : la propriété A n'est pas affichée.
Il existe une autre valeur possible de l'énumération
PropertyState
: l'état de propriété INHERIT signifie que l'état de la 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.