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

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

Трансформировать элементы

API Slides позволяет изменять положение и масштаб элементов на странице. Для этого сначала определите, какое преобразование требуется применить, а затем примените его с помощью метода presentations.batchUpdate() содержащего один или несколько элементов UpdatePageElementTransformRequest .

Преобразования можно выполнять с помощью 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 .

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

Рефакторинг значений

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