Dimensionar e posicionar elementos da página

Este guia explica como dimensionar e posicionar elementos da página usando transformações afins com a API Google Slides. Para uma introdução conceitual às transformações afins, consulte o guia de conceitos Transformações e elementos da página.

Transformar elementos

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

As transformações podem ser feitas usando um ApplyMode:

• As transformações ABSOLUTE substituem a matriz de transformação atual 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 pela matriz de transformação atual do elemento (a ordem da multiplicação é importante):

$$A' = BA$$

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

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

A ordem das operações de transformação é importante. Na maioria dos casos, girar um elemento em torno de um ponto e depois traduzir produz resultados diferentes do que traduzir primeiro.

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

Tradução

A tradução é 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.

Lembre-se de que os parâmetros de tradução especificam a posição do canto superior esquerdo do elemento, não o centro.

Uma matriz de transformação de tradução básica tem o formato:

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

Quando você usa um UpdatePageElementTransformRequest para traduzir um elemento (sem alterar o tamanho, o cisalhamento ou a orientação), é 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'
  }
}

Escala

O dimensionamento é a ação de esticar ou comprimir um elemento ao longo da dimensão X ou Y para mudar o tamanho dele. Uma matriz de transformação de dimensionamento básica tem o formato:

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

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

Rotação

As transformações de rotação giram um elemento de página em torno de um ponto, usando os parâmetros de dimensionamento e cisalhamento. A matriz de transformação de rotação básica tem o seguinte formato, 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 no dimensionamento, é possível usar esse formato 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 o frame de referência do elemento.

Reflexão

A reflexão espelha um elemento em uma linha ou eixo específico. A matriz de transformação de reflexão básica do eixo 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 no dimensionamento, é possível usar esse formato de matriz diretamente como uma transformação RELATIVE para refletir um elemento, mas isso também faz com que o elemento seja traduzido. Para refletir o elemento sem nenhuma tradução, mude para o frame de referência do elemento frame.

Frames de referência de elementos

A aplicação de uma transformação básica de escala, rotação, ou reflexão diretamente a 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 elemento, por exemplo, para girar um elemento em torno do ponto central.

Para transformar um elemento no próprio frame de referência, coloque-o entre duas outras traduções: uma tradução anterior T1 que move o centro do elemento para a origem da página e uma tradução seguinte T2 que move o elemento de volta para a 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 matrizes e aplicar o resultado como uma única ABSOLUTE transformação. Como alternativa, pré-calcule o produto T2 * B * T1 e aplique-o como uma única transformação RELATIVE. Ambos 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 da página. A tabela a seguir 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.**
Cisalhamento	✔	Não	Não

Para atualizar as dimensões da linha e da coluna 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 atuais, consulte a API Google Slides.

Valores refatorados

Ao criar um elemento de página, é possível especificar um tamanho e uma transformação que forneçam um determinado resultado visual. No entanto, a API Slides pode substituir os valores fornecidos por outros que geram a mesma aparência visual. Em geral, se você escrever um tamanho usando a API, não terá a garantia de receber o mesmo tamanho. No entanto, você vai receber os mesmos resultados se considerar a transformação.