Vincular a formas numa apresentação do PowerPoint

O seu suplemento do PowerPoint pode vincular-se a formas para aceder às mesmas de forma consistente através de um identificador. O suplemento estabelece um enlace ao chamar BindingCollection.add e atribuir um identificador exclusivo. Utilize o identificador em qualquer altura para referenciar a forma e aceder às respetivas propriedades. A criação de enlaces fornece o seguinte valor ao seu suplemento.

• Estabelece uma relação entre o suplemento e a forma no documento. Os enlaces são mantidos no documento e podem ser acedidos posteriormente.
• Permite o acesso às propriedades da forma para ler ou atualizar, sem exigir que o utilizador selecione formas.

A imagem seguinte mostra como um suplemento pode vincular-se a duas formas num diapositivo. Cada forma tem um ID de enlace criado pelo suplemento: star e pie. Com o ID de enlace, o suplemento pode aceder à forma pretendida para atualizar as propriedades.

Cenário: Utilizar enlaces para sincronizar com uma origem de dados

Um cenário comum para utilizar enlaces é manter as formas atualizadas com uma origem de dados. Muitas vezes, ao criar uma apresentação, os utilizadores copiam e colam imagens da origem de dados para a apresentação. Ao longo do tempo, para manter as imagens atualizadas, estas irão copiar e colar manualmente as imagens mais recentes da origem de dados. Um suplemento pode ajudar a automatizar este processo ao obter imagens atualizadas da origem de dados em nome do utilizador. Quando um preenchimento da forma precisa de ser atualizado, o suplemento utiliza o enlace para localizar a forma correta e atualizar o preenchimento da forma com a imagem mais recente.

Numa implementação geral, existem dois componentes a considerar para vincular uma forma no PowerPoint e atualizá-la com uma nova imagem de uma origem de dados.

1. A origem de dados. Esta é qualquer origem de dados ou biblioteca de recursos, como o Microsoft SharePoint ou o Microsoft OneDrive.
2. O suplemento do PowerPoint. O suplemento obtém dados da origem de dados com base no que o utilizador precisa. Converte os dados numa imagem codificada em Base64. Este é o único tipo de preenchimento que a forma vinculada pode aceitar. Insere uma forma a pedido do utilizador e vincula-a a um identificador exclusivo. Em seguida, preenche a forma com a imagem Base64 com base na origem de dados original. As formas são atualizadas a pedido do utilizador e o suplemento utiliza o identificador de enlace para localizar a forma e atualizar a imagem com a última imagem base64 guardada.

Criar uma forma vinculada no PowerPoint

Utilize o PowerPoint.BindingCollection.add() método da apresentação para criar um enlace que se refira a uma forma específica.

O exemplo seguinte mostra como criar uma forma no primeiro diapositivo 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);
});

Chame BindingCollection.add para adicionar o enlace à coleção de enlaces no PowerPoint. O exemplo seguinte mostra como adicionar um novo enlace para uma forma à coleção de enlaces.

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

Atualizar uma forma vinculada com dados atualizados

Depois de existir uma atualização dos dados da imagem, atualize a imagem da forma ao encontrá-la através do identificador de enlace. O seguinte exemplo de código mostra como localizar uma forma vinculada com o identificador e preenchê-la com uma imagem atualizada. A imagem é atualizada pelo suplemento com base no pedido de origem de dados ou fornecido diretamente pela origem 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);
        }
    });
} 

Eliminar um enlace

O exemplo seguinte mostra como eliminar um enlace ao eliminá-lo da coleção de enlaces.

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

Enlaces de carga

Quando um utilizador abre uma apresentação e o seu suplemento é carregado pela primeira vez, pode carregar todos os enlaces para continuar a trabalhar com os mesmos. O código seguinte mostra como carregar todos os enlaces numa apresentação e apresentá-los na consola do .

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

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

Processamento de erros quando um enlace ou forma é eliminado

Quando uma forma é eliminada, o enlace associado também é removido da coleção de enlace do PowerPoint. Quaisquer referências de objetos que tenha ao enlace ou forma irão devolver erros se aceder a quaisquer propriedades ou métodos nesses objetos. Certifique-se de que processa potenciais cenários de erro para uma forma eliminada se o suplemento mantiver os objetos Enlace ou Forma.

O código seguinte mostra uma abordagem ao processamento de erros quando um objeto de enlace referencia um enlace eliminado. Utilize uma instrução try/catch e, em seguida, chame uma função para recarregar todas as referências de enlace e forma quando ocorrer um erro.

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

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

Confira também

Ao manter a frescura nas formas, também poderá querer marcar zOrder. Veja a propriedade zOrderPosition para obter mais informações.

• Trabalhar com formas com a API JavaScript do PowerPoint
• Bind to regions in a document or spreadsheet