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

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

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

要素を変換する

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

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

ABSOLUTE は、要素の既存の変換行列を置き換える変換を行います。変換更新リクエストで省略したパラメータは 0 に設定されます。
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 オペレーションの面で効率的です。

制限事項

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

フィールド	図形	動画	テーブル
翻訳	✔	✔	✔
スケーリング	✔	✔	×**
Shear	✔	いいえ	いいえ

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

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

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

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