Lier et actualiser des formes dans une présentation PowerPoint

Utilisez des liaisons de forme lorsque votre complément doit rechercher et mettre à jour la même forme ultérieurement, par exemple en actualisant un nombre à partir d’une source de données externe.

Une liaison crée un identificateur stable pour une forme. Votre complément peut utiliser cet identificateur pour récupérer la forme, la mettre à jour et gérer les cas où la forme a été supprimée.

Les liaisons offrent deux avantages clés :

• Ils établissent une relation entre le complément et la forme du document. Le document conserve les liaisons, ce qui vous permet d’y accéder ultérieurement.
• Ils permettent d’accéder aux propriétés de forme pour la lecture ou la mise à jour, sans que l’utilisateur n’ait à 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. En utilisant l’ID de liaison, le complément peut accéder à la forme souhaitée pour mettre à jour ses propriétés.

Scénario : Synchroniser des formes avec une source de données

Un scénario courant consiste à maintenir à jour les visuels de présentation à partir d’une source de données. Au lieu de remplacer manuellement des images, un complément peut récupérer les données les plus récentes, les convertir en image encodée en Base64 et mettre à jour la forme correcte à l’aide de son ID de liaison.

Dans une implémentation générale, envisagez deux composants 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 BindingCollection.add pour créer une liaison qui fait référence à une forme spécifique.

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

    await context.sync();
});

Appelez BindingCollection.add pour ajouter la forme à la collection de liaisons PowerPoint. L’exemple suivant continue de l’exemple précédent et ajoute une nouvelle liaison pour 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);

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

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

Lorsque vous supprimez une forme, PowerPoint supprime également la liaison associée de la collection de liaisons. Toutes les références à cette liaison ou à cette forme peuvent échouer lorsque vous appelez des méthodes ou des propriétés d’accès. Gérez ces scénarios d’erreur si votre complément stocke ou Shape des Binding objets.

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.getItem(id);
            const shape = binding.getShape();

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

Voir aussi

Lorsque vous conservez l’actualisation visuelle, vous pouvez également case activée la superposition de formes à l’aide de Shape.zOrderPosition.

• Créer et mettre en forme des formes dans des compléments PowerPoint
• Modèle objet JavaScript PowerPoint dans les compléments Office
• Créer votre premier complément de volet de tâches PowerPoint
• Didacticiel : Créer un complément de volet de tâches de PowerPoint
• Liaisons de régions dans un document ou une feuille de calcul
• Documentation de référence sur l’API JavaScript pour PowerPoint