Cómo cambiar el tamaño y la posición de los elementos de la página

En esta guía, se explica cómo dimensionar y posicionar elementos de la página con transformaciones afines en la API de Google Slides. Para obtener una introducción conceptual a las transformaciones afines, consulta la guía de conceptos Transformaciones y elementos de página.

Transformar elementos

La API de Slides te permite cambiar la posición y el tamaño de los elementos en una página. Para ello, primero determina qué tipo de transformación se debe aplicar y, luego, aplica esa transformación con el método presentations.batchUpdate() que contiene uno o más elementos UpdatePageElementTransformRequest.

Las transformaciones se pueden realizar con un objeto ApplyMode:

  • Las transformaciones ABSOLUTE reemplazan la matriz de transformación existente del elemento. Los parámetros que omitas en la solicitud de actualización de la transformación se establecerán en cero.

  • Las transformaciones RELATIVE se multiplican con la matriz de transformación existente del elemento (el orden de la multiplicación es importante):

$$A' = BA$$

Las transformaciones relativas mueven o escalan el elemento de la página desde su posición actual. Por ejemplo, mover una forma 100 puntos hacia la izquierda o rotarla 40 grados. Las transformaciones absolutas descartan la información existente de posición y escala; por ejemplo, mover una forma al centro de la página o escalarla para que tenga un ancho específico.

Por lo general, las transformaciones complejas se pueden expresar como una secuencia de transformaciones más simples. Precalcular una transformación (combinar varias transformaciones con la multiplicación de matrices) a menudo puede reducir la sobrecarga.

Para algunas operaciones, debes conocer los parámetros de transformación existentes de un elemento. Si no tienes estos valores, puedes recuperarlos con el método presentations.pages.get().

Traducción

La traducción es la acción de mover un elemento de la página a una nueva posición en la misma página. Las traducciones absolutas mueven el elemento a un punto específico, mientras que las traducciones relativas mueven el elemento una distancia específica.

Una matriz de transformación de traducción básica tiene la siguiente forma:

$$T=\begin{bmatrix} 1 & 0 & translate\_x\\ 0 & 1 & translate\_y\\ 0 & 0 & 1 \end{bmatrix}$$

Cuando usas un UpdatePageElementTransformRequest para trasladar un elemento (sin alterar su tamaño, sesgo ni orientación), puedes usar una de las siguientes estructuras 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'
  }
}

Escala

El ajuste de escala es la acción de estirar o comprimir un elemento a lo largo de la dimensión X o Y para cambiar su tamaño. Una matriz de transformación de escalamiento básica tiene la siguiente forma:

$$S=\begin{bmatrix} scale\_x & 0 & 0\\ 0 & scale\_y & 0\\ 0 & 0 & 1 \end{bmatrix}$$

Puedes usar esta forma matricial directamente como una transformación RELATIVE para cambiar el tamaño de un elemento, pero esto también puede afectar la distorsión y la traslación renderizadas del elemento. Para escalar el elemento sin afectar su distorsión o traslación, cambia a su marco de referencia del elemento.

Rotación

Las transformaciones de rotación rotan un elemento de la página alrededor de un punto, con los parámetros de escala y sesgo. La matriz de transformación de rotación básica tiene la siguiente forma, en la que el ángulo de rotación (en radianes) se mide desde el eje X, en sentido contrario a las agujas del reloj:

$$R=\begin{bmatrix} cos(\theta) & sin(\theta) & 0\\ -sin(\theta) & cos(\theta) & 0\\ 0 & 0 & 1 \end{bmatrix}$$

Al igual que con el escalamiento, puedes usar esta forma matricial directamente como una transformación RELATIVE para rotar un elemento, pero esto hace que el elemento se rote alrededor del origen de la página. Para rotar el elemento alrededor de su centro o de un punto diferente, cambia a ese marco de referencia del elemento.

Comentarios

La reflexión genera una imagen especular de un elemento a través de una línea o un eje específicos. La matriz de transformación básica de reflexión en los ejes X e Y tiene las siguientes formas:

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

Al igual que con el ajuste, puedes usar esta forma matricial directamente como una transformación RELATIVE para reflejar un elemento, pero esto también hace que el elemento se traslade. Para reflejar el elemento sin ninguna traducción, cambia a su marco de referencia del elemento.

Sistemas de referencia de elementos

Si aplicas una transformación básica de escala, rotación o reflexión directamente a un elemento de la página, se produce una transformación en el marco de referencia de la página. Por ejemplo, una rotación básica rota el elemento alrededor del origen de la página (la esquina superior izquierda). Sin embargo, puedes operar en el marco de referencia del elemento, por ejemplo, para rotar un elemento alrededor de su punto central.

Para transformar un elemento dentro de su propio marco de referencia, encierra el elemento entre otras dos transformaciones: una transformación anterior T1 que mueve el centro del elemento al origen de la página y una transformación posterior T2 que mueve el elemento a su posición original. La operación completa se puede expresar como un producto matricial:

$$A' = T2 \times B \times T1 \times A$$

También puedes cambiar a otros marcos de referencia trasladando diferentes puntos al origen. Estos puntos se convierten en el centro del nuevo marco de referencia.

Es posible realizar cada una de estas transformaciones de forma individual como solicitudes de transformación RELATIVE secuenciales. Lo ideal sería que precalcules A' con multiplicaciones de matrices y apliques el resultado como una sola transformación ABSOLUTE. Como alternativa, calcula previamente el producto T2 * B * T1 y aplícalo como una sola transformación RELATIVE. Ambos son más eficientes, en términos de operaciones de API, que enviar las solicitudes de transformación de forma individual.

Limitaciones

Algunos campos de tamaño y posición no son compatibles con ciertos tipos de elementos de la página. En la siguiente tabla, se resume la compatibilidad de ciertos elementos de la página con los campos de tamaño y posición:

Campo Forma Video Tabla
Traducción ✔ ✔ ✔
Escala ✔ ✔ No**
Cizallamiento ✔ No No

Para actualizar las dimensiones de filas y columnas de la tabla, usa UpdateTableRowPropertiesRequest y UpdateTableColumnPropertiesRequest.

Todos los campos de tamaño y posición pueden arrojar resultados inesperados si el elemento de la página tiene distorsión. Todas las limitaciones están sujetas a cambios. Para obtener información actualizada, consulta la API de Google Slides.

Valores refactorizados

Cuando creas un elemento de página, puedes especificar un tamaño y una transformación que proporcionen un determinado resultado visual. Sin embargo, es posible que la API de Slides reemplace los valores que proporcionaste por otros que produzcan el mismo aspecto visual. En general, si escribes un tamaño con la API, no se garantiza que se te devuelva el mismo tamaño. Sin embargo, deberías obtener los mismos resultados si tienes en cuenta la transformación.