Seiten, Seitenelemente und Eigenschaften

Damit Sie die Google Slides API effektiv nutzen können, müssen Sie die Architektur von Präsentationen und ihre Komponenten sowie die Interaktionen zwischen diesen Komponenten verstehen. Auf dieser Seite finden Sie eine detaillierte Übersicht zu diesen Themen:

• Konzeptuelles Modell der Präsentationskomponenten
• Darstellung dieser Komponenten in der API
• Stilattribute der Komponenten

Wenn Sie diese und die anderen Konzeptübersichten lesen, können Sie die Anleitungen, die Referenzdokumentation und die Code beispiele besser 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 und für andere Nutzer freigegeben werden kann.

Jede Präsentation enthält verschiedene Arten von Seiten. 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 Arten von Seiten, mit denen Sie das Design auf viele verschiedene Folien anwenden und so ein einheitliches Erscheinungsbild schaffen können. Diese anderen Seitentypen sind Master und Layouts. Ihre Attribute bestimmen, wie Folien gerendert werden, wie im folgenden Diagramm dargestellt:

Master : Die Masterfolie 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 diesem Master basieren. Wenn Sie ein Unternehmenslogo haben, das auf jeder Folie in Ihrer Präsentation angezeigt werden soll, fügen Sie es dem Master hinzu.

Layouts : Layoutvorlagen bestimmen, wie Inhalte auf den einzelnen Folientypen angeordnet werden. Wenn alle Titelfolien auf eine bestimmte Weise aussehen sollen, können Sie beispielsweise die Layoutvorlage für den Titel bearbeiten.

Es gibt zwei weitere Arten von Seiten: Notizenseiten und Notizen master. Sie sind hauptsächlich für die Arbeit mit Referenten notizen relevant.

API-Darstellungstypen und -Struktur

In diesem Abschnitt wird beschrieben, wie das oben beschriebene konzeptuelle Modell von Google Präsentationen in der Google Slides API dargestellt wird.

Das folgende Diagramm zeigt die Beziehung zwischen Präsentationen, Seiten und Seitenelementen als Typen in der Google 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 Attributen 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,
}

Seiten

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:

Elementtyp	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 wie Rechtecke, Ellipsen und Textfelder. Formen können Text enthalten und sind daher die häufigsten Seitenelemente zum Erstellen von Folien.
Bild	Eine Grafik, die in Google Präsentationen importiert wurde.
Video	Ein Video, das in Google Präsentationen importiert wurde.
Linie	Eine visuelle Linie, Kurve oder Verbindungslinie.
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.

Attribute von Seiten und Seitenelementen

Mit der Google Slides API können Sie das Erscheinungsbild von Seiten und Seitenelementen in Ihrer Präsentation lesen und aktualisieren. Verschiedene Seitenelemente unterstützen unterschiedliche Attribute, die steuern, wie das Seitenelement gerendert wird.

Jede Art von Seitenelement hat ein entsprechendes Attributselement und eine Nachricht zur Aktualisierung der Attribute, z. B.:

• Es gibt den Seitenelementtyp Form.
• Das Attributfeld ist „shapeProperties“.
• Die Anfrage zum Aktualisieren dieser Attribute ist UpdateShapePropertiesRequest.

Für jeden Seitenelement typ gibt es denselben Satz von Element-/Attribut-/Aktualisierungsanfragen: „Image/imageProperties/UpdateImageProperties“ usw.

Sie können das Attribut „properties“ überall 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 batchUpdate Methode. So können Sie diese Werte in der Präsentation ändern.

Arten von Attributen

Es gibt einige Attribute, die für mehrere Arten von Objekten in der Google Slides API üblich sind:

Attribut	Beschreibung
Farbe	Farben in der Google 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 in der Regel aktualisiert, wenn Sie das Design der Präsentation im Google Slides-Editor ändern.
Füllung	Die Füllung stellt das Rendering von leerem Raum innerhalb eines Objekts 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 der Linien wird mit einer Füllung gesteuert. Aufrufer 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 Google 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 Attributsnachricht und können Feldmasken verwenden, um zu bestimmen, welche Felder in der Attributsnachricht aktualisiert werden sollen.

Eine Feldmaske mit * wird wie ein Platzhalter behandelt und ist eine Kurzform für die Angabe aller Felder in einer Nachricht. Die Platzhaltersyntax kann unerwünschte Ergebnisse liefern, wenn die API in Zukunft aktualisiert wird, da schreibgeschützte Felder und neu hinzugefügte Felder Fehler verursachen können. Listen Sie für Produktionsanwendungen immer die spezifischen Felder auf, die in Feldmasken aktualisiert werden, und vermeiden Sie die Verwendung von *-Platzhaltern.

