Dimensionar e posicionar os elementos da página

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

Transformar elementos

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

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

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

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

$$A' = BA$$

Transformações relativas movem ou dimensionam o elemento de página a partir de seu estado/localização atual. Por exemplo, mover uma forma em 100 pontos para a esquerda ou girá-la em 40 graus. Transformações absolutas descartam as informações atuais de posição e dimensão. Por exemplo, mover uma forma para o centro da página ou dimensioná-la para ter uma largura específica.

Transformações complexas normalmente podem ser expressas como uma sequência de outras simples. Pré-calcular uma transformação, combinando várias transformações usando a multiplicação de matrizes, muitas vezes 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 movimentá-lo gera resultados diferentes de quando se começa com a movimentação.

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

Tradução

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

Lembre-se de que os parâmetros de movimentaçã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}$$

Ao usar uma UpdatePageElementTransformRequest para mover um elemento (sem alterar o tamanho, a distorção ou a orientação), você pode 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

Dimensionamento é o ato de estender ou encolher um elemento ao longo do eixo de X e/ou Y para mudar o tamanho. Uma matriz de transformação de dimensionamento básica tem a seguinte forma:

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

Você pode usar a forma desta matriz diretamente como uma transformação RELATIVE para redimensionar um elemento, mas isso também pode afetar a movimentação e a distorção renderizadas do elemento. Para dimensionar o elemento sem afetar a distorção ou a movimentação, mude para o quadro de referência.

Rotação

Transformações de rotação giram um elemento de página em torno de um ponto usando os parâmetros de dimensionamento e distorção. 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 em sentido anti-horário:

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

Como com o dimensionamento, você pode usar a forma desta 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, use esse quadro de referência.

Reflexão

O reflexo 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 as seguintes 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}$$

Como com o dimensionamento, você pode usar a forma desta matriz diretamente como uma transformação RELATIVE para refletir um elemento, mas isso também gera a movimentação do elemento. Para refletir o elemento sem movimentá-lo, mude para o quadro de referência.

Quadros de referência dos elementos

Aplicar uma transformação básica de dimensionamento, reflexo ou rotação diretamente a um elemento da página gera uma transformação no quadro 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, você pode operar no quadro de referência do próprio elemento, por exemplo, para girar um elemento em torno de seu ponto central.

Para transformar um elemento dentro do próprio quadro 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 posterior 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$$

Além disso, você pode alternar para outros quadros de referência convertendo pontos diferentes na origem. Esses pontos se tornam o centro do novo quadro de referência.

É possível realizar cada uma dessas transformações individualmente na forma de 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 como uma única transformação RELATIVE. Ambos os métodos 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 linha e 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.

A API Slides pode refatorar seus valores

Ao criar um elemento de página, você pode especificar um tamanho e uma transformação que forneça um determinado resultado visual. No entanto, a API pode substituir os valores fornecidos por outros que gerem a mesma aparência. Em geral, se você gravar um tamanho usando a API, não há garantias de que o mesmo tamanho será retornado. Porém, você deve obter os mesmos resultados se levar a transformação em consideração.