Pour utiliser efficacement l'API Slides, vous devez comprendre l'architecture des présentations et leurs composants, ainsi que les interactions entre ces composants. Cette page offre un aperçu détaillé 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 d'autres présentations de concepts facilite la compréhension et l'utilisation des guides d'utilisation, de la documentation de référence et des 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. Il s'agit des pages que les utilisateurs voient et qui s'affichent lorsque la présentation s'affiche à l'écran.
Chaque page contient un certain nombre d'éléments qui constituent le contenu de la page, comme illustré dans le schéma suivant:
Outre les diapositives, vous pouvez appliquer d'autres types de pages à différentes diapositives, ce qui crée une apparence cohérente. Ces autres types de pages sont les pages maîtres et les mises en page, et leurs propriétés déterminent le mode d'affichage des diapositives, comme illustré dans le schéma suivant:
Maîtres : la page maître a deux objectifs. Les espaces réservés sur le maître contiennent les valeurs par défaut des styles de texte utilisés tout au long de 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 afficher le logo d'une entreprise 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 manière dont le contenu est organisé sur chaque type de diapositive. Par exemple, si vous souhaitez que toutes vos diapositives de titre s'affichent d'une certaine façon, 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 masques de notes. Ils sont principalement utiles pour travailler avec des notes d'intervenant.
Types et structure de représentations d'API
Cette section décrit la représentation du modèle conceptuel Google Slides, comme décrit ci-dessus, 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 au format JSON.
Présentations
Une présentation inclut un certain nombre de propriétés et contient les pages qu'elle contient:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Pages
Une page comprend un ensemble de propriétés et contient les éléments de page 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, dont 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:
| Type d'élément | Description |
|---|---|
| Groupe | Ensemble d'éléments de page traités comme une seule unité. Vous pouvez les déplacer, les redimensionner et les faire pivoter ensemble. |
| Forme | Objet visuel simple tel que des rectangles, des points de suspension et des zones de texte. Les formes peuvent contenir du texte. Elles constituent 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, une courbe ou un connecteur visuel |
| Table | Grille de contenu. |
| WordArt | Élément de texte visuel qui se comporte plus comme une forme. |
| Graphique Sheets | Un graphique importé dans Slides à partir de Google Sheets |
Page et propriétés de l'élément 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. Différents éléments de page acceptent différentes propriétés qui contrôlent l'affichage 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 Forme
- Son champ de propriété est shapeProperties
- La demande de mise à jour de ces propriétés est UpdateShapePropertiesRequest.
Il existe le même ensemble d'éléments/propriétés/demande de mise à jour 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 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 mises en correspondance avec les 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 d'un espace vide dans un objet. Le remplissage le plus souvent accepté 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 l'arrière-plan des pages. |
| Contour | Le contour représente l'ensemble de 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 visant à 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 tracés. Ces requêtes acceptent un message de propriétés complètes 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 peuvent 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 maître sur lequel elle est basée.
- Propriétés de la 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 la page maître) dont elle héritera.
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 parente et la masque d'une diapositive sont spécifiées 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 jeu de couleurs. 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 héritant des propriétés d'une mise en page, qui hérite d'une 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:
- La propriété A est "Rouge".
- La propriété B est "Orange".
Héritage des propriétés de forme
Les formes peuvent hériter de propriétés d'autres formes, comme 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.
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 montre l'héritage des propriétés entre trois espaces réservés contenus dans une diapositive, une mise en page et un maître:
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: la propriété A s'affiche en jaune et la propriété B en vert.
- Placeholder2: la propriété A s'affiche en jaune et la propriété B en violet.
- Placeholder3: la propriété A s'affiche en jaune et la propriété B en 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.
"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 est uniquement utilisée pour l'héritage par les formes enfants. Une propriété avec l'état NOT_RENDERED n'est 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" :
Le champ "PropertyState" peut avoir une incidence sur l'affichage des propriétés de la forme. Dans cet exemple, les valeurs résolues pour ces formes sont les suivantes:
- Placeholder1: la propriété A s'affiche en rouge.
- Placeholder2: la propriété A n'est pas affichée. S'il s'agissait de la propriété de contour, Placeholder2.
- Placeholder3: la propriété A n'est pas affichée.
Il existe une autre valeur possible de 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 parents ne peuvent pas avoir l'état de propriété INHERIT.