Dimensionar e posicionar elementos de página

Há duas maneiras de acessar e mudar o tamanho e a posição de um elemento da página:

  1. Como usar as funções getter e setter para tamanho e posição
  2. Manipulação da transformação afim dela usando as funções getTransform() e setTransform(), preservando o tamanho inerente.

Como ler as propriedades do elemento da página

Dimensionamento e rotação

Como mostrado na figura, o tamanho e a posição são medidos em relação à caixa delimitadora de um elemento de página renderizado quando ele não tem rotação:

  • Esquerda e Superior: medidas do canto superior esquerdo da página até o canto superior esquerdo da caixa delimitadora não girada. Use getLeft() e getTop() para ler os valores.
  • Largura e Altura: a largura e a altura da caixa delimitadora não girada. Use getWidth() e getHeight() para ler os valores.
  • Rotação: a rotação no sentido horário em relação à linha vertical ao redor do centro da caixa delimitadora. Use getRotation() para ler o valor.

Todos os comprimentos são medidos em pontos (pts). A rotação é medida em graus (°).

Definir as propriedades do elemento de página

Você pode definir o tamanho e a posição de um elemento de página durante a criação dele usando um método de inserção, como insertShape(). Para uma forma já existente, é possível definir o tamanho, a posição e a rotação. Também é possível definir o dimensionamento de um elemento para redimensionar ou refleti-lo em uma das bordas.

Na criação

É possível fornecer informações de posição e tamanho ao criar um elemento de página.

var slide = SlidesApp.getActivePresentation().getSlides()[0];
var shape = slide.insertShape(SlidesApp.ShapeType.TEXT_BOX, 100, 200, 300, 60);
Logger.log('Left: ' + shape.getLeft() + 'pt; Top: '
                    + shape.getTop() + 'pt; Width: '
                    + shape.getWidth() + 'pt; Height: '
                    + shape.getHeight() + 'pt; Rotation: '
                    + shape.getRotation() + ' degrees.');

O script acima cria uma forma no primeiro slide da apresentação ativa com a posição e o tamanho especificados e lê as informações de posição e tamanho da forma. O registro esperado é:

Left: 100pt; Top: 200pt; Width: 300pt; Height: 60pt; Rotation: 0 degrees.

Tamanho, posição e rotação

É possível atualizar o tamanho e a posição de um elemento de página após a criação:

  • Use setLeft() e setTop() para definir a posição do canto superior esquerdo da caixa delimitadora não girada.
  • Use setWidth() e setHeight() para definir a largura e a altura renderizadas da caixa delimitadora.
  • Use setRotation() para definir a rotação no sentido horário da caixa delimitadora em torno do centro dela.

O script a seguir cria uma forma no primeiro slide da apresentação ativa, usa setters para atualizar a posição, tamanho e rotação e lê as informações de posição e tamanho da forma.

var slide = SlidesApp.getActivePresentation().getSlides()[0];
var shape = slide.insertShape(SlidesApp.ShapeType.RECTANGLE);
shape.setLeft(100).setTop(200).setWidth(50).setHeight(60).setRotation(90);
Logger.log('Left: ' + shape.getLeft()
                    + 'pt; Top: ' + shape.getTop()
                    + 'pt; Width: ' + shape.getWidth()
                    + 'pt; Height: ' + shape.getHeight()
                    + 'pt; Rotation: ' + shape.getRotation() + '\u00B0.');

A saída de registro esperada desse script é a mostrada abaixo:

Left: 100pt; Top: 200pt; Width: 50pt; Height: 60pt; Rotation: 90°.

Os setters de tamanho, posição e rotação podem ser usados em qualquer ordem ou combinação. Substituir a terceira linha acima pelo script a seguir produzirá o mesmo resultado:

shape.setWidth(55);
shape.setRotation(90).setHeight(60).setLeft(100);
shape.setWidth(50).setTop(200);

Escalonamento

Em vez de usar setWidth() e setHeight() acima para definir o tamanho da forma como um valor absoluto, scaleWidth() e scaleHeight() podem ser usados para esticar ou apertar um elemento de página com um fator de escalonamento relativo.

shape.scaleHeight(0.5).scaleWidth(2);

