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 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 usando um ApplyMode:

• 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 existente 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á. 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 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.

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

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á extraí-los usando o método presentations.pages.get().

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 a seguinte forma:

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

Escala

A escalação é 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 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 distorção ou a tradução, mude para o frame de referência do elemento.

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 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 dos 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 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.

Frames de referência de elemento

Aplicar uma transformação básica de escala, rotação ou reflexã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 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 anterior T1 que move o centro do elemento para a origem da página e uma tradução T2 seguinte 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 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 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**
Corte	✔	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 atualizadas, consulte a API Google Slides.

Valores refatorados

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 Slides 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.