Pour utiliser l'API Slides efficacement, vous devez comprendre l'architecture des présentations et 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-t-elle ces composants ?
- Propriétés de style des composants
Si vous lisez cette présentation et d'autres de présentation des concepts, il sera plus facile de comprendre et d'utiliser les guides d'utilisation, la documentation de référence et les exemples de recettes.
Présentations, pages et éléments de page
L'élément de conteneur le plus externe dans Google Slides est une présentation. Cette unité 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. Il s'agit des pages que les utilisateurs voient et naviguent lorsque la présentation s'affiche à l'écran.
Chaque page contient un certain nombre d'éléments de page, qui constituent 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 la conception à de nombreuses diapositives différentes, créant ainsi une apparence cohérente. Ces autres types de pages sont les maîtres 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:
Maître : la page maître a une double utilité. Les espaces réservés sur le maître 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 maître constituent l'arrière-plan par défaut de toutes les diapositives basées sur ce masque. Si vous souhaitez faire apparaître le logo d'une entreprise sur chaque diapositive de votre présentation, placez-le sur le maître.
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, par exemple, vous pouvez modifier le modèle de mise en page de titre.
Il existe deux autres types de pages : les pages de notes et les maîtres de notes, principalement pertinents pour travailler avec des notes de l'orateur.
Structure et types 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 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 expliquent comment ces types sont représentés au format JSON.
Présentations
Une présentation comprend de nombreuses 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 qu'elle contient:
{
"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 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, 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, ce sont donc les éléments de page les plus courants pour créer des diapositives. |
| Image | Graphique importé dans Slides. |
| Vidéo | Une vidéo importée dans Slides. |
| Line | Une ligne visuelle, une courbe ou un connecteur. |
| Table | Grille de contenu. |
| WordArt | Élément de texte visuel qui se comporte davantage comme une forme. |
| SheetsChart | Graphique importé dans Slides à partir de Google Sheets. |
Propriétés de la page et des éléments de page
L'API Slides vous permet de lire et de mettre à jour l'apparence des pages et des éléments de page dans votre présentation. Les différents éléments de page prennent en charge différentes propriétés qui contrôlent le rendu de l'élément de page.
Chaque genre 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 de requêtes d'élément/de propriétés/de mise à jour existe pour chaque type d'élément de page: Image/imageProperties/UpdateImageProperties, etc.
Vous pouvez lire l'attribut de propriétés 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 en tant que 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 dans l'API Slides peuvent être une valeur RVB ou une référence à une couleur de thème. Les couleurs du thème sont appelées par leur nom (par exemple, "DARK1") et peuvent être mappées avec 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. |
| Fill | Le remplissage représente le rendu d'un espace vide à l'intérieur d'un objet. Le remplissage le plus couramment utilisé dans Slides est un remplissage plein, 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. |
| Outline | 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 de tirets des contours. |
| Shadow | L'ombre représente un effet visuel destiné à imiter une ombre physique projetée par l'objet. Actuellement, les ombres dans l'API Slides ne sont accessibles qu'en lecture seule. |
Mettre à 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 Shapes). 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 des propriétés qu'elle ne définit pas, mais qui sont définies dans la mise en page ou le masque sur lesquels elle est basée.
- Propriétés de la forme : une forme peut être marquée en tant qu'espace réservé, ce qui vous permet de référencer explicitement une autre forme d'espace réservé (sur la mise en page ou le masque parent de la page) dont elle hérite 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 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 maîtres. La mise en page parente 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 illustre une diapositive héritant des propriétés d'une mise en page, laquelle hérite d'un masque:
Les propriétés utilisées pour afficher une diapositive sont une combinaison des propriétés 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 des 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 sur les pages maîtres peuvent agir en tant que parents des espaces réservés des mises en page.
Lorsque cette hiérarchie d'héritage est définie, la page enfant hérite d'une propriété en ne la définissant pas 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é combinent celles qu'elle définit et celles dont elle hérite. Dans cet exemple, les valeurs résolues de ces formes sont les suivantes:
- Placeholder1: le rendu de la propriété A est "jaune" et de la propriété B "vert".
- Placeholder2: le rendu de la propriété A est "jaune" et de la propriété B "violet".
- Placeholder3: le rendu de la propriété A est "jaune" et de la propriété B "violet".
Les formes sont le seul type d'élément de page qui peut 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.
Masquage 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 le rendu ou si la valeur est uniquement utilisée pour l'héritage par les formes enfants. Une propriété avec l'état de propriété 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 illustre 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 la forme peut être affecté par le champ "PropertyState". Dans cet exemple, les valeurs résolues de ces formes sont les suivantes:
- Placeholder1: le rendu de la propriété A est "rouge".
- Placeholder2: 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.
- Placeholder3: la propriété A n'est pas affichée.
Il existe une autre valeur possible dans l'énumération PropertyState: l'état de la 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é défini sur INHERIT.