Seitenelemente in Größe und Position anpassen

In diesem Leitfaden wird beschrieben, wie Sie Seitenelemente mithilfe von affinen Transformationen mit der Google Slides API in der Größe anpassen und positionieren. Eine konzeptionelle Einführung in affine Transformationen finden Sie im Konzeptleitfaden Transformationen und Seitenelemente.

Elemente transformieren

Mit der Slides API können Sie Elemente auf einer Seite neu positionieren und skalieren. Bestimmen Sie dazu zuerst, welche Art von Transformation angewendet werden muss, und wenden Sie diese dann mit der Methode presentations.batchUpdate() an, die ein oder mehrere UpdatePageElementTransformRequest-Elemente enthält.

Transformationen können mit einem ApplyMode vorgenommen werden:

  • Mit ABSOLUTE wird die vorhandene Transformationsmatrix des Elements ersetzt. Alle Parameter, die Sie in der Anfrage zur Aktualisierung der Transformation weglassen, werden auf null gesetzt.

  • RELATIVE-Transformationen werden mit der vorhandenen Transformationsmatrix des Elements multipliziert (die Reihenfolge der Multiplikation ist wichtig):

$$A' = BA$$

Bei relativen Transformationen wird das Seitenelement von seiner aktuellen Position aus verschoben oder skaliert, z. B. eine Form um 100 Punkte nach links verschoben oder um 40 Grad gedreht. Bei absoluten Transformationen werden vorhandene Positions- und Skalierungsinformationen verworfen. Das kann beispielsweise beim Verschieben einer Form in die Mitte der Seite oder beim Skalieren auf eine bestimmte Breite passieren.

Komplexe Transformationen lassen sich in der Regel als eine Folge einfacherer Transformationen ausdrücken. Durch die Vorberechnung einer Transformation, bei der mehrere Transformationen durch Matrixmultiplikation kombiniert werden, kann der Aufwand oft reduziert werden.

Für einige Vorgänge müssen Sie die vorhandenen Transformationsparameter eines Elements kennen. Wenn Sie diese Werte nicht haben, können Sie sie mit der Methode presentations.pages.get() abrufen.

Übersetzung

Bei der Übersetzung wird ein Seitenelement an eine neue Position auf derselben Seite verschoben. Bei absoluten Übersetzungen wird das Element an einen bestimmten Punkt verschoben, bei relativen Übersetzungen wird es um eine bestimmte Strecke verschoben.

Eine einfache Transformationsmatrix für die Übersetzung hat die folgende Form:

$$T=\begin{bmatrix} 1 & 0 & translate\_x\\ 0 & 1 & translate\_y\\ 0 & 0 & 1 \end{bmatrix}$$

Wenn Sie ein Element mit einer UpdatePageElementTransformRequest-Transformation übersetzen möchten, ohne seine Größe, Scherung oder Ausrichtung zu ändern, können Sie eine der folgenden AffineTransform-Strukturen verwenden:

// Absolute translation:
{
  'transform': {
    'scaleX':  current scaleX value,
    'scaleY':  current scaleY value,
    'shearX':  current shearX value,
    'shearY':  current shearY value,
    'translateX': X coordinate to move to,
    'translateY': Y coordinate to move to,
    'unit': 'EMU' // or 'PT'
  }
}

// Relative translation (scaling must also be provided to avoid a matrix multiplication error):
{
  'transform': {
    'scaleX':  1,
    'scaleY':  1,
    'translateX': X coordinate to move by,
    'translateY': Y coordinate to move by,
    'unit': 'EMU' // or 'PT'
  }
}

Skalieren

Beim Skalieren wird ein Element entlang der X- oder Y-Achse gestreckt oder zusammengedrückt, um seine Größe zu ändern. Eine grundlegende Skalierungstransformationsmatrix hat die folgende Form:

$$S=\begin{bmatrix} scale\_x & 0 & 0\\ 0 & scale\_y & 0\\ 0 & 0 & 1 \end{bmatrix}$$

Sie können diese Matrixform direkt als RELATIVE-Transformation verwenden, um die Größe eines Elements zu ändern. Dies kann sich jedoch auch auf die gerenderte Scherung und Translation des Elements auswirken. Wenn Sie das Element skalieren möchten, ohne seine Scherung oder Translation zu beeinflussen, wechseln Sie zum Element-Referenzrahmen.

Rotation

Bei Rotations-Transformationen wird ein Seitenelement mithilfe der Skalierungs- und Scherungsparameter um einen Punkt gedreht. Die grundlegende Rotationsmatrix hat die folgende Form, wobei der Drehwinkel (in Radiant) von der X-Achse aus gemessen wird und sich gegen den Uhrzeigersinn bewegt:

