Damit Sie die Slides API effektiv nutzen 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:
- Konzeptionelles Modell der Präsentationskomponenten
- Wie die API diese Komponenten darstellt
- Stileigenschaften der Komponenten
Wenn Sie diese und die anderen Konzeptübersichten lesen, können Sie die Anleitungen, die Referenzdokumentation und die Codebeispiele leichter verstehen und verwenden.
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, mit anderen Nutzern geteilt werden kann usw.
Jede Präsentation enthält verschiedene Arten von Seiten. Ein Seitentyp 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 ausmachen, wie im folgenden Diagramm dargestellt:
Neben Folien gibt es noch andere Arten von Seiten, mit denen Sie ein Design auf viele verschiedene Folien anwenden können, um ein einheitliches Erscheinungsbild zu erzielen. Diese anderen Seitentypen sind Master und Layouts. Ihre Eigenschaften bestimmen, wie Folien gerendert werden, wie im folgenden Diagramm dargestellt:
Master: Die Masterseite dient zwei Zwecken. Platzhalter im Master enthalten die Standardeinstellungen 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 diesem Master basieren. Wenn Sie ein Firmenlogo haben, das auf jeder Folie Ihrer Präsentation erscheinen soll, fügen Sie es auf der Masterfolie ein.
Layouts: Layoutvorlagen bestimmen, wie Inhalte auf den einzelnen Folientypen angeordnet werden. Wenn Sie beispielsweise möchten, dass alle Titelfolien ein bestimmtes Aussehen haben, können Sie die Layoutvorlage für Titel bearbeiten.
Es gibt zwei weitere Arten von Seiten: Notizenseiten und Notizenmaster. Diese sind hauptsächlich für die Arbeit mit Vortragsnotizen 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 umfasst eine Reihe von Properties und enthält 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 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 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 zusammen verschoben, skaliert und gedreht werden. |
| Form | Ein einfaches visuelles Objekt, z. B. Rechtecke, Ellipsen und Textfelder. Formen können Text enthalten und sind daher die am häufigsten verwendeten Seitenelemente zum Erstellen von Folien. |
| Bild | Eine in Google Präsentationen importierte Grafik. |
| Video | Ein in Google Präsentationen importiertes Video. |
| Line | Eine visuelle Linie, Kurve oder ein Connector. |
| 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. |
Eigenschaften von Seiten und Seitenelementen
Mit der Slides API können Sie das Erscheinungsbild von Seiten und Seitenelementen in Ihrer Präsentation lesen und aktualisieren. Verschiedene Seitenelemente unterstützen unterschiedliche Eigenschaften, die steuern, wie das Seitenelement gerendert wird.
Jeder Seitenelementtyp hat ein entsprechendes Eigenschaften-Element und eine Nachricht zur Aktualisierung der Eigenschaften, z. B.:
- Es gibt den Seitenelementtyp Shape.
- Das Attributfeld ist shapeProperties.
- Die Anfrage zum Aktualisieren dieser Eigenschaften lautet UpdateShapePropertiesRequest.
Für jeden Seitenelementtyp gibt es dieselben Elemente, Properties und Update-Anfragen: Image/imageProperties/UpdateImageProperties usw.
Sie können das Attribut „properties“ überall dort lesen, wo Sie es beim Lesen eines Elements finden. 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 Attributen
Es gibt einige Eigenschaften, die bei mehreren Arten von Objekten in der Slides API gleich sind:
| Attribut | Beschreibung |
|---|---|
| Farbe | Farben in der Slides API können entweder ein RGB-Wert oder ein Verweis auf eine Designfarbe sein. Designfarben werden mit Namen bezeichnet (z. B. „DARK1“) und können mithilfe des Farbschemas einer Seite RGB-Werten zugeordnet werden. Dieses Farbschema wird normalerweise aktualisiert, wenn das Design der Präsentation im Präsentationen-Editor geändert wird. |
| Füllung | Die Füllung stellt die Darstellung des leeren Raums innerhalb eines Objekts dar. Die am häufigsten unterstützte Füllung in Google Präsentationen ist eine einfarbige Füllung, bei der das Innere eines Objekts mit einer einzigen Volltonfarbe gefüllt wird. Füllungen können auch für den Hintergrund von Seiten verwendet werden. |
| Umriss | Die Umrandung stellt die Linien dar, die das Seitenelement umgeben. Die Farbe von Linien wird mit einer Füllung gesteuert. Anrufer können auch die Breite und den Strichstil von Umrissen anpassen. |
| Schatten | Der Schatten ist ein visueller Effekt, der einen physischen Schatten nachahmen soll, der vom Objekt geworfen wird. Derzeit sind Schatten in der Slides API schreibgeschützt. |
Attribute aktualisieren
Wenn Sie eine Eigenschaft aktualisieren möchten, verwenden Sie 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 für Properties
Eine Seite oder ein Seitenelement kann Eigenschaften von den übergeordneten Objekten übernehmen. Die Attribute eines Objekts, einschließlich der von ihm definierten und der von ihm übernommenen Attribute, bestimmen sein endgültiges visuelles Erscheinungsbild.
- Seiteneigenschaften: Eine Seite übernimmt alle Eigenschaften, die sie nicht selbst definiert, die aber im Layout oder Master definiert sind, auf dem sie basiert.
- Formeigenschaften: Eine Form kann als Platzhalter markiert werden, sodass Sie explizit auf eine andere Platzhalterform (im übergeordneten Layout oder Master der Seite) verweisen können, 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 Mastern definiert eine Vererbungshierarchie innerhalb der Präsentation: Folien erben von Layouts und Layouts erben von Mastern. Das übergeordnete Layout und der Master einer Folie werden im Feld slideProperties der Folie angegeben.
Eine Seite kann Attribute wie Hintergrund und Farbschema von einer übergeordneten Seite übernehmen. Wenn eine untergeordnete Seite eine Property übernehmen soll, wird für diese Property in der PageProperties-Nachricht einfach kein Wert festgelegt. Wenn der vom übergeordneten Element definierte Wert nicht überschrieben wird, akzeptiert die Seite den übernommenen Wert.
Das folgende Diagramm zeigt eine Folie, die Attribute von einem Layout übernimmt, das wiederum von einem Master übernimmt:
Die zum Rendern einer Folie verwendeten Eigenschaften sind eine Kombination aus den von ihr definierten und den von ihr übernommenen Eigenschaften. In diesem Beispiel werden die folgenden aufgelösten Werte zum Rendern von Folie 1 verwendet:
- 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 identifiziert den übergeordneten Platzhalter. Wenn Sie eine neue Folie auf Grundlage eines Layouts erstellen, werden alle Platzhalter in diesem Layout als untergeordnete Formen in der neuen Folie angezeigt.
Ebenso können Platzhalter auf Masterfolien als übergeordnete Elemente der Platzhalter der Layouts fungieren.
Wenn diese Vererbungshierarchie definiert ist, übernimmt die untergeordnete Seite eine Eigenschaft, indem dieser Wert nicht in der ShapeProperties-Nachricht festgelegt wird. Wenn Sie den vom übergeordneten Element definierten Wert nicht überschreiben, akzeptiert die untergeordnete Form den übernommenen Wert.
Das folgende Diagramm zeigt die Vererbung von Eigenschaften zwischen drei Platzhaltern, die in einer Folie, einem Layout und einem Master enthalten sind:
Die Attribute, die zum Rendern einer Platzhalterform verwendet werden, sind eine Kombination aus den von ihr definierten und den von ihr übernommenen Attributen. In diesem Beispiel sind die aufgelösten Werte für diese Formen:
- Platzhalter 1: propertyA wird als „Gelb“ und propertyB als „Grün“ gerendert.
- Platzhalter2: propertyA wird als „Gelb“ und propertyB als „Lila“ gerendert.
- Platzhalter3: propertyA wird als „Gelb“ und propertyB als „Lila“ gerendert.
Formen sind der einzige Typ von Seitenelement, der übergeordnete Elemente haben kann. Andere Typen wie Bilder, Tabellen und Diagramme können keine Platzhalter und keine übergeordneten Elemente sein.
Attribute mit PropertyState „ausblenden“
Die Aufzählung PropertyState steuert, ob ein Attribut einer Form tatsächlich für das Rendering verwendet wird oder ob der Wert nur für die Vererbung durch untergeordnete Formen verwendet wird. Eine Property mit dem Property-Status NOT_RENDERED wird beim Rendern der Form auf der Seite nicht verwendet. Untergeordnete Elemente mit dem entsprechenden Property-Status RENDERED können diese Property jedoch weiterhin übernehmen.
Das folgende Diagramm zeigt die Vererbung von Attributen zwischen drei Platzhaltern, die das Feld „PropertyState“ bearbeiten:
Das Rendering von Formattributen kann durch das Feld „PropertyState“ beeinflusst werden. In diesem Beispiel sind die aufgelösten Werte für diese Formen:
- Platzhalter1: propertyA wird als „Rot“ gerendert.
- Placeholder2: propertyA wird nicht gerendert. Wenn dies die Eigenschaft „outline“ wäre, hätte Placeholder2 keine Kontur.
- Placeholder3: propertyA wird nicht gerendert.
Es gibt einen weiteren möglichen Wert der Aufzählung PropertyState: Der Attributstatus INHERIT bedeutet, dass der Attributstatus selbst übernommen wird und der Wert des übergeordneten Elements verwendet werden soll. Formen ohne übergeordnete Elemente können nicht den Attributstatus INHERIT haben.