Ajouter et supprimer des diapositives dans PowerPoint

Un complément PowerPoint peut ajouter des diapositives à la présentation et éventuellement spécifier quelle diapositive master et quelle disposition du master est utilisée pour la nouvelle diapositive. Le complément peut également supprimer des diapositives.

Les API permettant d’ajouter des diapositives sont principalement utilisées dans les scénarios où les ID des masque des diapositives et des dispositions de la présentation sont connus au moment du codage ou se trouvent dans une source de données au moment de l’exécution. Dans un tel scénario, vous ou le client devez créer et gérer une source de données qui met en corrélation le critère de sélection (par exemple, les noms ou les images des masques et des dispositions des diapositives) avec les ID des masques et des dispositions des diapositives. Les API peuvent également être utilisées dans les scénarios où l’utilisateur peut insérer des diapositives qui utilisent le master de diapositive par défaut et la disposition par défaut de l’master, et dans les scénarios où l’utilisateur peut sélectionner une diapositive existante et en créer une nouvelle avec la même master de diapositive et la même disposition (mais pas le même contenu). Pour plus d’informations à ce sujet, consultez Sélection de la master et de la disposition des diapositives à utiliser.

Ajouter une diapositive avec SlideCollection.add

Ajoutez des diapositives avec la méthode SlideCollection.add . Voici un exemple simple dans lequel une diapositive qui utilise la diapositive par défaut de la présentation master et la première disposition de cette master est ajoutée. La méthode ajoute toujours de nouvelles diapositives à la fin de la présentation. Voici un exemple.

async function addSlide() {
  await PowerPoint.run(async function(context) {
    context.presentation.slides.add();

    await context.sync();
  });
}

Sélectionner la master et la disposition des diapositives à utiliser

Utilisez le paramètre AddSlideOptions pour contrôler la master de diapositive utilisée pour la nouvelle diapositive et la disposition utilisée dans le master. Voici un exemple. Tenez compte du code suivant :

• Vous pouvez inclure l’une ou les deux propriétés de l’objet AddSlideOptions .
• Si les deux propriétés sont utilisées, la disposition spécifiée doit appartenir au master spécifié, sinon une erreur est générée.
• Si la masterId propriété n’est pas présente (ou si sa valeur est une chaîne vide), la master de diapositive par défaut est utilisée et doit layoutId être une disposition de cette diapositive master.
• Le master de diapositive par défaut est le master de diapositive utilisé par la dernière diapositive de la présentation. (Dans le cas inhabituel où il n’y a actuellement aucune diapositive dans la présentation, la diapositive par défaut master est la première diapositive master de la présentation.)
• Si la layoutId propriété n’est pas présente (ou si sa valeur est une chaîne vide), la première disposition de la master spécifiée par est masterId utilisée.
• Les deux propriétés sont des chaînes de l’une des trois formes possibles : nnnnnnnnnnnn#, #mmmmmmmmmmm ou nnnnnnnn#mmmmmmmmmmm, où nnnnnnnn est l’ID du master ou de la disposition (généralement 10 chiffres) et mmmmmmmmm est l’ID de création du master ou de la disposition (généralement de 6 à 10 chiffres). En voici quelques exemples : 2147483690#2908289500, 2147483690#et #2908289500.

async function addSlide() {
    await PowerPoint.run(async function(context) {
        context.presentation.slides.add({
            slideMasterId: "2147483690#2908289500",
            layoutId: "2147483691#2499880"
        });
    
        await context.sync();
    });
}

Il n’existe aucun moyen pratique pour les utilisateurs de découvrir l’ID ou l’ID de création d’un master ou d’une disposition de diapositive. Pour cette raison, vous pouvez utiliser le AddSlideOptions paramètre uniquement lorsque vous connaissez les ID au moment du codage ou que votre complément peut les découvrir au moment de l’exécution. Étant donné qu’on ne peut pas s’attendre à ce que les utilisateurs mémorisent les ID, vous avez également besoin d’un moyen de permettre à l’utilisateur de sélectionner des diapositives, par exemple par nom ou par image, puis de mettre en corrélation chaque titre ou image avec l’ID de la diapositive.

Par conséquent, le AddSlideOptions paramètre est principalement utilisé dans les scénarios dans lesquels le complément est conçu pour fonctionner avec un ensemble spécifique de masques de diapositives et de dispositions dont les ID sont connus. Dans un tel scénario, vous ou le client devez créer et gérer une source de données qui met en corrélation un critère de sélection (tel que les master de diapositives et les noms de disposition ou les images) avec les ID ou ID de création correspondants.

Laisser l’utilisateur choisir une diapositive correspondante

Si votre complément peut être utilisé dans des scénarios où la nouvelle diapositive doit utiliser la même combinaison de master de diapositive et de disposition que celle utilisée par une diapositive existante, votre complément peut (1) inviter l’utilisateur à sélectionner une diapositive et (2) lire les ID de la diapositive master et de la disposition. Les étapes suivantes montrent comment lire les ID et ajouter une diapositive avec une master et une disposition correspondantes.

1. Créez une fonction pour obtenir l’index de la diapositive sélectionnée. Voici un exemple. 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 en regard de la diapositive dans le volet Miniatures.

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

2. Appelez votre nouvelle fonction à l’intérieur de PowerPoint.run() de la fonction main qui ajoute la diapositive. Voici un exemple.

   async function addSlideWithMatchingLayout() {
       await PowerPoint.run(async function(context) {
   
           let selectedSlideIndex = await getSelectedSlideIndex();
   
           // Decrement the index because the value returned by getSelectedSlideIndex()
           // is 1-based, but SlideCollection.getItemAt() is 0-based.
           const realSlideIndex = selectedSlideIndex - 1;
           const selectedSlide = context.presentation.slides.getItemAt(realSlideIndex).load("slideMaster/id, layout/id");
   
           await context.sync();
   
           context.presentation.slides.add({
               slideMasterId: selectedSlide.slideMaster.id,
               layoutId: selectedSlide.layout.id
           });
   
           await context.sync();
       });
   }
   

Supprimer des diapositives

Supprimez une diapositive en obtenant une référence à l’objet Slide qui représente la diapositive et appelez la Slide.delete méthode . Voici un exemple dans lequel la 4e diapositive est supprimée.

async function deleteSlide() {
    await PowerPoint.run(async function(context) {

        // The slide index is zero-based. 
        const slide = context.presentation.slides.getItemAt(3);
        slide.delete();

        await context.sync();
    });
}