A figura abaixo ilustra como o código acima funciona em uma forma quadrada com rotação de 45°. O canto superior esquerdo da caixa delimitadora é fixado durante o dimensionamento.

Dimensionamento das Apresentações Google

Reflexo ao longo da borda

O argumento em scaleWidth() e scaleHeight() pode ser negativo para que possa ser usado para virar um elemento de página horizontal ou verticalmente.

shape.scaleWidth(-1); // Flip horizontally along the left edge of the bounding box.
shape.scaleHeight(-1); // Flip vertically along the top edge of the bounding box.

A figura abaixo ilustra como o código acima funciona em uma forma girada em 45°. Observe que o elemento de página é virado ao longo de uma das bordas da caixa delimitadora, mas não no centro.

Reflexão sobre slides

Rotação de linhas

Como outros elementos de página, a rotação de uma linha não é o ângulo vertical dela, mas a rotação da caixa delimitadora. Quando você cria uma linha com os pontos de início e fim especificados, a rotação é sempre de 0°. Arrastar os endpoints da linha na IU das Apresentações Google muda o ângulo vertical, assim como o tamanho e a posição da caixa delimitadora, mas não altera a rotação. O uso de setRotation() gira a caixa delimitadora da linha, o que muda efetivamente o ângulo vertical. Portanto, duas linhas podem ter o mesmo ângulo vertical visual, mas caixas delimitadoras diferentes e, portanto, valores de tamanho, posição e rotação diferentes.

Limitações

Alguns métodos de dimensionamento e posicionamento são incompatíveis com alguns tipos de elementos de página. A tabela abaixo resume os métodos que não são compatíveis com alguns tipos de elementos de página.

Métodos Forma Video Tabela
getHeight(), getWidth() NO (retorna um valor nulo)
setHeight(), setWidth() Noruega
setRotation() Noruega Noruega
scaleHeight(), scaleWidth() Noruega

Todos os métodos de dimensionamento e posicionamento poderão gerar resultados inesperados se o elemento da página tiver distorção. Todas as limitações estão sujeitas a alterações. Consulte a referência para ver informações atualizadas.

Como usar transformações afins

Para controle avançado, o tamanho e a posição de um elemento de página também podem ser calculados e ajustados pelo tamanho inerente (nativo) e pela transformação afim.

O Google Apps Script oferece uma interface semelhante para usar a transformação afim da API Google Slides.

  • Para ler, este artigo explica os conceitos de transformação afim e como inferir o tamanho renderizado com base no tamanho inerente (nativo) e na transformação dos elementos da página. No Apps Script, use
    • getInherentWidth() e getInherentHeight() para o tamanho nativo dos elementos da página;
    • getTransform() para a transformação afim dos elementos de página.
  • Para escrever, este artigo descreve como dimensionar e posicionar elementos de página usando a transformação afim para conseguir dimensionamento, rotação, reflexão etc. No Apps Script, use
    • setTransform() para definir a transformação afim dos elementos da página (semelhante ao modo ABSOLUTE).
    • preconcatenateTransform() para pré-concatenar uma transformação afim à transformação atual dos elementos da página (semelhante ao modo RELATIVE).

O script a seguir cria uma forma, define a transformação, lê o tamanho inerente e lê a transformação afim.

var slide = SlidesApp.getActivePresentation().getSlides()[0];
var shape = slide.insertShape(SlidesApp.ShapeType.RECTANGLE);
shape.setTransform(SlidesApp.newAffineTransformBuilder()
                   .setScaleX(2)
                   .setScaleY(1)
                   .setTranslateX(100)
                   .setTranslateY(200)
                   .build());
Logger.log('Inherent width: ' + shape.getInherentWidth()
                              + 'pt; Inherent height: '
                              + shape.getInherentHeight() + 'pt.');

A saída de registro esperada desse script é a mostrada abaixo:

Inherent width: 236.2pt; Inherent height: 236.2pt.

A forma resultante terá as seguintes transformações e tamanho e posição renderizadas:

AffineTransform{scaleX=2.0, scaleY=1.0, shearX=0.0, shearY=0.0, translateX=100.0, translateY=200.0}
Left: 100pt; Top: 200pt; Width: 472.4pt; Height: 236.2pt; Rotation: 0°.