Criar e formatar formas em suplementos do PowerPoint

Use a API JavaScript do PowerPoint para criar, formatar, mover, agrupar e excluir formas em slides.

Este artigo se concentra em formas geométricas, linhas e caixas de texto usando Shape e ShapeCollection.

Exemplo rápido: criar e formatar uma forma

O exemplo a seguir cria uma forma geométrica, posiciona-a e define o preenchimento e a formatação do texto.

await PowerPoint.run(async (context) => {
    const shapes = context.presentation.getSelectedSlides().getItemAt(0).shapes;
    const rectangle = shapes.addGeometricShape(PowerPoint.GeometricShapeType.rectangle);

    rectangle.left = 80;
    rectangle.top = 80;
    rectangle.width = 220;
    rectangle.height = 100;
    rectangle.name = "StatusCard";

    rectangle.fill.setSolidColor("lightblue");
    rectangle.textFrame.textRange.text = "Q2 complete";
    rectangle.textFrame.textRange.font.bold = true;

    await context.sync();
});

Criar formas

As formas são criadas e armazenadas na coleção de formas de um slide (slide.shapes). ShapeCollection tem vários .add* métodos para esse fim. Todas as formas têm nomes e IDs gerados para elas quando são adicionadas à coleção. Estas são as name propriedades and 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 é uma enumeração GeometricShapeType ou o equivalente de cadeia de caracteres de um dos valores da enumeração. 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 "Quadrado" que é 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 é uma enumeração ConnectorType ou o equivalente de cadeia de caracteres de um dos valores da enumeração para especificar como a linha se contorce entre os pontos de extremidade. Há um segundo parâmetro opcional do tipo ShapeAddOptions que pode especificar os pontos inicial e final da linha. Ou essas propriedades podem ser definidas após a criação da forma. O método retorna um Shape objeto.

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 ShapeCollection.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. Seu posicionamento é definido pelas left propriedades and top . Eles atuam como margens das bordas do slide, medidas em pontos, sendo left: 0 e top: 0 o canto superior esquerdo. O tamanho da height forma é especificado pelas propriedades and 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. Veja Linhas.)

A amostra de código a seguir move e redimensiona uma forma.

await PowerPoint.run(async (context) => {
    const slide = context.presentation.getSelectedSlides().getItemAt(0);
    const shape = slide.shapes.getItem("StatusCard");

    shape.left = 120;
    shape.top = 150;
    shape.width = 300;
    shape.height = 120;

    await context.sync();
});

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 texto excedente). TextFrame.textRange é um objeto TextRange com as configurações de texto, conteúdo e fonte.

O exemplo de código a seguir cria uma forma geométrica chamada "Chaves" com o texto "Texto da forma". Ele também ajusta a forma e as cores 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, você pode agrupar várias formas e tratá-las como uma única forma. Em seguida, você pode desagrupar formas agrupadas. Para saber mais sobre como agrupar objetos na interface do usuário do PowerPoint, confira Agrupar ou desagrupar formas, imagens ou outros objetos.

Agrupar formas

Para agrupar formas com a API JavaScript, use ShapeCollection.addGroup.

O exemplo de código a seguir mostra como agrupar formas existentes do tipo ShapeType.geometricShape encontradas no slide 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 group do objeto do Shape grupo e chame ShapeGroup.ungroup.

O exemplo de código a seguir mostra como desagrupar o primeiro grupo de formas encontrado no slide 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}`);
});

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();
});

Confira também

• Crie o seu primeiro suplemento do painel de tarefas do PowerPoint
• Modelo de objeto JavaScript do PowerPoint em Suplementos do Office
• Tutorial: Criar um Suplemento do Painel de Tarefas
• Trabalhar com tabelas usando a API JavaScript do PowerPoint
• Associar a formas em uma apresentação do PowerPoint
• Referência da API JavaScript do PowerPoint
• Agrupar ou desagrupar formas, imagens ou outros objetos