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 página con transformaciones afines con la API de Google Slides. Para obtener una introducción conceptual a las transformaciones afines, consulta la guía de conceptos de transformaciones y elementos de página.

Transforma elementos

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

Las transformaciones se pueden realizar con un ApplyMode:

Las transformaciones ABSOLUTE reemplazan la matriz de transformación existente del elemento. Cualquier parámetro que omitas de la solicitud de actualización de transformación se establece en cero.
Las transformaciones RELATIVE se multiplican con la matriz de transformación existente del elemento (el orden de multiplicación importa):

$$A' = BA$$

Las transformaciones relativas mueven o escalan el elemento de página desde donde está. Por ejemplo, mover una forma 100 puntos hacia la izquierda o rotarla 40 grados. Las transformaciones absolutas descartan la posición existente y la información de 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. El cálculo previo de una transformación (combinar varias transformaciones con la multiplicación de matrices) puede reducir la sobrecarga.

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

Traducción

La traducción es la acción de mover un elemento de 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 a 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 traducir un elemento (sin alterar su tamaño, corte o orientación), puedes usar una de las siguientes AffineTransform estructuras:

// 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 escalamiento 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 de matriz directamente como una transformación RELATIVE para cambiar el tamaño de un elemento, pero esto también puede afectar el corte y la traslación renderizados del elemento. Para escalar el elemento sin afectar su corte o traducción, cambia a su marco de referencia del elemento.

Rotación

Las transformaciones de rotación rotan un elemento de página alrededor de un punto, con los parámetros de escalamiento y corte. 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 y se mueve en sentido antihorario:

$$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 de matriz directamente como una transformación RELATIVE para rotar un elemento, pero esto hace que el elemento rote sobre el origen de la página. Para rotar el elemento sobre su centro o un punto diferente, cambia a ese marco de referencia del elemento frame.

Comentarios

La reflexión refleja un elemento a través de una línea o un eje específico. La matriz de transformación de reflexión básica de los ejes X y 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 escalamiento, puedes usar esta forma de matriz directamente como una transformación RELATIVE para reflejar un elemento, pero esto hace que el elemento también se traslade. Para reflejar el elemento sin ninguna traducción, cambia a su marco de referencia del elemento frame.

Marcos de referencia de elementos

Si aplicas una transformación básica de escala, rotación o reflexión directamente a un elemento de 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 sobre el 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, enciérralo entre otras dos traducciones: una traducción anterior T1 que mueve el centro del elemento al origen de la página y una traducción siguiente T2 que mueve el elemento de vuelta a su posición original. La operación completa se puede expresar como un producto de matriz:

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

También puedes cambiar a otros marcos de referencia si traduces 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 es calcular previamente A' arriba con multiplicaciones de matrices y aplicar el resultado como una sola ABSOLUTE transformación. 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 la API, que enviar las solicitudes de transformación de forma individual.

Limitaciones

Algunos campos de dimensionamiento y posicionamiento no son compatibles con algunos tipos de elementos de página. En la siguiente tabla, se resume la compatibilidad de ciertos elementos de página con los campos de dimensionamiento y posicionamiento:

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

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

Todos los campos de dimensionamiento y posicionamiento pueden arrojar resultados inesperados si el elemento de página tiene corte. 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 resultado visual determinado. Sin embargo, la API de Slides puede reemplazar los valores proporcionados por otros que produzcan la misma apariencia visual. En general, si escribes un tamaño con la API, no se garantiza que se muestre el mismo tamaño. Sin embargo, deberías obtener los mismos resultados si tienes en cuenta la transformación.