このページは Cloud Translation API によって翻訳されました。

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

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

要素を変換する

Slides 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 つの変換で囲みます。前の変換 T1 は要素の中心をページの原点に移動し、後の変換 T2 は要素を元の位置に戻します。全体のオペレーションは、行列積として表すことができます。

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

別の基準座標系に切り替えるには、別の点を原点に移動します。これらのポイントが新しい参照フレームの中心になります。

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

制限事項

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

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

テーブルの行と列のディメンションを更新するには、UpdateTableRowPropertiesRequest と UpdateTableColumnPropertiesRequest を使用します。

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

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

ページ要素を作成するときに、特定の視覚効果を生むサイズと変換を指定できます。ただし、Slides API は、指定された値を、同じ外観になる他の値に置き換えることがあります。通常、API を使用してサイズを書き込む場合、同じサイズが返されるとは限りません。ただし、変換を考慮すると、同じ結果が得られます。