Übernahme für Properties

Eine Seite oder ein Seitenelement kann Attribute von seinen übergeordneten Objekten übernehmen. Die Attribute eines Objekts, einschließlich der von ihm definierten und der von ihm übernommenen Attribute, bestimmen sein endgültiges Erscheinungsbild.

• Seiteneigenschaften : Eine Seite übernimmt alle Attribute, die sie nicht definiert, aber die im Layout oder Master definiert sind, auf dem sie basiert.
• Formattribute: Eine Form kann als Platzhalter markiert werden. So können Sie explizit auf eine andere Platzhalterform (im übergeordneten Layout oder Master der Seite) verweisen, von der Attribute übernommen werden sollen.

Diese Ideen werden in den folgenden Abschnitten weiter erläutert.

Übernahme von Seiteneigenschaften

Die Struktur von Folien, Layouts und Mastern definiert eine Übernahmehierarchie in der Präsentation: Folien übernehmen Attribute von Layouts und Layouts übernehmen Attribute 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. Um ein Attribut zu übernehmen, legt die untergeordnete Seite einfach keinen Wert für dieses Attribut in ihrer PageProperties Nachricht fest. Wenn der von der übergeordneten Seite definierte Wert nicht überschrieben wird, akzeptiert die Seite den übernommenen Wert.

Das folgende Diagramm zeigt, wie eine Folie Attribute von einem Layout übernimmt, das Attribute von einem Master übernimmt:

Die Attribute, die zum Rendern einer Folie verwendet werden, sind eine Kombination aus den von ihr definierten und den von ihr übernommenen Attributen. In diesem Beispiel sind die aufgelösten Werte, die zum Rendern von Folie 1 verwendet werden, folgende:

• AttributA ist „Rot“.
• AttributB ist „Orange“.

Eine Seite ohne übergeordnete Seite übernimmt Standardwerte aus Google Präsentationen für alle Attribute, die sie nicht definiert.

Übernahme von Formattributen

Formen können Attribute wie Füllung, Umriss oder Schatten von anderen Formen übernehmen. Eine Form ist ein Platzhalter , wenn das Shape.placeholder Feld 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 in der neuen Folie angezeigt. Ebenso können Platzhalter auf Masterfolien als übergeordnete Elemente der Platzhalter der Layouts fungieren.

Sie können Platzhalter mit dem Google Slides-Editor erstellen, aber nicht mit der Google Slides API.

Mit dieser definierten Übernahmehierarchie übernimmt die untergeordnete Seite ein Attribut, indem sie diesen Wert nicht in ihrer ShapeProperties Nachricht festlegt. Wenn der von der übergeordneten Seite definierte Wert nicht überschrieben wird, akzeptiert die untergeordnete Form den übernommenen Wert.

Das folgende Diagramm zeigt die Übernahme von Attributen 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 folgende:

• Platzhalter1: AttributA wird als „Gelb“ und AttributB als „Grün“ gerendert.
• Platzhalter2: AttributA wird als „Gelb“ und AttributB als „Lila“ gerendert.
• Platzhalter3: AttributA wird als „Gelb“ und AttributB 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.

Wenn eine Form kein übergeordnetes Element hat, werden alle Werte, die sie nicht festlegt, automatisch mit Standardwerten der Anwendung gefüllt.

Attribute mit PropertyState „ausblenden“

Die PropertyState PropertyState steuert, ob das Attribut einer Form tatsächlich für das Rendering verwendet wird, oder ob der Wert nur für die Übernahme durch untergeordnete Formen verwendet wird. Ein Attribut mit dem Attributszustand NOT_RENDERED wird beim Rendern der Form auf seiner Seite nicht verwendet. Untergeordnete Elemente mit dem entsprechenden Attributszustand RENDERED können dieses Attribut jedoch weiterhin übernehmen.

Wenn Sie ein Attribut aktualisieren, wird sein Attributszustand implizit auf `RENDERED` gesetzt, es sei denn, Sie legen den Zustand in derselben Anfrage auf einen anderen Wert fest.

Das folgende Diagramm zeigt die Übernahme 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 folgende:

• Platzhalter1: AttributA wird als „Rot“ gerendert.
• Platzhalter2: AttributA wird nicht gerendert. Wenn dies das Umrissattribut wäre, hätte Platzhalter2 keinen Umriss.
• Platzhalter3: AttributA wird nicht gerendert.

Es gibt einen weiteren möglichen Wert der PropertyState: Der INHERIT Attributszustand bedeutet, dass der Attributszustand selbst übernommen wird und der Wert des übergeordneten Elements verwendet werden soll. Formen ohne übergeordnete Elemente können keinen Attributszustand INHERIT haben.