Размер и расположение элементов страницы

В этом руководстве объясняется, как изменять размер и положение элементов страницы с помощью аффинных преобразований в API Google Slides. Для более подробного ознакомления с аффинными преобразованиями см. руководство по концепции «Преобразования и элементы страницы» .

Преобразовать элементы

The Slides API lets you reposition and scale elements on a page. To do this, first determine what kind of transformation needs to be applied and then apply that transform using the presentations.batchUpdate() method containing one or more UpdatePageElementTransformRequest elements.

Преобразования можно выполнять с помощью параметра ApplyMode :

  • ABSOLUTE преобразования заменяют существующую матрицу преобразования элемента. Любые параметры, которые вы не указываете в запросе на обновление преобразования, устанавливаются равными нулю.

  • RELATIVE преобразования умножаются на существующую матрицу преобразования элемента (порядок умножения имеет значение):

$$A' = BA$$

Относительные преобразования перемещают или масштабируют элемент страницы относительно его текущего положения. Например, перемещение фигуры на 100 точек влево или поворот на 40 градусов. Абсолютные преобразования отбрасывают существующую информацию о положении и масштабе; например, перемещение фигуры в центр страницы или масштабирование её до определённой ширины.

Сложные преобразования обычно можно выразить в виде последовательности более простых. Предварительное вычисление преобразования — объединение нескольких преобразований с помощью матричного умножения — часто позволяет уменьшить накладные расходы.

For some operations, you must know what an element's existing transform parameters are. If you don't have these values, you can retrieve them using the presentations.pages.get() method.

Перевод

Абсолютное перемещение — это действие по перемещению элемента страницы в новое положение на той же странице. Абсолютное перемещение перемещает элемент в определенную точку, а относительное перемещение — на определенное расстояние.

Базовая матрица преобразования сдвига имеет следующий вид:

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

Если для элемента страницы используется сдвиг (sharping), все поля, отвечающие за размер и позиционирование, могут давать неожиданные результаты. Все ограничения могут быть изменены. Актуальную информацию см. в документации Google Slides API .

Переработанные значения

При создании элемента страницы вы можете указать размер и преобразование, которые обеспечат определенный визуальный результат. Однако API Slides может заменить предоставленные вами значения другими, дающими тот же визуальный эффект. В целом, если вы указываете размер с помощью API, нет гарантии, что вам будет возвращен тот же размер. Однако вы должны получить тот же результат, если учтете преобразование.