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

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

要素の変換

Slides API を使用すると、ページ上の要素の再配置やスケーリングが可能になります。そのためには、最初に適用する変換の種類を決定し、それから 1 つ以上の UpdatePageElementTransformRequest 要素を含む presentations.batchUpdate メソッドを使用して、その変換を適用します。

変換は、次の 2 つのapplyModes のいずれかで実行します。

  • ABSOLUTE 変換は、要素の既存の変換行列を置き換えます。変換の更新リクエストで省略したパラメータはすべて 0 に設定されます。

  • RELATIVE 変換は、要素の既存の変換行列に乗算されます（乗算の順序が重要です）。

$$A' = BA$$

相対変換では、ページ要素を現在の状態から移動またはスケーリングします。たとえば、シェイプを 100 pt 左に動かす、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 つの変換で挟みます。具体的には、先に T1 変換で要素をページの中心に移動させ、その後 T2 変換で要素を元の位置に戻します。全体的な操作は以下のような行列の積で表現されます。

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

別の基準座標系に変換するには、代わりに他の点を原点に変換します。すると、その点が新しい基準座標系における原点になります。

これらの変換は、連続的な RELATIVE 変換リクエストとして個別に実行できます。理想的には、あらかじめ行列の乗算をして上記の A' を求めておき、その結果を単一の ABSOLUTE 変換として適用するとよいでしょう。または、T2 * B * T1 の積を事前に計算し、その結果を 1 つの RELATIVE 変換として適用します。これらの方法は API 操作の観点で効率が良く、変換リクエストを個別に送信できます。

制限事項

サイズと配置のフィールドの中には、一部のタイプのページ要素と互換性がないフィールドがあります。次の表に、特定のページ要素とサイズ設定フィールドと配置フィールドの互換性を示します。

フィールド 図形 動画 表
翻訳 ✔ ✔ ✔
スケーリング ✔ ✔ いいえ**
シアー ✔ いいえ いいえ

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

ページ要素にシアーがある場合、サイズと配置のすべてのフィールドで予期しない結果が返されることがあります。制限事項は変更される可能性があります。最新情報については、Google Slides API をご覧ください。

Slides API による値のリファクタリング

ページ要素を作成してサイズと変換を指定することで、最終的な表示結果が決まります。ただし、指定した値を API 側で置換して、同じ表示結果を実現できることもあります。一般的に、API を使用してサイズを記述する場合、必ずしも同じサイズが返ってくるとは限りません。ただし、変換を考慮に入れると同じ結果が返されます。