Damit Sie die Slides API effektiv nutzen können, müssen Sie die Architektur von Präsentationen und ihren Komponenten sowie die Interaktionen zwischen diesen Komponenten verstehen. Auf dieser Seite finden Sie einen detaillierten Überblick über die folgenden Themen:
- Konzeptmodell der Präsentationskomponenten
- So werden diese Komponenten in der API dargestellt
- Stileigenschaften der Komponenten
Wenn Sie sich diese und die anderen Konzeptübersichten durchlesen, fällt es Ihnen leichter, die Anleitungen, die Referenzdokumentation und die Beispielrezepte zu verstehen und zu verwenden.
Präsentationen, Seiten und Seitenelemente
Das äußerste Containerelement in Google Präsentationen ist eine Präsentation. Das ist die Einheit, die in Google Drive gespeichert und für andere Nutzer freigegeben werden kann.
Jede Präsentation enthält verschiedene Arten von Folien. Eine Art von Seite ist eine Folie. Das sind die Seiten, die Nutzer sehen und zwischen denen sie 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 Folien gibt es auch andere Seitentypen, auf die Sie ein Design anwenden können, um ein einheitliches Erscheinungsbild zu erzielen. Die anderen Seitentypen sind Masters (Master) und Layouts (Layouts). Ihre Eigenschaften bestimmen, wie Folien gerendert werden. Das folgende Diagramm veranschaulicht dies:
Masterseiten: Die Masterseite dient zwei Zwecken. Platzhalter auf dem Master enthalten die Standardwerte für Textstile, die in der gesamten Präsentation verwendet werden. Der Hintergrund und alle anderen Formen auf der Masterfolie bilden den Standardhintergrund für alle Folien, die auf dieser Masterfolie basieren. Wenn Sie ein Unternehmenslogo haben, das auf jeder Folie Ihrer Präsentation angezeigt werden soll, fügen Sie es in die Masterfolie ein.
Layouts: Mit Layoutvorlagen wird festgelegt, wie Inhalte auf den einzelnen Folientypen angeordnet werden. Wenn alle Titelfolien ein bestimmtes Aussehen haben sollen, können Sie beispielsweise die Vorlage für das Titellayout bearbeiten.
Es gibt zwei weitere Arten von Seiten: Notizseiten und Notiz-Master. Diese sind hauptsächlich für die Arbeit mit Referentennnotizen relevant.
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 zeigt 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 enthält eine Reihe von Eigenschaften und 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,
}
iWork Pages
Eine Seite enthält eine Reihe von Attributen und die darin enthaltenen Seitenelemente:
{
"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 Attributen, 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 verschiedene 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 | Eine Gruppe von Seitenelementen, die als einzelne Einheit behandelt werden. Sie können gemeinsam verschoben, skaliert und gedreht werden. |
| Form | Ein einfaches visuelles Objekt wie Rechtecke, Ellipsen und Textfelder. Formen können Text enthalten und sind daher die gängigsten Seitenelemente zum Erstellen von Folien. |
| Bild | Eine in Google-Präsentationen importierte Grafik. |
| Video | Ein in Google Präsentationen importiertes Video |
| Linie | Eine visuelle Linie, Kurve oder Verbindung. |
| Tabelle | Ein Raster mit Inhalten. |
| WordArt | Ein visuelles Textelement, das sich eher wie eine Form verhält. |
| SheetsChart | Ein Diagramm, das aus Google Sheets in Google-Präsentationen importiert wurde. |
Seiten- und Seitenelementeigenschaften
Mit der Slides API können Sie das Erscheinungsbild von Seiten und Seitenelementen in Ihrer Präsentation lesen und aktualisieren. Für verschiedene Seitenelemente werden unterschiedliche Eigenschaften unterstützt, mit denen gesteuert wird, wie das Seitenelement gerendert wird.
Für jede Art von Seitenelement gibt es ein entsprechendes Properties-Element und eine Properties-Aktualisierungsnachricht, z. B.:
- Es gibt den Seitenelementtyp Form.
- Das zugehörige Property-Feld ist shapeProperties.
- Die Anfrage zum Aktualisieren dieser Attribute ist UpdateShapePropertiesRequest.
Für jeden Seitenelementtyp gibt es dieselbe Gruppe von Elementen/Properties/Aktualisierungsanfragen: Image/imageProperties/UpdateImageProperties usw.
Sie können das Attribut „properties“ überall dort lesen, wo es beim Lesen eines Elements vorkommt. Wenn Sie die Werte darin ändern möchten, verwenden Sie es mit dem entsprechenden Anfragetyp als Nutzlast für die Methode batchUpdate. So können Sie diese Werte in der Präsentation ändern.
Arten von Properties
Einige Eigenschaften sind für mehrere Arten von Objekten in der Google Präsentationen API üblich:
| Attribut | Beschreibung |
|---|---|
| Farbe | Farben in der Slides API können entweder ein RGB-Wert oder ein Verweis auf eine Designfarbe sein. Auf Designfarben wird anhand des Namens verwiesen (z. B. „DARK1“). Sie können mithilfe des Farbschemas einer Seite RGB-Werten zugeordnet werden. Dieses Farbschema wird in der Regel aktualisiert, wenn Sie das Design der Präsentation im Präsentationen-Editor ändern. |
| Füllung | Die Füllung stellt die Darstellung von leerem Raum in einem Objekt dar. Die am häufigsten unterstützte Füllung in Google-Präsentationen ist eine Volltonfüllung, bei der das Innere eines Objekts mit einer einzelnen Volltonfarbe gefüllt wird. Füllungen können auch für die Hintergründe von Seiten verwendet werden. |
| Umriss | Der Umriss stellt die Linien dar, die das Seitenelement umgeben. Die Farbe von Linien wird mit einer Füllung festgelegt. Anrufer können auch die Breite und den Strichstil von Konturen anpassen. |
| Schatten | Der Schatten ist ein visueller Effekt, der den physischen Schatten des Objekts nachahmen soll. Derzeit sind Schatten in der Slides API schreibgeschützt. |
Attribute aktualisieren
Verwenden Sie zum Aktualisieren einer Eigenschaft die entsprechende Update...Properties-Anfrage in einem batchUpdate-Aufruf, z. B. UpdateShapeProperties für Formen. Diese Anfragen akzeptieren eine vollständige Properties-Nachricht und können Feldmasken verwenden, um festzulegen, welche Felder in der Properties-Nachricht aktualisiert werden sollen.
Übernahme für Properties
Eine Seite oder ein Seitenelement kann Attribute von seinen übergeordneten Objekten übernehmen. Die Eigenschaften eines Objekts, einschließlich der von ihm definierten und der von ihm geerbten Eigenschaften, bestimmen sein endgültiges Erscheinungsbild.
- Seiteneigenschaften: Eine Seite übernimmt alle Eigenschaften, die nicht auf der Seite selbst, sondern im Layout oder in der Masterseite definiert sind, auf der sie basiert.
- Formeigenschaften: Eine Form kann als Platzhalter markiert werden. So können Sie explizit auf eine andere Platzhalterform (im übergeordneten Layout oder der Master-Folie der Seite) verweisen, von der Eigenschaften übernommen werden sollen.
Diese Ideen werden in den folgenden Absätzen näher erläutert.
Übernahme von Seiteneigenschaften
Die Struktur von Folien, Layouts und Masterfolien definiert eine Vererbungshierarchie innerhalb der Präsentation: Folien werden von Layouts und Layouts von Masterfolien abgeleitet. Das übergeordnete Layout und die Masterfolie einer Folie werden im Feld slideProperties der Folie angegeben.
Eine Seite kann Attribute wie Hintergrund und Farbschema von einer übergeordneten Seite übernehmen. Damit eine Property übernommen wird, muss auf der untergeordneten Seite in der Nachricht PageProperties kein Wert für diese Property festgelegt werden. Wenn der vom übergeordneten Element definierte Wert nicht überschrieben wird, übernimmt die Seite den übernommenen Wert.
Das folgende Diagramm zeigt eine Folie, die Eigenschaften von einem Layout erbt, das wiederum Eigenschaften von einer Masterfolie erbt:
Die Eigenschaften, die zum Rendern einer Folie verwendet werden, sind eine Kombination aus den Eigenschaften, die sie definiert, und den Eigenschaften, die sie erbt. In diesem Beispiel sind die aufgelösten Werte, die zum Rendern von Folie 1 verwendet werden, die folgenden:
- PropertyA ist „Rot“.
- PropertyB ist „Orange“.
Übernahme von Formeigenschaften
Formen können Attribute wie Füllung, Umriss oder Schatten von anderen Formen übernehmen. Eine Form ist ein Platzhalter, wenn das Feld Shape.placeholder festgelegt ist. Das Feld Shape.placeholder.parentObjectId des untergeordneten Platzhalters gibt den übergeordneten Platzhalter an. Wenn Sie eine neue Folie auf Grundlage eines Layouts erstellen, werden alle Platzhalter in diesem Layout als untergeordnete Formen auf der neuen Folie angezeigt.
Platzhalter auf Masterseiten können auch als übergeordnete Elemente der Platzhalter der Layouts fungieren.
Wenn diese Vererbungshierarchie definiert ist, erbt die untergeordnete Seite eine Eigenschaft, indem dieser Wert in der ShapeProperties-Nachricht nicht festgelegt wird. Wenn der vom übergeordneten Element definierte Wert nicht überschrieben wird, übernimmt die untergeordnete Form den übernommenen Wert.
Das folgende Diagramm zeigt die Vererbung von Eigenschaften zwischen drei Platzhaltern, die sich auf einer Folie, in einem Layout und in einem Master befinden:
Die Attribute, die zum Rendern einer Platzhalterform verwendet werden, sind eine Kombination aus den Attributen, die sie definiert, und den Attributen, die sie erbt. In diesem Beispiel sind die aufgelösten Werte für diese Formen so:
- Platzhalter 1: „propertyA“ wird als „Gelb“ und „propertyB“ als „Grün“ gerendert.
- Placeholder2: propertyA wird als „Gelb“ und propertyB als „Lila“ gerendert.
- Platzhalter 3: „propertyA“ wird als „Gelb“ und „propertyB“ als „Lila“ gerendert.
Formen sind die einzigen Seitenelemente, die übergeordnete Elemente haben können. Andere Typen wie Bilder, Tabellen und Diagramme können keine Platzhalter sein und keine übergeordneten Elemente haben.
Attribute mit PropertyState „ausblenden“
Die Enumeration PropertyState steuert, ob die Property einer Form tatsächlich für das Rendern verwendet wird oder ob der Wert nur für die Vererbung durch untergeordnete Formen verwendet wird. Eine Property mit dem Status NOT_RENDERED wird beim Rendern der Form auf der zugehörigen Seite nicht verwendet. Untergeordnete Elemente mit dem Status RENDERED können diese Property jedoch weiterhin übernehmen.
Das folgende Diagramm zeigt die Vererbung von Eigenschaften zwischen drei Platzhaltern, die das Feld „PropertyState“ bearbeiten:
Die Darstellung von Formattributen kann durch das Feld „PropertyState“ beeinflusst werden. In diesem Beispiel sind die aufgelösten Werte für diese Formen so:
- Platzhalter 1: propertyA wird als „Rot“ gerendert.
- Placeholder2: propertyA wird nicht gerendert. Wenn dies die Eigenschaft „Umriss“ wäre, hätte Placeholder2 keinen Umriss.
- Placeholder3: propertyA wird nicht gerendert.
Es gibt noch einen weiteren möglichen Wert für die Enumeration PropertyState: Der Property-Status INHERIT bedeutet, dass der Property-Status selbst übernommen wird und der Wert des übergeordneten Elements verwendet werden sollte. Formen ohne übergeordnete Elemente können keinen Eigenschaftsstatus von INHERIT haben.