Agregar y eliminar diapositivas en PowerPoint

Un complemento de PowerPoint puede agregar diapositivas a la presentación y, opcionalmente, especificar qué patrón de diapositivas y qué diseño del patrón se usa para la nueva diapositiva. El complemento también puede eliminar diapositivas.

Las API para agregar diapositivas se usan principalmente en escenarios en los que los identificadores de los patrones y diseños de diapositivas de la presentación se conocen en tiempo de codificación o se pueden encontrar en un origen de datos en tiempo de ejecución. En este escenario, usted o el cliente deben crear y mantener un origen de datos que correlacione el criterio de selección (como los nombres o imágenes de patrones y diseños de diapositivas) con los identificadores de los patrones y diseños de diapositivas. Las API también se pueden usar en escenarios en los que el usuario puede insertar diapositivas que usan el patrón de diapositivas predeterminado y el diseño predeterminado del patrón, y en escenarios en los que el usuario puede seleccionar una diapositiva existente y crear una nueva con el mismo patrón de diapositivas y diseño (pero no el mismo contenido). Consulte Selección del patrón de diapositivas y el diseño que se van a usar para obtener más información sobre esto.

Agregar una diapositiva con SlideCollection.add

Agregue diapositivas con el método SlideCollection.add . A continuación se muestra un ejemplo sencillo en el que se agrega una diapositiva que usa el patrón de diapositivas predeterminado de la presentación y el primer diseño de ese patrón. El método siempre agrega nuevas diapositivas al final de la presentación. A continuación se muestra un ejemplo.

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

    await context.sync();
  });
}

Seleccione el patrón de diapositivas y el diseño que se van a usar

Use el parámetro AddSlideOptions para controlar qué patrón de diapositivas se usa para la nueva diapositiva y qué diseño del patrón se usa. A continuación se muestra un ejemplo. Sobre este código, tenga en cuenta:

• Puede incluir o ambas propiedades del AddSlideOptions objeto.
• Si se usan ambas propiedades, el diseño especificado debe pertenecer al patrón especificado o se produce un error.
• Si la masterId propiedad no está presente (o su valor es una cadena vacía), se usa el patrón de diapositivas predeterminado y debe layoutId ser un diseño de ese patrón de diapositivas.
• El patrón de diapositivas predeterminado es el patrón de diapositivas usado por la última diapositiva de la presentación. (En el caso inusual en el que actualmente no hay diapositivas en la presentación, el patrón de diapositivas predeterminado es el primer patrón de diapositivas de la presentación).
• Si la layoutId propiedad no está presente (o su valor es una cadena vacía), se usa el primer diseño del patrón especificado por .masterId
• Ambas propiedades son cadenas de una de las tres formas posibles: nnnnnnnnnnn#, #mmmmmmmmm o nnnnnnnnnnn#mmmmmmmmm, donde nnnnnnnnnnnnn es el identificador del patrón o diseño (normalmente 10 dígitos) y mmmmmmmmm es el identificador de creación del patrón o diseño (normalmente de 6 a 10 dígitos). Algunos ejemplos son 2147483690#2908289500, 2147483690#y #2908289500.

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

No hay ninguna manera práctica de que los usuarios puedan detectar el identificador o el identificador de creación de un patrón de diapositivas o diseño. Por este motivo, solo puede usar el AddSlideOptions parámetro cuando conozca los identificadores en tiempo de codificación o el complemento pueda detectarlos en tiempo de ejecución. Dado que no se puede esperar que los usuarios memorizan los identificadores, también necesita una manera de permitir que el usuario seleccione diapositivas, quizás por nombre o por una imagen, y luego correlacionar cada título o imagen con el identificador de la diapositiva.

En consecuencia, el AddSlideOptions parámetro se usa principalmente en escenarios en los que el complemento está diseñado para trabajar con un conjunto específico de patrones y diseños de diapositivas cuyos identificadores se conocen. En este escenario, usted o el cliente deben crear y mantener un origen de datos que correlacione un criterio de selección (como el patrón de diapositivas y los nombres de diseño o imágenes) con los identificadores o identificadores de creación correspondientes.

Hacer que el usuario elija una diapositiva coincidente

Si el complemento se puede usar en escenarios en los que la nueva diapositiva debe usar la misma combinación de patrón de diapositivas y diseño que usa una diapositiva existente , el complemento puede (1) pedir al usuario que seleccione una diapositiva y (2) leer los identificadores del patrón de diapositivas y el diseño. En los pasos siguientes se muestra cómo leer los identificadores y agregar una diapositiva con un patrón y un diseño coincidentes.

1. Cree una función para obtener el índice de la diapositiva seleccionada. A continuación se muestra un ejemplo. Sobre este código, tenga en cuenta:

   • Usa el método Office.context.document.getSelectedDataAsync de las API comunes de JavaScript.
   • La llamada a getSelectedDataAsync se inserta en una función de devolución de promesa. Para obtener más información sobre por qué y cómo hacerlo, vea Encapsular las API comunes en funciones que devuelven promesas.
   • getSelectedDataAsync devuelve una matriz porque se pueden seleccionar varias diapositivas. En este escenario, el usuario ha seleccionado solo una, por lo que el código obtiene la primera (0ª) diapositiva, que es la única seleccionada.
   • El index valor de la diapositiva es el valor basado en 1 que el usuario ve junto a la diapositiva en el panel miniaturas.

   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. Llame a la nueva función dentro de PowerPoint.run() de la función principal que agrega la diapositiva. A continuación se muestra un ejemplo.

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

Eliminar diapositivas

Elimine una diapositiva obteniendo una referencia al objeto Slide que representa la diapositiva y llame al Slide.delete método . A continuación se muestra un ejemplo en el que se elimina la 4ª diapositiva.

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