$$R=\begin{bmatrix} cos(\theta) & sin(\theta) & 0\\ -sin(\theta) & cos(\theta) & 0\\ 0 & 0 & 1 \end{bmatrix}$$

Wie beim Skalieren können Sie diese Matrixform direkt als RELATIVE-Transformation verwenden, um ein Element zu drehen. Dadurch wird das Element jedoch um den Ursprung der Seite gedreht. Wenn Sie das Element um seinen Mittelpunkt oder einen anderen Punkt drehen möchten, wechseln Sie zum entsprechenden Referenzrahmen.

Beurteilung

Bei der Spiegelung wird ein Element an einer bestimmten Linie oder Achse gespiegelt. Die grundlegende Transformationsmatrix für die Spiegelung an der x- und y-Achse hat die folgenden Formen:

$$F_x=\begin{bmatrix} 1 & 0 & 0\\ 0 & -1 & 0\\ 0 & 0 & 1\\ \end{bmatrix}\qquad\qquad F_y=\begin{bmatrix} -1 & 0 & 0\\ 0 & 1 & 0\\ 0 & 0 & 1\\ \end{bmatrix}$$

Wie beim Skalieren können Sie diese Matrixform direkt als RELATIVE-Transformation verwenden, um ein Element zu spiegeln. Dadurch wird das Element jedoch auch verschoben. Um das Element ohne Übersetzung zu spiegeln, wechseln Sie zum Elementreferenzrahmen.

Elementbezugssysteme

Wenn Sie eine einfache Skalierungs-, Drehungs- oder Spiegelungs-Transformation direkt auf ein Seitenelement anwenden, wird eine Transformation im Referenzrahmen der Seite erzeugt. Bei einer einfachen Drehung wird das Element beispielsweise um den Ursprung der Seite (die obere linke Ecke) gedreht. Sie können jedoch im Referenzrahmen des Elements arbeiten, um es beispielsweise um seinen Mittelpunkt zu drehen.

Wenn Sie ein Element in seinem eigenen Bezugssystem transformieren möchten, schließen Sie es zwischen zwei anderen Translationen ein: einer vorangehenden Translation T1, die den Mittelpunkt des Elements zum Ursprung der Seite verschiebt, und einer nachfolgenden Translation T2, die das Element zurück an seine ursprüngliche Position verschiebt. Der gesamte Vorgang kann als Matrixprodukt ausgedrückt werden:

$$A' = T2 \times B \times T1 \times A$$

Sie können auch zu anderen Referenzrahmen wechseln, indem Sie stattdessen verschiedene Punkte in den Ursprung verschieben. Diese Punkte werden zum Mittelpunkt des neuen Referenzrahmens.

Jede dieser Transformationen kann einzeln als sequenzielle RELATIVE-Transformationsanfrage ausgeführt werden. Im Idealfall sollten Sie A' oben mit Matrixmultiplikationen vorab berechnen und das Ergebnis als einzelne ABSOLUTE-Transformation anwenden. Alternativ können Sie das Produkt T2 * B * T1 vorab berechnen und als einzelne RELATIVE-Transformation anwenden. Beide sind in Bezug auf API-Vorgänge effizienter als das individuelle Senden der Transformationsanfragen.

Beschränkungen

Einige Felder für Größe und Positionierung sind mit bestimmten Arten von Seitenelementen nicht kompatibel. In der folgenden Tabelle wird die Kompatibilität bestimmter Seitenelemente mit den Feldern für Größe und Position zusammengefasst:

Feld Form Video Tabelle
Translation ✔ ✔ ✔
Scale ✔ ✔ Nein**
Scheren ✔ Nein Nein

Verwenden Sie UpdateTableRowPropertiesRequest und UpdateTableColumnPropertiesRequest, um die Abmessungen von Tabellenzeilen und ‑spalten zu aktualisieren.

Alle Felder für Größe und Positionierung können unerwartete Ergebnisse liefern, wenn das Seitenelement Scherung aufweist. Alle Einschränkungen können sich ändern. Aktuelle Informationen finden Sie unter Google Slides API.

Refaktorierte Werte

Wenn Sie ein Seitenelement erstellen, können Sie eine Größe und eine Transformation angeben, die ein bestimmtes visuelles Ergebnis liefern. Die Slides API kann die von Ihnen angegebenen Werte jedoch durch andere Werte ersetzen, die dasselbe Erscheinungsbild haben. Wenn Sie über die API eine Größe angeben, wird Ihnen in der Regel nicht garantiert, dass Sie dieselbe Größe zurückerhalten. Wenn Sie die Transformation berücksichtigen, sollten Sie jedoch dieselben Ergebnisse erhalten.