Lier des formes dans une présentation PowerPoint

Votre complément PowerPoint peut se lier à des formes pour y accéder de manière cohérente via un identificateur. Le complément établit une liaison en appelant BindingCollection.add et en affectant un identificateur unique. Utilisez l’identificateur à tout moment pour référencer la forme et accéder à ses propriétés. La création de liaisons fournit la valeur suivante à votre complément.

• Établit une relation entre le complément et la forme dans le document. Les liaisons sont conservées dans le document et sont accessibles ultérieurement.
• Permet d’accéder aux propriétés de forme à lire ou à mettre à jour, sans demander à l’utilisateur de sélectionner des formes.

L’image suivante montre comment un complément peut être lié à deux formes sur une diapositive. Chaque forme a un ID de liaison créé par le complément : star et pie. À l’aide de l’ID de liaison, le complément peut accéder à la forme souhaitée pour mettre à jour les propriétés.

Scénario : Utiliser des liaisons pour synchroniser avec une source de données

Un scénario courant pour l’utilisation de liaisons consiste à maintenir les formes à jour avec une source de données. Souvent, lors de la création d’une présentation, les utilisateurs copient et collent des images de la source de données dans la présentation. Au fil du temps, pour maintenir les images à jour, ils copient et collent manuellement les dernières images à partir de la source de données. Un complément peut vous aider à automatiser ce processus en récupérant des images à jour à partir de la source de données pour le compte de l’utilisateur. Lorsqu’un remplissage de forme doit être mis à jour, le complément utilise la liaison pour rechercher la forme correcte et mettre à jour le remplissage de forme avec l’image la plus récente.

Dans une implémentation générale, il existe deux composants à prendre en compte pour lier une forme dans PowerPoint et la mettre à jour avec une nouvelle image à partir d’une source de données.

1. Source de données. Il s’agit de toute source de données ou bibliothèque de ressources, telle que Microsoft SharePoint ou Microsoft OneDrive.
2. Complément PowerPoint. Le complément obtient des données de la source de données en fonction de ce dont l’utilisateur a besoin. Il convertit les données en image encodée en Base64. Il s’agit du seul type de remplissage que la forme liée peut accepter. Il insère une forme à la demande de l’utilisateur et la lie à un identificateur unique. Ensuite, il remplit la forme avec l’image Base64 en fonction de la source de données d’origine. Les formes sont mises à jour à la demande de l’utilisateur et le complément utilise l’identificateur de liaison pour rechercher la forme et mettre à jour l’image avec la dernière image Base64 enregistrée.

Créer une forme liée dans PowerPoint

Utilisez la PowerPoint.BindingCollection.add() méthode de la présentation pour créer une liaison qui fait référence à une forme particulière.

L’exemple suivant montre comment créer une forme sur la première diapositive sélectionnée.

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

Appelez BindingCollection.add pour ajouter la liaison à la collection de liaisons dans PowerPoint. L’exemple suivant montre comment ajouter une nouvelle liaison pour une forme à la collection de liaisons.

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

Actualiser une forme liée avec des données mises à jour

Après une mise à jour des données d’image, actualisez l’image de forme en la recherchant via l’identificateur de liaison. L’exemple de code suivant montre comment rechercher une forme liée avec l’identificateur et la remplir avec une image mise à jour. L’image est mise à jour par le complément en fonction de la demande de source de données ou fournie directement par la source de données.

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

Supprimer une liaison

L’exemple suivant montre comment supprimer une liaison en la supprimant de la collection bindings.

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

Charger des liaisons

Lorsqu’un utilisateur ouvre une présentation et que votre complément se charge en premier, vous pouvez charger toutes les liaisons pour continuer à les utiliser. Le code suivant montre comment charger toutes les liaisons dans une présentation et les afficher dans la console.

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

Gestion des erreurs lors de la suppression d’une liaison ou d’une forme

Lorsqu’une forme est supprimée, sa liaison associée est également supprimée de la collection de liaisons PowerPoint. Toutes les références d’objet que vous avez à la liaison, ou à la forme, retournent des erreurs si vous accédez à des propriétés ou des méthodes sur ces objets. Veillez à gérer les scénarios d’erreur potentiels pour une forme supprimée si votre complément conserve des objets Binding ou Shape.

Le code suivant montre une approche de la gestion des erreurs lorsqu’un objet de liaison fait référence à une liaison supprimée. Utilisez une instruction try/catch, puis appelez une fonction pour recharger toutes les références de liaison et de forme en cas d’erreur.

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

Voir aussi

Lorsque vous conservez l’actualisation des formes, vous pouvez également case activée le zOrder. Pour plus d’informations, consultez la propriété zOrderPosition .

• Utiliser des formes à l’aide de l’API JavaScript PowerPoint
• Liaisons de régions dans un document ou une feuille de calcul