Associar e atualizar formas em uma apresentação do PowerPoint

Use associações de forma quando o suplemento precisar localizar e atualizar a mesma forma mais tarde, como atualizar um número de uma fonte de dados externa.

Uma associação cria um identificador estável para uma forma. Seu suplemento pode usar esse identificador para obter a forma novamente, atualizá-la e lidar com casos em que a forma foi excluída.

As associações oferecem dois benefícios principais:

• Elas estabelecem uma relação entre o suplemento e a forma no documento. O documento mantém as associações, para que você possa acessá-las mais tarde.
• Elas permitem o acesso às propriedades da forma para leitura ou atualização, sem exigir que o usuário selecione nenhuma forma.

A imagem a seguir mostra como um suplemento pode se associar a duas formas em um slide. Cada forma tem uma ID de associação criada pelo suplemento: star e pie. Usando a ID de associação, o suplemento pode acessar a forma desejada para atualizar suas propriedades.

Cenário: sincronizar formas com uma fonte de dados

Um cenário comum é manter os visuais da apresentação atualizados a partir de uma fonte de dados. Em vez de substituir manualmente as imagens, um suplemento pode recuperar os dados mais recentes, convertê-los em uma imagem codificada em Base64 e atualizar a forma correta usando sua ID de associação.

Em uma implementação geral, considere dois componentes para associar uma forma no PowerPoint e atualizá-la com uma nova imagem de uma fonte de dados.

1. A fonte de dados. Isso é qualquer fonte de dados ou biblioteca de ativos, como o Microsoft SharePoint ou o Microsoft OneDrive.
2. O suplemento do PowerPoint. O suplemento obtém dados da fonte de dados com base no que o usuário precisa. Ele converte os dados em uma imagem codificada em Base64. Esse é o único tipo de preenchimento que a forma acoplada pode aceitar. Ele insere uma forma a pedido do usuário e a associa a um identificador exclusivo. Em seguida, ele preenche a forma com a imagem Base64 com base na fonte de dados original. As formas são atualizadas mediante a solicitação do usuário, e o suplemento usa o identificador de associação para localizar a forma e atualizar a imagem com a última imagem Base64 salva.

Criar uma forma encadernada no PowerPoint

Use BindingCollection.add para criar uma associação que faça referência a uma forma específica.

O exemplo a seguir mostra como criar uma forma no primeiro slide selecionado.

await PowerPoint.run(async (context) => {
    const slides = context.presentation.getSelectedSlides();

    // Insert new shape on first selected slide.
    const myShape = slides
        .getItemAt(0)
        .shapes.addGeometricShape(PowerPoint.GeometricShapeType.rectangle, {
            top: 100,
            left: 30,
            width: 200,
            height: 200
        });

    // Fill shape with a Base64-encoded image.
    // Note: The image is typically created from a data source request.
    const productsImage = "...Base64 image data...";
    myShape.fill.setImage(productsImage);

    await context.sync();
});

Chamada BindingCollection.add para adicionar a forma à coleção de associações do PowerPoint. O exemplo a seguir continua do exemplo anterior e adiciona uma nova associação para myShape.

// Create a binding ID to track the shape for later updates.
const bindingId = "productChart";
// Create a binding by adding the shape to the bindings collection.
context.presentation.bindings.add(myShape, PowerPoint.BindingType.shape, bindingId);

Atualizar uma forma encadernada com dados atualizados

Depois que houver uma atualização para os dados da imagem, atualize a imagem da forma localizando-a por meio do identificador de associação. O exemplo de código a seguir mostra como localizar uma forma associada com o identificador e preenchê-la com uma imagem atualizada. A imagem é atualizada pelo suplemento com base na solicitação da fonte de dados ou fornecida diretamente pela fonte de dados.

async function updateBinding(bindingId, image) {
    await PowerPoint.run(async (context) => {
        try {
            // Get the shape based on binding ID.
            const myShape = context.presentation.bindings
                .getItem(bindingId)
                .getShape();

            // Update the shape to latest image.
            myShape.fill.setImage(image);
            await context.sync();

        } catch (err) {
            console.error(err);
        }
    });
}

Excluir uma associação

O exemplo a seguir mostra como excluir uma associação excluindo-a da coleção de associações.

async function deleteBinding(bindingId) {
    await PowerPoint.run(async (context) => {
        context.presentation.bindings.getItem(bindingId).delete();
        await context.sync();
    });
}

Carregar associações

Quando um usuário abre uma apresentação e seu suplemento é carregado pela primeira vez, você pode carregar todas as associações para continuar trabalhando com eles. O código a seguir mostra como carregar todas as associações em uma apresentação e exibi-las no console.

async function loadBindings() {
    await PowerPoint.run(async (context) => {
        try {
            const myBindings = context.presentation.bindings;
            myBindings.load("items");
            await context.sync();

            // Log all binding IDs to console.
            if (myBindings.items.length > 0) {
                myBindings.items.forEach((binding) => {
                    console.log(binding.id);
                });
            }
        } catch (err) {
            console.error(err);
        }
    });
}

Tratamento de erros quando uma associação ou forma é excluída

Quando você exclui uma forma, o PowerPoint também remove a associação associada da coleção de associação. Todas as referências a essa associação ou forma podem falhar quando você chama métodos ou acessa propriedades. Lide com esses cenários de erro se o suplemento armazenar Binding objetos ou Shape armazenamentos.

O código a seguir mostra uma abordagem para o tratamento de erros quando um objeto de associação faz referência a uma associação excluída. Use uma instrução try/catch e, em seguida, chame uma função para recarregar todas as referências de associação e forma quando ocorrer um erro.

async function getShapeFromBindingID(id) {
    await PowerPoint.run(async (context) => {
        try {
            const binding = context.presentation.bindings.getItem(id);
            const shape = binding.getShape();

            await context.sync();
            return shape;
        } catch (err) {
            console.log(err);
            return undefined;
        }
    });
}

Confira também

Ao manter a atualização visual, talvez você também queira marcar as camadas de forma usando Shape.zOrderPosition.

• Criar e formatar formas em suplementos do PowerPoint
• Modelo de objeto JavaScript do PowerPoint em Suplementos do Office
• Crie o seu primeiro suplemento do painel de tarefas do PowerPoint
• Tutorial: Criar um Suplemento do Painel de Tarefas
• Bind to regions in a document or spreadsheet
• Referência da API JavaScript do PowerPoint