Pour utiliser l'API Slides efficacement, 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 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 utiliser les guides d'utilisation, 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 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. Le premier type de page est une diapositive, c'est-à-dire les pages que les utilisateurs voient et entre lesquelles ils naviguent lorsque la présentation est affichée sur un écran.
Chaque page contient un certain nombre d'éléments de page, qui constituent ensemble le contenu de la page, comme illustré dans le schéma suivant :
Outre les diapositives, il existe d'autres types de pages qui vous permettent d'appliquer une mise en page à de nombreuses diapositives différentes, créant ainsi 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 illustré dans le schéma suivant :
Pages maîtres : la page maître a deux objectifs. Les espaces réservés du masque contiennent les valeurs par défaut des styles de texte utilisés dans l'ensemble de votre présentation. L'arrière-plan et toutes les autres formes de la diapositive de 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 apparaisse 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. Par exemple, si vous souhaitez que toutes vos diapositives de titre aient un certain aspect, vous pouvez modifier le modèle de mise en page du titre.
Il existe deux autres types de pages : les pages de commentaires et les masques de commentaires, qui sont principalement utiles pour travailler avec les commentaires du présentateur.
Types et structure de représentation des 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 schéma 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 en JSON.
Présentations
Une présentation inclut un certain nombre de propriétés et contient les pages qu'elle comporte :
{
"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 de l'API contient un certain nombre de propriétés, y compris un champ qui varie selon le 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 :
| Genre d'élément | Description |
|---|---|
| Groupe | Ensemble d'éléments de page traités comme une unité individuelle. Ils peuvent être déplacés, redimensionnés et pivotés ensemble. |
| Forme | Un objet visuel simple, tel que des rectangles, des ellipses et des zones de texte. Les formes peuvent contenir du texte. Ce sont donc les éléments de page les plus courants pour créer des diapositives. |
| Image | Un graphique importé dans Slides. |
| Vidéo | Une vidéo importée dans Slides. |
| Ligne | Ligne, courbe ou connecteur visuel. |
| Table | Une grille de contenu. |
| WordArt | Élément de texte visuel qui se comporte davantage comme une forme. |
| SheetsChart | Un graphique importé dans Slides depuis Google Sheets. |
Propriétés de la page 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 l'affichage de l'élément de page.
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 (Forme).
- Son champ de propriété est shapeProperties.
- La requête de mise à jour de 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 | Les couleurs de l'API Slides 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 le rendu de l'espace vide à l'intérieur d'un objet. Le type de 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 page. La couleur des lignes est contrôlée par un remplissage. Les appelants peuvent également ajuster la largeur et le style de tiret des contours. |
| Ombre | L'ombre représente un effet visuel destiné à imiter l'ombre physique projetée par l'objet. Actuellement, les ombres dans l'API Slides sont en lecture seule. |
Mise à jour des 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.
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 forme : une forme peut être marquée comme un espace réservé, ce qui vous permet de référencer explicitement une autre forme d'espace réservé (sur la mise en page parente ou le masque de la page) dont vous souhaitez hériter les 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 masques définit une hiérarchie d'héritage au sein de la présentation : les diapositives héritent des mises en page, et les mises en page héritent des masques. La mise en page parent et le masque 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 jeu de couleurs, d'une page parente. Pour hériter d'une propriété, la page enfant ne définit tout 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 :
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 :
- PropertyA est "Red".
- PropertyB est "Orange".
Héritage des propriétés de forme
Les formes peuvent hériter de propriétés d'autres formes, telles que le 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 basée sur une mise en page, tous les espaces réservés de cette mise en page apparaissent en tant que formes enfants dans la nouvelle diapositive.
De même, les espaces réservés des pages maîtres peuvent agir en tant que parents des espaces réservés des mises en page.
Une fois 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 diagramme suivant montre 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 :
- Placeholder1 : propertyA est affiché sous la forme "Jaune", propertyB sous la forme "Vert".
- Placeholder2 : propertyA est affiché sous la forme "Yellow" et propertyB sous la forme "Purple".
- Placeholder3 : propertyA est affiché sous la forme "Jaune", propertyB sous la forme "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 détermine 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 ne sera 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 montre l'héritage des propriétés entre trois espaces réservés qui manipulent le champ PropertyState :
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 : propertyA est affiché sous la forme "Red".
- Placeholder2 : propertyA n'est pas affiché. S'il s'agissait de la propriété "outline", 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 l'état de propriété INHERIT.