Trabalhar com formas com a API JavaScript do PowerPoint

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

Criar formas

As formas são criadas através de e armazenadas numa coleção de formas de diapositivo (slide.shapes). ShapeCollection tem vários .add* métodos para esta finalidade. Todas as formas têm nomes e IDs gerados para as mesmas quando são adicionadas à coleção. Estas são as name propriedades e id , respetivamente. name pode ser definido pelo seu suplemento.

Formas geométricas

É criada uma forma geométrica com uma das sobrecargas de ShapeCollection.addGeometricShape. O primeiro parâmetro é uma enumeração GeometricShapeType ou a cadeia equivalente a um dos valores da enumeração. Existe um segundo parâmetro opcional do tipo ShapeAddOptions que pode especificar o tamanho inicial da forma e a respetiva posição em relação aos lados superior e esquerdo do diapositivo, medido em pontos. Ou estas propriedades podem ser definidas após a forma ser criada.

O seguinte exemplo de código cria um retângulo com o nome "Quadrado" que está posicionado a 100 pontos dos lados superior e esquerdo do diapositivo. O método devolve 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

É criada uma linha com uma das sobrecargas de ShapeCollection.addLine. O primeiro parâmetro é uma enumeração ConnectorType ou a cadeia equivalente a um dos valores da enumeração para especificar a forma como a linha é contorcida entre pontos finais. Existe um segundo parâmetro opcional do tipo ShapeAddOptions que pode especificar os pontos de início e de fim da linha. Ou estas propriedades podem ser definidas após a forma ser criada. O método devolve um Shape objeto.

O seguinte exemplo de código cria uma linha reta no diapositivo.

// 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

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

O seguinte exemplo de código mostra como criar uma caixa de texto no primeiro diapositivo.

// 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 encontram-se em cima do diapositivo. A respetiva colocação é definida pelas left propriedades e top . Funcionam como margens das respetivas margens do diapositivo, medidas em pontos, com left: 0 e top: 0 sendo o canto superior esquerdo. O tamanho da forma é especificado pelas height propriedades e width . O código pode mover ou redimensionar a forma ao repor estas propriedades. (Estas propriedades têm um significado ligeiramente diferente quando a forma é uma linha. Consulte Linhas.)

Texto em formas

As formas geométricas podem conter texto. As formas têm uma textFrame propriedade do tipo TextFrame. O TextFrame objeto gere as opções de apresentação de texto (como margens e excesso de texto). TextFrame.textRange é um objeto TextRange com o conteúdo do texto e as definições do tipo de letra.

O seguinte exemplo de código cria uma forma geométrica denominada "Chavetas" com o texto "Texto da forma". Também ajusta as cores da forma e do 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();
});

Agrupar e desagrupar formas

No PowerPoint, pode agrupar várias formas e tratá-las como uma única forma. Posteriormente, pode desagrupar formas agrupadas. Para saber mais sobre o agrupamento de objetos na IU do PowerPoint, veja Agrupar ou desagrupar formas, imagens ou outros objetos.

Agrupar formas

Para agrupar formas com a API de JavaScript, utilize ShapeCollection.addGroup.

O seguinte exemplo de código mostra como agrupar formas existentes do tipo GeometricShape encontradas no diapositivo atual.

// Groups the geometric shapes on the current slide.
await PowerPoint.run(async (context) => {
    // Get the shapes on the current slide.
    context.presentation.load("slides");
    const slide = context.presentation.getSelectedSlides().getItemAt(0);
    slide.load("shapes/items/type,shapes/items/id");
    await context.sync();

    const shapes = slide.shapes;
    const shapesToGroup = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.geometricShape);
    if (shapesToGroup.length === 0) {
        console.warn("No shapes on the current slide, so nothing to group.");
        return;
    }

    // Group the geometric shapes.
    console.log(`Number of shapes to group: ${shapesToGroup.length}`);
    const group = shapes.addGroup(shapesToGroup);
    group.load("id");
    await context.sync();

    console.log(`Grouped shapes. Group ID: ${group.id}`);
});

Desagrupar formas

Para desagrupar formas com a API javaScript, obtenha a propriedade de grupo do objeto do Shape grupo e, em seguida, chame ShapeGroup.ungroup.

O seguinte exemplo de código mostra como desagrupar o primeiro grupo de formas encontrado no diapositivo atual.

// Ungroups the first shape group on the current slide.
await PowerPoint.run(async (context) => {
    // Get the shapes on the current slide.
    context.presentation.load("slides");
    const slide = context.presentation.getSelectedSlides().getItemAt(0);
    slide.load("shapes/items/type,shapes/items/id");
    await context.sync();

    const shapes = slide.shapes;
    const shapeGroups = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.group);
    if (shapeGroups.length === 0) {
        console.warn("No shape groups on the current slide, so nothing to ungroup.");
        return;
    }

    // Ungroup the first grouped shapes.
    const firstGroupId = shapeGroups[0].id;
    const shapeGroupToUngroup = shapes.getItem(firstGroupId);
    shapeGroupToUngroup.group.ungroup();
    await context.sync();

    console.log(`Ungrouped shapes with group ID: ${firstGroupId}`);
});

Eliminar formas

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

O seguinte exemplo de código mostra como eliminar 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();
});

Confira também

• Trabalhar com tabelas com a API JavaScript do PowerPoint
• Vincular a formas numa apresentação do PowerPoint
• Agrupar ou desagrupar formas, imagens ou outros objetos