Um die Slides API effektiv nutzen zu können, müssen Sie die Architektur von Präsentationen und deren Komponenten sowie die Interaktionen zwischen diesen Komponenten verstehen. Auf dieser Seite finden Sie eine detaillierte Übersicht über diese Themen:
- Konzeptmodell der Präsentationskomponenten
- Darstellung dieser Komponenten durch die API
- Stileigenschaften der Komponenten
Diese und die anderen Konzeptübersichten erleichtern das Verständnis und die Verwendung der Anleitungen, der Referenzdokumentation und der Rezeptbeispiele.
Präsentationen, Seiten und Seitenelemente
Das äußerste Containerelement in Google Präsentationen ist eine Präsentation. Dies ist die Einheit, die in Google Drive gespeichert, für andere Nutzer freigegeben usw. werden kann.
Jede Präsentation besteht aus verschiedenen Arten von Seiten. Ein Seitentyp ist eine Folie. Das sind die Seiten, die Nutzer sehen und zwischen denen die Präsentation wechseln, wenn die Präsentation auf einem Bildschirm gerendert wird.
Jede Seite enthält eine Reihe von Seitenelementen, die zusammen den Inhalt der Seite bilden, wie im folgenden Diagramm dargestellt:
Neben den Folien gibt es auch andere Seitentypen, mit denen Sie Designs auf viele verschiedene Folien anwenden können, um für ein einheitliches Erscheinungsbild zu sorgen. Die anderen Seitentypen sind Master und Layouts. Ihre Attribute bestimmen, wie Folien gerendert werden, wie im folgenden Diagramm dargestellt:
Master – Die Master-Seite dient zwei Zwecken. Platzhalter auf dem Master enthalten die Standardwerte für Textstile, die in Ihrer Präsentation verwendet werden. Der Hintergrund und alle anderen Formen auf der Masterfolie bilden den Standardhintergrund für alle Folien auf Grundlage dieses Masters. Wenn Sie ein Firmenlogo haben, das auf jeder Folie zu sehen sein soll,
Layouts: Layoutvorlagen bestimmen, wie Inhalte auf den einzelnen Folientypen angeordnet werden. Wenn Sie beispielsweise möchten, dass alle Titelfolien ein bestimmtes Format haben, können Sie die Vorlage für das Titellayout bearbeiten.
Es gibt zwei weitere Arten von Seiten – Notizenseiten und Notizenmaster –, die hauptsächlich für die Arbeit mit Sprechernotizen relevant sind.
API-Darstellungstypen und -struktur
In diesem Abschnitt wird beschrieben, wie das oben beschriebene konzeptionelle Modell von Google Präsentationen in der Slides API dargestellt wird.
Das folgende Diagramm veranschaulicht die Beziehung zwischen Präsentationen, Seiten und Seitenelementen als Typen in der Slides API:
In den folgenden Abschnitten wird gezeigt, wie diese Typen in JSON dargestellt werden.
Präsentationen
Eine Präsentation hat eine Reihe von Attributen sowie die darin enthaltenen Seiten:
{
"presentationId": string,
"pageSize": { object(Size) },
"slides": [ { object(Page) } ],
"title": string,
"masters": [ { object(Page) } ],
"layouts": [ { object(Page) } ],
"notesMaster": object(Page),
"locale": string,
}
Seiten
Eine Seite besteht aus einer Reihe von Eigenschaften und den enthaltenen Seitenelementen:
{
"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.
}
Seitenelemente
Seitenelemente sind die visuellen Komponenten, die auf Seiten platziert werden. Ein Seitenelement in der API enthält eine Reihe von Eigenschaften, darunter ein Feld, das je nach Art des Seitenelements variiert:
{
"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.
}
Es gibt mehrere Arten von Seitenelementen, die durch das Union-Feld element_kind in der obigen Definition definiert werden. Diese Arten von Seitenelementen werden in der folgenden Tabelle beschrieben:
| Elementart | Beschreibung |
|---|---|
| Gruppe | Ein Satz von Seitenelementen, die als einzelne Einheit behandelt werden. Sie können zusammen verschoben, skaliert und gedreht werden. |
| Form | Ein einfaches visuelles Objekt wie Rechtecke, Ellipsen und Textfelder. Formen können Text enthalten. Daher sind sie die am häufigsten verwendeten Seitenelemente zum Erstellen von Folien. |
| Bild | Eine in Google Präsentationen importierte Grafik |
| Video | Ein Video, das in Google Präsentationen importiert wurde |
| Linie | Eine visuelle Linie, Kurve oder Verbindung. |
| Tabelle | Ein Inhaltsraster. |
| WordArt | Ein visuelles Textelement, das sich mehr wie eine Form verhält. |
| SheetsChart | Ein aus Google Tabellen in Google Präsentationen importiertes Diagramm. |
Seiten- und Seitenelementeigenschaften
Mit der Slides API können Sie die Darstellung von Seiten und Seitenelementen in Ihrer Präsentation lesen und aktualisieren. Die verschiedenen Seitenelemente unterstützen unterschiedliche Eigenschaften, mit denen festgelegt wird, wie das Seitenelement gerendert wird.
Jede Seitenelementart hat ein entsprechendes Properties-Element und eine Property-Aktualisierungsnachricht. Beispiel:
- Mit dem Seitenelementtyp Shape
- Das zugehörige Eigenschaftsfeld ist shapeProperties.
- Die Anfrage zum Aktualisieren dieser Eigenschaften lautet UpdateShapePropertiesRequest.
Für jeden Seitenelementtyp gibt es die gleiche Gruppe von Element-/Eigenschaften-/Aktualisierungsanfragen: Image/imageProperties/UpdateImageProperties usw.
Sie können das Attributattribut überall dort lesen, wo es beim Lesen eines Elements angezeigt wird. Wenn Sie die Werte im Element ändern möchten, verwenden Sie es mit dem passenden Anfragetyp als Nutzlast für die Methode batchUpdate. So können Sie diese Werte in der Präsentation ändern.
Arten von Unterkünften
Es gibt einige Eigenschaften, die bei verschiedenen Objekttypen in der Slides API gemeinsam sind:
| Property | Beschreibung |
|---|---|
| Farbe | Farben in der Slides API können entweder ein RGB-Wert oder ein Verweis auf eine Designfarbe sein. Designfarben werden anhand des Namens referenziert, z. B. „DUNK1“, und können RGB-Werten mithilfe des Farbschemas einer Seite zugeordnet werden. Dieses Farbschema wird in der Regel aktualisiert, wenn das Design der Präsentation im Präsentationen-Editor geändert wird. |
| Füllung | Die Füllung stellt die Wiedergabe von leerem Raum innerhalb eines Objekts dar. Die am häufigsten unterstützte Füllung in Google Präsentationen ist die vollständige Füllung, bei der das Innere eines Objekts mit einer einzigen deckenden Farbe ausgefüllt wird. Füllungen können auch für den Hintergrund von Seiten verwendet werden. |
| Umriss | Der Umriss stellt die Gruppe von Linien dar, die das Seitenelement umgeben. Die Linienfarbe wird mit einer Füllung festgelegt. Anrufer können außerdem die Breite und den Strichstil der Konturen anpassen. |
| Shadow | Der Schatten steht für einen visuellen Effekt, der einen vom Objekt geworfenen physischen Schatten nachahmen soll. Derzeit sind Schatten in der Slides API schreibgeschützt. |
Attribute aktualisieren
Verwenden Sie zum Aktualisieren eines Attributs die entsprechende Update...Properties-Anfrage in einem batchUpdate-Aufruf, z. B. UpdateShapeProperties für Formen. Diese Anfragen akzeptieren eine vollständige Attributnachricht und können Feldmasken verwenden, um zu bestimmen, welche Felder in der Attributnachricht aktualisiert werden sollen.
Übernahme aus Properties
Eine Seite oder ein Seitenelement kann Eigenschaften von ihren übergeordneten Objekten übernehmen. Die endgültige visuelle Darstellung eines Objekts hängt von seinen Eigenschaften ab. Dazu gehören auch diejenigen, die es definiert und die es übernommen hat.
- Seiteneigenschaften: Eine Seite übernimmt alle Eigenschaften, die sie nicht definiert, die aber in dem Layout oder Master definiert sind, auf dem sie basiert.
- Formeigenschaften: Eine Form kann als Platzhalter markiert werden, damit Sie explizit auf eine andere Platzhalterform (im übergeordneten Layout oder im übergeordneten Master der Seite) verweisen können, von der die Eigenschaften übernommen werden sollen.
Diese Konzepte werden in den folgenden Abschnitten näher erläutert.
Übernahme von Seiteneigenschaften
Die Struktur der Folien, Layouts und Master definiert eine Hierarchie innerhalb der Präsentation: Folien übernehmen von Layouts, Layouts von Mastern. Im Feld slideProperties der Folie werden das übergeordnete Layout und der Master einer Folie angegeben.
Eine Seite kann Eigenschaften wie den Hintergrund und das Farbschema von einer übergeordneten Seite übernehmen. Um ein Attribut zu übernehmen, legt die untergeordnete Seite in der Nachricht PageProperties einfach keinen Wert für dieses Attribut fest. Wenn der vom übergeordneten Element definierte Wert nicht überschrieben wird, akzeptiert die Seite den übernommenen Wert.
Das folgende Diagramm zeigt eine Folie, die Eigenschaften von einem Layout übernimmt, das wiederum von einem Master übernommen wird:
Die Eigenschaften, die zum Rendern einer Folie verwendet werden, sind eine Kombination aus den von der Folie definierten und den übernommenen Eigenschaften. In diesem Beispiel werden zum Rendern von Folie 1 die folgenden aufgelösten Werte verwendet:
- PropertyA ist „Rot“.
- PropertyB ist „Orange“.
Übernahme von Formeigenschaften
Formen können Eigenschaften wie Füllung, Umriss oder Schatten von anderen Formen übernehmen. Eine Form ist ein Platzhalter, wenn das entsprechende Feld Shape.placeholder ausgefüllt ist. Das Feld Shape.placeholder.parentObjectId des untergeordneten Platzhalters gibt den übergeordneten Platzhalter an. Wenn Sie eine neue Folie basierend auf einem Layout erstellen, werden alle Platzhalter in diesem Layout als untergeordnete Formen auf der neuen Folie angezeigt.
Ebenso können Platzhalter auf Masterseiten den Platzhaltern des Layouts übergeordnet sein.
Wenn diese Übernahmehierarchie definiert ist, übernimmt die untergeordnete Seite ein Attribut, indem dieser Wert in der Nachricht ShapeProperties nicht festgelegt wird. Wenn der vom übergeordneten Element definierte Wert nicht überschrieben wird, akzeptiert die untergeordnete Form den übernommenen Wert.
Das folgende Diagramm zeigt die Übernahme von Eigenschaften zwischen drei Platzhaltern, die in einer Folie, einem Layout und einem Master enthalten sind:
Die zum Rendern einer Platzhalterform verwendeten Eigenschaften sind eine Kombination aus definierten und übernommenen Eigenschaften. In diesem Beispiel sind die aufgelösten Werte für diese Formen so:
- Platzhalter 1: propertyA wird als „Gelb“ dargestellt, PropertyB als „grün“.
- Platzhalter 2: propertyA wird als „Gelb“ gerendert, PropertyB als „Lila“.
- Platzhalter 3: propertyA wird als „Gelb“ gerendert, PropertyB als „Lila“.
Formen sind der einzige Typ von Seitenelementen, die übergeordnete Elemente haben können. Andere Typen wie Bilder, Tabellen und Diagramme können keine Platzhalter sein und keine übergeordneten Elemente haben.
Properties mithilfe von PropertyState ausblenden
Mit der Aufzählung PropertyState wird gesteuert, ob die Eigenschaft einer Form tatsächlich zum Rendern verwendet wird oder ob der Wert nur für die Übernahme von untergeordneten Formen verwendet wird. Ein Attribut mit dem Attributstatus NOT_RENDERED wird beim Rendern der Form auf der entsprechenden Seite nicht verwendet. Untergeordnete Elemente mit dem Attributstatus RENDERED können diese Property jedoch weiterhin übernehmen.
Das folgende Diagramm zeigt die Übernahme von Properties zwischen drei Platzhaltern, die das Feld „PropertyState“ manipulieren:
Die Darstellung der Formeigenschaften kann vom Feld „PropertyState“ beeinflusst werden. In diesem Beispiel lauten die aufgelösten Werte für diese Formen wie folgt:
- Platzhalter 1: propertyA wird als „Red“ gerendert.
- Platzhalter 2: propertyA wird nicht gerendert. Wenn dies die Outline-Property wäre, würde Platzhalter2 keine Outline-Eigenschaft.
- Platzhalter 3: propertyA wird nicht gerendert.
Bei der Aufzählung PropertyState gibt es noch einen weiteren Wert: Der Attributstatus INHERIT bedeutet, dass der Attributstatus selbst übernommen wird und der Wert des übergeordneten Elements verwendet werden sollte. Formen ohne übergeordnete Elemente können nicht den Attributstatus INHERIT haben.