Seitenelemente in Größe und Position anpassen

In diesem Leitfaden wird beschrieben, wie Sie Seitenelemente mithilfe von affinen Transformationen mit der Google Präsentationen API skalieren und positionieren. Eine konzeptionelle Einführung in affine Transformationen finden Sie im Konzeptleitfaden Transformationen und Seitenelemente.

Elemente transformieren

Mit der Google Präsentationen API können Sie Elemente auf einer Seite neu positionieren und skalieren. Dazu müssen Sie zuerst die Art der Transformation bestimmen und sie dann mit der Methode presentations.batchUpdate() anwenden, die ein oder mehrere UpdatePageElementTransformRequest-Elemente enthält.

Transformationen können mit einem ApplyMode vorgenommen werden:

• ABSOLUTE ersetzt die vorhandene Transformationsmatrix des Elements. Alle Parameter, die Sie aus der Aktualisierungsanfrage für die 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 an seiner Position verschoben oder skaliert. So können Sie beispielsweise eine Form um 100 Pixel nach links verschieben oder um 40 Grad drehen. Bei absoluten Transformationen werden vorhandene Informationen zu Position und Skalierung verworfen. So können Sie beispielsweise eine Form in die Mitte der Seite verschieben oder auf eine bestimmte Breite skalieren.

Komplexe Transformationen können in der Regel als Abfolge einfacherer Transformationen ausgedrückt werden. Wenn Sie eine Transformation vorab berechnen und mehrere Transformationen mithilfe der Matrixmultiplikation kombinieren, lässt sich der Overhead oft reduzieren.

Die Reihenfolge der Transformationsoperationen ist wichtig. In den meisten Fällen führt das Drehen eines Elements um einen Punkt und dann die Verschiebung zu anderen Ergebnissen als die Verschiebung zuerst.

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 Verschiebung wird ein Seitenelement an eine neue Position auf derselben Seite verschoben. Bei absoluten Verschiebungen wird das Element an einen bestimmten Punkt verschoben, während es bei relativen Verschiebungen um eine bestimmte Entfernung verschoben wird.

Denken Sie daran, dass die Translationsparameter die Position des linken oberen Eckpunkts des Elements angeben, nicht die des Mittelpunkts.

Eine einfache Matrix für die Translationstransformation hat die Form:

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

Wenn Sie ein Element mit einem UpdatePageElementTransformRequest verschieben möchten, ohne seine Größe, Neigung 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 gedehnt oder verkleinert, um die Größe zu ändern. Eine einfache Matrix für die Skalierungstransformation 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 sich jedoch auch auf die gerenderte Scherung und Verschiebung des Elements auswirken. Wenn Sie das Element skalieren möchten, ohne seine Scherung oder Verschiebung zu beeinflussen, wechseln Sie zum Element-Referenzrahmen.

Rotation

Mit Drehtransformationen wird ein Seitenelement mithilfe der Skalierungs- und Scherparameter um einen Punkt gedreht. Die Matrix der einfachen Drehtransformation hat die folgende Form, wobei der Drehwinkel (in Radian) von der X-Achse aus gegen den Uhrzeigersinn gemessen wird:

$$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. Das Element wird dann jedoch um den Ursprung der Seite gedreht. Wenn Sie das Element um seinen Mittelpunkt oder einen anderen Punkt drehen möchten, wechseln Sie zu diesem Referenzframe des Elements.

Beurteilung

Bei der Spiegelung wird ein Element entlang 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 bei der Skalierung können Sie diese Matrixform direkt als RELATIVE-Transformation verwenden, um ein Element zu spiegeln. Dadurch wird das Element jedoch auch verschoben. Wenn Sie das Element ohne Verschiebung spiegeln möchten, wechseln Sie zum Referenzframe des Elements.

Elementreferenzframes

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

Wenn Sie ein Element innerhalb seines eigenen Referenzrahmens transformieren möchten, setzen Sie es zwischen zwei andere Translationen: eine vorangehende Translation T1, die das Elementzentrum zum Ursprung der Seite verschiebt, und eine nachfolgende Translation T2, die das Element wieder an seine ursprüngliche Position verschiebt. Der vollständige 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 verschiedene Punkte an den Ursprung verschieben. Diese Punkte werden zum Mittelpunkt des neuen Referenzframes.

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

Beschränkungen

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

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

Verwenden Sie UpdateTableRowPropertiesRequest und UpdateTableColumnPropertiesRequest, um die Tabellenzeilen- und ‑Spaltendimensionen zu aktualisieren.

Alle Felder für Größe und Positionierung können zu unerwarteten Ergebnissen führen, wenn das Seitenelement eine Verschiebung hat. Alle Einschränkungen können sich ändern. Aktuelle Informationen finden Sie unter Google Präsentationen API.

Überarbeitete 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 Ihre angegebenen Werte jedoch durch andere ersetzen, die dieselbe visuelle Darstellung ergeben. Wenn Sie eine Größe über die API schreiben, ist nicht garantiert, dass dieselbe Größe zurückgegeben wird. Sie sollten jedoch dieselben Ergebnisse erhalten, wenn Sie die Transformation berücksichtigen.