ページ要素のサイズと位置

このガイドでは、Google スライド API でアフィン変換を使用してページ要素のサイズと位置を設定する方法について説明します。アフィン変換のコンセプトについては、変換とページ要素のコンセプトガイドをご覧ください。

要素を変換する

スライド API を使用すると、ページ上の要素の位置を変更したり、要素を拡大縮小したりできます。これを行うには、まず適用する変換の種類を決定し、 1 つ以上の UpdatePageElementTransformRequest 要素を含む presentations.batchUpdate() メソッドを使用してその変換を適用します。

変換は ApplyModeを使用して行うことができます。

ABSOLUTE 変換は、要素の既存の変換行列を置き換えます。変換更新リクエストで省略したパラメータはゼロに設定されます。
RELATIVE 変換は、要素の既存の変換行列と掛け合わせます（掛け合わせる順序が重要です）。

$$A' = BA$$

相対変換では、ページ要素を現在の位置から移動または拡大縮小します。たとえば、図形を左に 100 ポイント移動したり、40 度回転させたりします。絶対変換では、既存の位置とスケールの情報が破棄されます。たとえば、図形をページの中央に移動したり、特定の幅に拡大縮小したりします。

複雑な変換は、通常、より単純な変換のシーケンスとして表現できます。変換を事前に計算する（行列の乗算を使用して複数の変換を組み合わせる）と、オーバーヘッドを削減できることがよくあります。

一部のオペレーションでは、要素の既存の変換パラメータを知っておく必要があります。これらの値がない場合は、 presentations.pages.get() メソッドを使用して取得できます。

移動

移動とは、ページ要素を同じページ上の新しい位置に移動するアクションです。絶対移動では、要素を特定のポイントに移動します。相対移動では、要素を特定の距離だけ移動します。

基本的な変換行列の形式は次のとおりです。

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

UpdatePageElementTransformRequestを使用して要素を移動する場合（サイズ、せん断、向きを変更しない場合）、次のいずれかのAffineTransform構造を使用できます。

// 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'
  }
}

スケール

スケーリングとは、X 軸または Y 軸に沿って要素を伸縮してサイズを変更するアクションです。基本的なスケーリング変換行列の形式は次のとおりです。

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

この行列形式を RELATIVE 変換として直接使用して要素のサイズを変更できますが、要素のレンダリングされたせん断と移動にも影響する可能性があります。せん断や移動に影響を与えずに要素を拡大縮小するには、要素の参照フレームに切り替えます。

回転

回転変換では、スケーリングパラメータとせん断パラメータを使用して、ページ要素をある点を中心に回転させます。基本的な回転変換行列の形式は次のとおりです。回転角度（ラジアン単位）は、X 軸から反時計回りに測定されます。

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

スケーリングと同様に、この行列形式を RELATIVE 変換として直接使用して要素を回転させることができますが、この場合、要素はページの原点を中心に回転します。要素を中心または別の点を中心に回転させるには、その要素の参照フレームに切り替えます。

リフレクション

リフレクションは、特定の線または軸を基準に要素を反転させます。基本的な x 軸と y 軸のリフレクション変換行列の形式は次のとおりです。

$$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}$$

スケーリングと同様に、この行列形式を RELATIVE 変換として直接使用して要素を反転させることができますが、この場合、要素も移動します。移動せずに要素を反転させるには、要素の参照フレームに切り替えます。

要素の参照フレーム

基本的なスケーリング、回転、またはリフレクション変換をページ要素に直接適用すると、ページの参照フレームで変換が行われます。たとえば、基本的な回転では、要素はページの原点（左上隅）を中心に回転します。ただし、要素の参照フレームで操作することもできます。たとえば、要素を中心点を中心に回転させることができます。

要素を独自の参照フレーム内で変換するには、要素を 2 つの移動で囲みます。1 つは、要素の中心をページの原点に移動する先行移動 T1、もう 1 つは、要素を元の位置に戻す後続移動 T2 です。完全なオペレーションは、行列積として表すことができます。

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

代わりに、別の点を原点に移動することで、他の参照フレームに切り替えることもできます。これらの点が新しい参照フレームの中心になります。

これらの変換はそれぞれ、連続する RELATIVE 変換リクエストとして個別に行うことができます。理想的には、行列の乗算で上記の A' を事前に計算し、その結果を単一の ABSOLUTE 変換として適用します。または、T2 * B * T1 積を事前に計算し、それを単一の RELATIVE 変換として適用します。どちらも、変換リクエストを個別に送信するよりも、API オペレーションの点で効率的です。

制限事項

一部のサイズ設定フィールドと位置設定フィールドは、一部の種類のページ要素と互換性がありません。次の表に、特定のページ要素とサイズ設定フィールドおよび位置設定フィールドの互換性を示します。

フィールド	シェイプ	動画	テーブル
移動	✔	✔	✔
スケール	✔	✔	×**
せん断	✔	いいえ	いいえ

テーブルの行と列のサイズを更新するには、 UpdateTableRowPropertiesRequest と UpdateTableColumnPropertiesRequestを使用します。

ページ要素にせん断がある場合、すべてのサイズ設定フィールドと位置設定フィールドで予期しない結果が生じる可能性があります。すべての制限事項は変更される可能性があります。最新情報については、Google スライド APIをご覧ください。

リファクタリングされた値

ページ要素を作成するときに、特定の視覚的な結果が得られるサイズと変換を指定できます。ただし、スライド API では、指定した値が、同じ視覚的な外観になる別の値に置き換えられることがあります。一般に、API を使用してサイズを書き込んでも、同じサイズが返されるとは限りません。ただし、変換を考慮すると、同じ結果が得られます。