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

В этом руководстве объясняется, как изменять размер и положение элементов страницы с помощью аффинных преобразований в 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 .

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

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

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