Größe und Positionierung von Seitenelementen

In diesem Leitfaden wird beschrieben, wie Sie die Größe und Position von Seitenelementen mithilfe von affinen Transformationen anpassen. Eine konzeptionelle Einführung in affine Transformationen finden Sie im Konzeptleitfaden zu Transformationen.

Elemente transformieren

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

Transformationen können in einem von zwei applyModes erfolgen:

  • ABSOLUTE-Transformationen ersetzen die vorhandene Transformationsmatrix des Elements. Alle Parameter, die Sie bei der Anfrage zur Transformationsaktualisierung weglassen, werden auf null gesetzt.

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

$$A' = BA$$

Relative Transformationen verschieben oder skalieren das Seitenelement von seiner aktuellen Position aus, z. B. indem eine Form um 100 Punkte nach links verschoben oder um 40 Grad gedreht wird. Absolute Transformationen verwerfen vorhandene Positions- und Skalierungsinformationen, z. B. das Verschieben einer Form in die Mitte der Seite oder das Skalieren auf eine bestimmte Breite.

Komplexe Transformationen können normalerweise als eine Abfolge einfacherer Transformationen ausgedrückt werden. Durch die Vorberechnung einer Transformation, bei der mehrere Transformationen mithilfe einer Matrixmultiplikation kombiniert werden, kann der Aufwand häufig reduziert werden.

Bei einigen Vorgängen müssen Sie die vorhandenen Transformationsparameter eines Elements kennen. Wenn Sie diese Werte nicht haben, können Sie sie mit einer presentations.pages.get-Anfrage abrufen.

Übersetzung

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

Eine einfache Translation-Transformationsmatrix hat folgende Form:

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

Wenn Sie ein Element mit UpdatePageElementTransformRequest übersetzen, 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'
  }
}

Skalierung

Unter Skalierung versteht man das Dehnen oder Quetschen eines Elements entlang der X- und/oder Y-Dimension, um seine Größe zu ändern. Eine einfache Skalierungstransformationsmatrix hat die 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 jedoch auch die gerenderte Scherung und Verschiebung des Elements beeinflussen. Wenn Sie das Element skalieren möchten, ohne seine Scherung oder Übersetzung zu beeinträchtigen, verschieben Sie es zu seinem Referenzframe.

Rotation

Bei Rotationstransformationen wird ein Seitenelement mit den Parametern "Skalierung" und "Scheren" um einen Punkt gedreht. Die grundlegende Rotationstransformationsmatrix hat die folgende Form, bei der der Drehwinkel (im Bogenmaß) von der X-Achse aus gemessen wird, wobei er sich gegen den Uhrzeigersinn bewegt:

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

Wie bei der Skalierung 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, verschieben Sie es zu diesem Referenzframe.

Beurteilung

Bei der Reflexion wird ein Element entlang einer bestimmten Linie oder Achse gespiegelt. Die grundlegende Reflexionstransformationsmatrix für die 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 bei der Skalierung können Sie diese Matrixform direkt als RELATIVE-Transformation verwenden, um ein Element widerzuspiegeln. Dadurch wird das Element jedoch ebenfalls übersetzt. Wenn das Element ohne Übersetzung widergespiegelt werden soll, verschieben Sie es zum Referenzframe.

Referenzframes für Elemente

Wenn Sie eine einfache Skalierungs-, Reflexions- oder Rotationstransformation direkt auf ein Seitenelement anwenden, wird eine Transformation im Referenzframe der Seite erzeugt. Bei einer einfachen Rotation wird das Element beispielsweise um den Ursprung der Seite (die obere linke Ecke) gedreht. Sie können jedoch im Referenzframe des Elements selbst arbeiten, z. B. um ein Element um seinen Mittelpunkt zu drehen.

Wenn Sie ein Element innerhalb seines eigenen Referenzframes transformieren möchten, schließen Sie es zwischen zwei anderen Übersetzungen ein: eine vorherige Übersetzungs-T1, die das Elementmittelpunkt zum Seitenursprung verschiebt, und eine folgende Übersetzungs-T2, die das Element zurück an seine ursprüngliche Position verschiebt. Die vollständige Operation kann als Matrixprodukt ausgedrückt werden:

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

Sie können auch zu anderen Referenzframes wechseln, indem Sie stattdessen verschiedene Punkte in den Ursprung übersetzen. Diese Punkte werden zum Zentrum des neuen Referenzframes.

Jede dieser Transformationen kann einzeln als sequenzielle RELATIVE-Transformationsanfragen ausgeführt werden. Idealerweise sollten Sie A' oben mit Matrixmultiplikationen vorausberechnen und das Ergebnis als einzelne ABSOLUTE-Transformation anwenden. Alternativ können Sie das T2 * B * T1-Produkt vorab berechnen und dieses als einzelne RELATIVE-Transformation anwenden. Beide sind in Bezug auf API-Vorgänge effizienter, da die Transformationsanfragen dann einzeln gesendet werden.

Beschränkungen

Einige Größen- und Positionierungsfelder sind mit einigen Arten von Seitenelementen nicht kompatibel. In der folgenden Tabelle ist die Kompatibilität bestimmter Seitenelemente mit den Feldern für Größenanpassung und Positionierung zusammengefasst.

Field Form Video Tabelle
Übersetzung ✔ ✔ ✔
Scale ✔ ✔ Nein**
Scherung ✔ Nein Nein

** Verwenden Sie UpdateTableRowPropertiesRequest und UpdateTableColumnPropertiesRequest, um die Zeilen- und Spaltendimensionen von Tabellen zu aktualisieren.

Alle Größen- und Positionierungsfelder können zu unerwarteten Ergebnissen führen, wenn das Seitenelement eine Scherung aufweist. Alle Einschränkungen können sich ändern. Aktuelle Informationen finden Sie unter Google Slides API.

Die Slides API refaktoriert möglicherweise Ihre Werte

Wenn Sie ein Seitenelement erstellen, können Sie eine Größe und eine Transformation angeben, die zu einem bestimmten visuellen Ergebnis führt. Die API kann die von Ihnen bereitgestellten Werte jedoch durch andere Werte ersetzen, die die gleiche visuelle Darstellung erzielen. Wenn Sie eine Größe mit der API schreiben, ist nicht garantiert, dass Sie dieselbe Größe erhalten. Wenn Sie die Transformation berücksichtigen, sollten Sie jedoch dieselben Ergebnisse erhalten.