Trabalhar com formas usando a API JavaScript do PowerPoint

Este artigo descreve como usar formas geométricas, linhas e caixas de texto em conjunto com as APIs Shape e ShapeCollection .

Criar formas

As formas são criadas por meio e armazenadas na coleção de formas de um slide (slide.shapes). ShapeCollection tem vários .add* métodos para essa finalidade. Todas as formas têm nomes e IDs gerados para elas quando são adicionadas à coleção. Estas são as name propriedades e id , respectivamente. name pode ser definido pelo seu suplemento.

Formas geométricas

Uma forma geométrica é criada com uma das sobrecargas de ShapeCollection.addGeometricShape. O primeiro parâmetro é um enumeração GeometricShapeType ou a cadeia de caracteres equivalente a um dos valores do enum. Há um segundo parâmetro opcional do tipo ShapeAddOptions que pode especificar o tamanho inicial da forma e sua posição em relação aos lados superior e esquerdo do slide, medidos em pontos. Ou essas propriedades podem ser definidas após a criação da forma.

O exemplo de código a seguir cria um retângulo chamado "Square" posicionado a 100 pontos dos lados superior e esquerdo do slide. O método retorna um Shape objeto.

// This sample creates a rectangle positioned 100 points from the top and left sides
// of the slide and is 150x150 points. The shape is put on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const rectangle = shapes.addGeometricShape(PowerPoint.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";
    await context.sync();
});

Linhas

Uma linha é criada com uma das sobrecargas de ShapeCollection.addLine. O primeiro parâmetro é um enumeração ConnectorType ou a cadeia de caracteres equivalente a um dos valores do enum para especificar como a linha se contorta entre pontos de extremidade. Há um segundo parâmetro opcional do tipo ShapeAddOptions que pode especificar os pontos de início e de extremidade da linha. Ou essas propriedades podem ser definidas após a criação da forma. O método retorna um Shape objeto.

Observação

Quando a forma é uma linha, as top propriedades e left dos Shape objetos e ShapeAddOptions especificam o ponto de partida da linha em relação às bordas superior e esquerda do slide. As height propriedades e width especificam o ponto de extremidade da linha em relação ao ponto de partida. Portanto, o ponto de extremidade relativo às bordas superior e esquerda do slide é (top + height) por ().left + width A unidade de medida para todas as propriedades é de pontos e valores negativos são permitidos.

O exemplo de código a seguir cria uma linha reta no slide.

// This sample creates a straight line on the first slide.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const line = shapes.addLine(PowerPoint.ConnectorType.straight, {left: 200, top: 50, height: 300, width: 150});
    line.name = "StraightLine";
    await context.sync();
});

Caixas de texto

Uma caixa de texto é criada com o método addTextBox . O primeiro parâmetro é o texto que deve aparecer na caixa inicialmente. Há um segundo parâmetro opcional do tipo ShapeAddOptions que pode especificar o tamanho inicial da caixa de texto e sua posição em relação aos lados superior e esquerdo do slide. Ou essas propriedades podem ser definidas após a criação da forma.

O exemplo de código a seguir mostra como criar uma caixa de texto no primeiro slide.

// This sample creates a text box with the text "Hello!" and sizes it appropriately.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const textbox = shapes.addTextBox("Hello!");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 300;
    textbox.width = 450;
    textbox.name = "Textbox";
    await context.sync();
});

Mover e redimensionar formas

As formas ficam em cima do slide. O posicionamento deles é definido pelas left propriedades e top . Elas atuam como margens das respectivas bordas do slide, medidas em pontos, com left: 0 e top: 0 sendo o canto superior esquerdo. O tamanho da height forma é especificado pelas propriedades e width . Seu código pode mover ou redimensionar a forma redefinindo essas propriedades. (Essas propriedades têm um significado ligeiramente diferente quando a forma é uma linha. Consulte Linhas.)

Texto em formas

Formas geométricas podem conter texto. As formas têm uma textFrame propriedade do tipo TextFrame. O TextFrame objeto gerencia as opções de exibição de texto (como margens e estouro de texto). TextFrame.textRange é um objeto TextRange com o conteúdo de texto e as configurações de fonte.

O exemplo de código a seguir cria uma forma geométrica chamada "Braces" com o texto "Texto de forma". Ele também ajusta a forma e as cores de texto, bem como define o alinhamento vertical do texto para o centro.

// This sample creates a light blue rectangle with braces ("{}") on the left and right ends
// and adds the purple text "Shape text" to the center.
await PowerPoint.run(async (context) => {
    const shapes = context.presentation.slides.getItemAt(0).shapes;
    const braces = shapes.addGeometricShape(PowerPoint.GeometricShapeType.bracePair);
    braces.left = 100;
    braces.top = 400;
    braces.height = 50;
    braces.width = 150;
    braces.name = "Braces";
    braces.fill.setSolidColor("lightblue");
    braces.textFrame.textRange.text = "Shape text";
    braces.textFrame.textRange.font.color = "purple";
    braces.textFrame.verticalAlignment = PowerPoint.TextVerticalAlignment.middleCentered;
    await context.sync();
});

Excluir formas

As formas são removidas do slide com o Shape método do delete objeto.

O exemplo de código a seguir mostra como excluir formas.

await PowerPoint.run(async (context) => {
    // Delete all shapes from the first slide.
    const shapes = context.presentation.slides.getItemAt(0).shapes;

    // Load all the shapes in the collection without loading their properties.
    shapes.load("items/$none");
    await context.sync();
        
    shapes.items.forEach(function (shape) {
        shape.delete();
    });
    await context.sync();
});