Dimensionar e posicionar os elementos da página

Este guia descreve como dimensionar e posicionar elementos da página usando transformações afins. Para uma introdução conceitual às transformações afins, consulte o guia de conceito Transformações.

Transformação de elementos

A API Slides permite reposicionar e redimensionar elementos em uma página. Para fazer isso, primeiro determine que tipo de transformação precisa ser aplicado e, em seguida, aplique essa transformação usando o método presentations.batchUpdate que contém um ou mais elementos UpdatePageElementTransformRequest.

As transformações podem ser feitas em um dos dois applyModes:

  • ABSOLUTE transforma replace a matriz de transformação existente do elemento. Todos os parâmetros omitidos da solicitação de atualização de transformação são definidos como zero.

  • As transformações RELATIVE são multiplicadas com a matriz de transformação do elemento (a ordem da multiplicação é importante):

$$A' = BA$$

As transformações relativas movem ou dimensionam o elemento da página de onde ele está atualmente. Por exemplo, movendo uma forma 100 pontos para a esquerda ou girando-a 40 graus. As transformações absolutas descartam informações de posição e escala. Por exemplo, mover uma forma para o centro da página ou redimensioná-la para uma largura específica.

Transformações complexas geralmente podem ser expressas como uma sequência de transformações mais simples. O cálculo prévio de uma transformação, combinando várias transformações usando a multiplicação de matrizes, geralmente pode reduzir a sobrecarga.

Para algumas operações, é necessário saber quais são os parâmetros de transformação de um elemento. Se você não tiver esses valores, poderá recuperá-los com uma solicitação presentations.pages.get.

Tradução

A tradução é simplesmente a ação de mover um elemento de página para uma nova posição na mesma página. As traduções absolutas movem o elemento para um ponto específico, enquanto as traduções relativas movem o elemento para uma distância específica.

Uma matriz de transformação de tradução básica tem a seguinte forma:

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

Quando você usa uma UpdatePageElementTransformRequest para transformar um elemento (sem alterar o tamanho, a inclinação ou a orientação dele), é possível usar uma das seguintes estruturas 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'
  }
}

Escalonamento

A escala é a ação de esticar ou comprimir um elemento ao longo das dimensões X e/ou Y para mudar o tamanho dele. Uma matriz de transformação de escalonamento básica tem o seguinte formato:

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

É possível usar esse formulário de matriz diretamente como uma transformação RELATIVE para redimensionar um elemento, mas isso também pode afetar a distorção e a tradução renderizadas do elemento. Para dimensionar o elemento sem afetar a cisalhamento ou a tradução, mude para o frame de referência.

Rotação

As transformações de rotação giram um elemento da página em torno de um ponto, usando os parâmetros de escala e cisalhamento. A matriz de transformação de rotação básica tem a seguinte forma, em que o ângulo de rotação (em radianos) é medido a partir do eixo X, movendo-se no sentido anti-horário:

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

Assim como na escala, é possível usar esse formulário de matriz diretamente como uma transformação RELATIVE para girar um elemento, mas isso faz com que o elemento seja girado em torno da origem da página. Para girar o elemento em torno do centro ou de um ponto diferente, mude para esse frame de referência.

Reflexão

A reflexão espelha um elemento em uma linha ou eixo específico. A matriz básica de transformação de reflexão das eixos X e Y tem os seguintes formatos:

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

Assim como na escala, é possível usar esse formulário de matriz diretamente como uma transformação RELATIVE para refletir um elemento, mas isso faz com que o elemento seja traduzido também. Para refletir o elemento sem nenhuma tradução, mude para o frame de referência.

Frames de referência de elemento

Aplicar uma transformação básica de escala, reflexão ou rotação diretamente em um elemento da página produz uma transformação no frame de referência da página. Por exemplo, uma rotação básica gira o elemento em torno da origem da página (o canto superior esquerdo). No entanto, é possível operar no frame de referência do próprio elemento, por exemplo, para girar um elemento em torno do ponto central.

Para transformar um elemento no próprio frame de referência, inclua-o entre duas outras traduções: uma tradução T1 anterior que move o centro do elemento para a origem da página e uma tradução T2 seguinte que move o elemento de volta à posição original. A operação completa pode ser expressa como um produto de matriz:

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

Também é possível mudar para outros frames de referência, traduzindo pontos diferentes para a origem. Esses pontos se tornam o centro do novo frame de referência.

É possível realizar cada uma dessas transformações individualmente como solicitações de transformação RELATIVE sequenciais. O ideal é pré-calcular A' acima com multiplicações de matriz e aplicar o resultado como uma única transformação ABSOLUTE. Como alternativa, pré-calcule o produto T2 * B * T1 e aplique-o como uma única transformação RELATIVE. Elas são mais eficientes, em termos de operações de API, do que enviar as solicitações de transformação individualmente.

Limitações

Alguns campos de dimensionamento e posicionamento são incompatíveis com alguns tipos de elementos de página. A tabela abaixo resume a compatibilidade de determinados elementos da página com campos de dimensionamento e posicionamento.

Campo Forma Vídeo Tabela
Tradução ✔ ✔ ✔
Escala ✔ ✔ Não**
Corte ✔ Não Não

** Para atualizar as dimensões de linhas e colunas da tabela, use UpdateTableRowPropertiesRequest e UpdateTableColumnPropertiesRequest.

Todos os campos de dimensionamento e posicionamento podem gerar resultados inesperados se o elemento da página tiver cisalhamento. Todas as limitações estão sujeitas a mudanças. Para informações atualizadas, consulte a API Google Slides.

A API Slides pode reformular seus valores

Ao criar um elemento de página, você pode especificar um tamanho e uma transformação que ofereçam um determinado resultado visual. No entanto, a API pode substituir os valores fornecidos por outros que geram a mesma aparência visual. Em geral, se você gravar um tamanho usando a API, não há garantia de que o mesmo tamanho será retornado. No entanto, você vai conseguir os mesmos resultados se considerar a transformação.