Utiliser des balises personnalisées pour les présentations, les diapositives et les formes dans PowerPoint

  • Article

Un complément peut attacher des métadonnées personnalisées, sous la forme de paires clé-valeur, appelées « balises », à des présentations, des diapositives spécifiques et des formes spécifiques sur une diapositive.

Il existe deux scénarios principaux pour l’utilisation des balises :

  • Lorsqu’elle est appliquée à une diapositive ou à une forme, une balise permet à l’objet d’être classé pour le traitement par lots. Par exemple, supposons qu’une présentation comporte des diapositives qui doivent être incluses dans les présentations dans la région Est, mais pas dans la région Ouest. De même, il existe d’autres diapositives qui doivent être affichées uniquement vers l’Ouest. Votre complément peut créer une balise avec la clé REGION et la valeur East et l’appliquer aux diapositives qui doivent être utilisées uniquement dans l’Est. La valeur de la balise est définie sur West pour les diapositives qui doivent être affichées uniquement dans la région Ouest. Juste avant une présentation vers l’Est, un bouton dans le complément exécute le code qui effectue une boucle dans toutes les diapositives vérifiant la valeur de la REGION balise. Les diapositives où se trouve West la région sont supprimées. L’utilisateur ferme ensuite le complément et démarre le diaporama.
  • Lorsqu’elle est appliquée à une présentation, une balise est en fait une propriété personnalisée dans le document de présentation (similaire à une propriété CustomProperty dans Word).

Étiqueter des diapositives et des formes

Une balise est une paire clé-valeur, où la valeur est toujours de type string et est représentée par un objet Tag . Chaque type d’objet parent, tel qu’un objet Presentation, Slide ou Shape , a une tags propriété de type TagsCollection.

Ajouter, mettre à jour et supprimer des balises

Pour ajouter une balise à un objet, appelez la méthode TagCollection.add de la propriété de l’objet tags parent. Le code suivant ajoute deux balises à la première diapositive d’une présentation. Tenez compte du code suivant :

  • Le premier paramètre de la add méthode est la clé dans la paire clé-valeur.
  • Le deuxième paramètre est la valeur .
  • La clé est en majuscules. Cela n’est pas strictement obligatoire pour la add méthode ; toutefois, la clé est toujours stockée par PowerPoint en majuscules, et certaines méthodes liées aux balises nécessitent que la clé soit exprimée en majuscules. Nous vous recommandons donc de toujours utiliser des majuscules dans votre code pour une clé de balise.
async function addMultipleSlideTags() {
  await PowerPoint.run(async function(context) {
    const slide = context.presentation.slides.getItemAt(0);
    slide.tags.add("OCEAN", "Arctic");
    slide.tags.add("PLANET", "Jupiter");

    await context.sync();
  });
}

La add méthode est également utilisée pour mettre à jour une balise. Le code suivant modifie la valeur de la PLANET balise.

async function updateTag() {
  await PowerPoint.run(async function(context) {
    const slide = context.presentation.slides.getItemAt(0);
    slide.tags.add("PLANET", "Mars");

    await context.sync();
  });
}

Pour supprimer une balise, appelez la delete méthode sur son objet parent TagsCollection et passez la clé de la balise en tant que paramètre . Pour obtenir un exemple, consultez Définir des métadonnées personnalisées sur la présentation.

Utiliser des étiquettes pour traiter de manière sélective les diapositives et les formes

