調整頁面元素的大小和位置

本指南說明如何使用 Google Slides API 的仿射轉換，調整網頁元素大小和位置。如需仿射轉換的概念簡介，請參閱「轉換和頁面元素」概念指南。

轉換元素

您可以使用 Slides API 重新放置及縮放頁面上的元素。如要執行這項操作，請先判斷需要套用哪種轉換，然後使用包含一或多個 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 轉換指令來反映元素，但這也會導致元素平移。如要反映元素而不進行任何翻譯，請切換至元素參照影格。

元素參考影格

直接對網頁元素套用基本縮放、旋轉或反射轉換，會在網頁的參照框架中產生轉換。舉例來說，基本旋轉會讓元素繞著網頁原點 (左上角) 旋轉。不過，您可以在元素的參照影格中操作，例如繞著中心點旋轉元素。

如要在元素本身的參照影格中轉換元素，請將元素放在兩個其他轉換之間：前置轉換 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 寫入大小，系統不保證會傳回相同大小。不過，如果將轉換納入考量，您應該會得到相同結果。