Dimensionar e posicionar os elementos da página

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

Como transformar elementos

Com a Slides API, você pode reposicionar e dimensionar 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 de dois applyModes:

• 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 do elemento atual (a ordem de multiplicação faz diferença):

$$A' = BA$$

Transformações relativas movem ou dimensionam o elemento de página a partir do local onde ele está no momento. Por exemplo, mover uma forma 100 pontos para a esquerda ou girá-la em 40 graus. As transformações absolutas descartam as informações atuais de posição e escala. 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 outras mais simples. Pré-calcular uma transformação, ou seja, a combinação de 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 converter gera resultados diferentes do que se traduzir primeiro.

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

Tradução

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

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

Uma matriz de transformação de translaçã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 converter 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 é a ação de alongar ou apertar um elemento ao longo da dimensão X e/ou Y para mudar o tamanho dele. Uma matriz de transformação de escalonamento básica tem a forma:

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

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

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 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 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, você pode 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 dele ou de um ponto diferente, mude para esse frame de referência.

Reflexão

O reflexo reflete um elemento em uma linha ou eixo específico. A matriz de transformação de reflexo nos eixos x e y básica 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}$$

Assim como no dimensionamento, é possível usar o formato dessa matriz diretamente como uma transformação RELATIVE para refletir um elemento, mas isso também faz com que o elemento seja convertido. Para refletir o elemento sem nenhuma translação, mude para o frame de referência.

Frames de referência dos elementos

Aplicar uma transformação básica de escala, reflexão ou rotação diretamente a um elemento de 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, você pode operar no frame de referência do próprio elemento, por exemplo, para girar um elemento em torno do ponto central dele.

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

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

Você também pode alternar para outros frames de referência, traduzindo pontos diferentes para a origem. Esses pontos se tornam o centro do novo quadro de referência.

É possível executar cada uma dessas transformações individualmente como solicitações de transformação RELATIVE sequenciais. O ideal é pré-computar A' acima com multiplicações de matrizes e aplicar o resultado como uma única transformação ABSOLUTE. Como alternativa, pré-compute o produto T2 * B * T1 e aplique-o como uma única transformação RELATIVE. Em termos de operações da API, ambos são mais eficientes 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 de página com os campos de dimensionamento e posicionamento.

Campo	Forma	Video	Tabela
Tradução	✔	✔	✔
Escala	✔	✔	Não**
Shear (link em inglês)	✔	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 poderão fornecer resultados inesperados se o elemento da página tiver distorção. Todas as limitações estão sujeitas a alterações. Para informações atualizadas, consulte API Google Slides.

A API Slides pode refatorar seus valores

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