Considérez le scénario suivant : Contoso Consulting présente une présentation à tous les nouveaux clients. Toutefois, certaines diapositives ne doivent être affichées que pour les clients qui ont payé le statut « Premium ». Avant d’afficher la présentation aux clients non Premium, ils en font une copie et suppriment les diapositives que seuls les clients Premium doivent voir. Un complément permet à Contoso d’étiqueter les diapositives destinées aux clients Premium et de supprimer ces diapositives si nécessaire. La liste suivante décrit les principales étapes de codage pour créer cette fonctionnalité.

  1. Créez une fonction qui marque la diapositive actuellement sélectionnée comme destinée aux Premium clients. Tenez compte du code suivant :

    • La getSelectedSlideIndex fonction est définie à l’étape suivante. Elle retourne l’index de base 1 de la diapositive actuellement sélectionnée.
    • La valeur retournée par la getSelectedSlideIndex fonction doit être décrémentée, car la méthode SlideCollection.getItemAt est basée sur 0.
    async function addTagToSelectedSlide() {
  await PowerPoint.run(async function(context) {
    let selectedSlideIndex = await getSelectedSlideIndex();
    selectedSlideIndex = selectedSlideIndex - 1;
    const slide = context.presentation.slides.getItemAt(selectedSlideIndex);
    slide.tags.add("CUSTOMER_TYPE", "Premium");

    await context.sync();
  });
}

  2. Le code suivant crée une méthode pour obtenir l’index de la diapositive sélectionnée. Tenez compte du code suivant :

    • Il utilise la méthode Office.context.document.getSelectedDataAsync des API JavaScript courantes.
    • L’appel à getSelectedDataAsync est incorporé dans une fonction de retour de promesse. Pour plus d’informations sur la raison et la façon de procéder, consultez Wrapper les API courantes dans les fonctions de retour de promesse.
    • getSelectedDataAsync retourne un tableau, car plusieurs diapositives peuvent être sélectionnées. Dans ce scénario, l’utilisateur n’en a sélectionné qu’une seule, de sorte que le code obtient la première (0e) diapositive, qui est la seule sélectionnée.
    • La index valeur de la diapositive est la valeur de base 1 que l’utilisateur voit à côté de la diapositive dans le volet Miniatures de l’interface utilisateur PowerPoint.
    function getSelectedSlideIndex() {
    return new OfficeExtension.Promise<number>(function(resolve, reject) {
        Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange, function(asyncResult) {
            try {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    reject(console.error(asyncResult.error.message));
                } else {
                    resolve(asyncResult.value.slides[0].index);
                }
            } 
            catch (error) {
                reject(console.log(error));
            }
        });
    });
}

  3. Le code suivant crée une fonction pour supprimer les diapositives étiquetées pour les clients Premium. Tenez compte du code suivant :

    • Étant donné que les key propriétés et value des balises vont être lues après le context.sync, elles doivent être chargées en premier.
    async function deleteSlidesByAudience() {
  await PowerPoint.run(async function(context) {
    const slides = context.presentation.slides;
    slides.load("tags/key, tags/value");

    await context.sync();

    for (let i = 0; i < slides.items.length; i++) {
      let currentSlide = slides.items[i];
      for (let j = 0; j < currentSlide.tags.items.length; j++) {
        let currentTag = currentSlide.tags.items[j];
        if (currentTag.key === "CUSTOMER_TYPE" && currentTag.value === "Premium") {
          currentSlide.delete();
        }
      }
    }

    await context.sync();
  });
}

Définir des métadonnées personnalisées sur la présentation

Les compléments peuvent également appliquer des balises à la présentation dans son ensemble. Cela vous permet d’utiliser des balises pour les métadonnées au niveau du document, comme la classe CustomPropertyest utilisée dans Word. Mais contrairement à la classe Word CustomProperty , la valeur d’une balise PowerPoint ne peut être que de type string.

Le code suivant est un exemple d’ajout d’une balise à une présentation.

async function addPresentationTag() {
  await PowerPoint.run(async function (context) {
    let presentationTags = context.presentation.tags;
    presentationTags.add("SECURITY", "Internal-Audience-Only");

    await context.sync();
  });
}

Le code suivant est un exemple de suppression d’une balise d’une présentation. Notez que la clé de la balise est passée à la delete méthode de l’objet parent TagsCollection .

async function deletePresentationTag() {
  await PowerPoint.run(async function (context) {
    let presentationTags = context.presentation.tags;
    presentationTags.delete("SECURITY");

    await context.sync();
  });
}