Insertar diapositivas en una presentación de PowerPoint

  • Artículo

Un complemento de PowerPoint puede insertar diapositivas de una presentación en la presentación actual mediante la biblioteca de JavaScript específica de la aplicación de PowerPoint. Puede controlar si las diapositivas insertadas mantienen el formato de la presentación de origen o el formato de la presentación de destino.

Las API de inserción de diapositivas se usan principalmente en escenarios de plantilla de presentación: hay un pequeño número de presentaciones conocidas que sirven como grupos de diapositivas que el complemento puede insertar. En este escenario, usted o el cliente deben crear y mantener un origen de datos que correlacione el criterio de selección (como títulos de diapositivas o imágenes) con identificadores de diapositivas. Las API también se pueden usar en escenarios en los que el usuario puede insertar diapositivas de cualquier presentación arbitraria, pero en ese escenario el usuario se limita eficazmente a insertar todas las diapositivas de la presentación de origen. Consulte Selección de las diapositivas que se van a insertar para obtener más información sobre esto.

Hay dos pasos para insertar diapositivas de una presentación en otra.

  1. Convierta el archivo de presentación de origen (.pptx) en una cadena con formato base64.
  2. Use el insertSlidesFromBase64 método para insertar una o varias diapositivas del archivo base64 en la presentación actual.

Convertir la presentación de origen en base64

Hay muchas maneras de convertir un archivo en base64. El escenario determina qué lenguaje de programación y biblioteca se usan y si se va a convertir en el lado servidor del complemento o en el lado cliente. Normalmente, la conversión se realiza en JavaScript en el lado cliente mediante un objeto FileReader . En el ejemplo siguiente se muestra esta práctica.

  1. Empiece por obtener una referencia al archivo de PowerPoint de origen. En este ejemplo, usaremos un <input> control de tipo file para pedir al usuario que elija un archivo. Agregue el marcado siguiente a la página del complemento.

    <section>
    <p>Select a PowerPoint presentation from which to insert slides</p>
    <form>
        <input type="file" id="file" />
    </form>
</section>

    Este marcado agrega la interfaz de usuario en la captura de pantalla siguiente a la página.

    Un control de entrada de tipo de archivo HTML precedido por una oración de instrucciones que lee

    Nota:

    Hay muchas otras maneras de obtener un archivo de PowerPoint. Por ejemplo, si el archivo se almacena en OneDrive o SharePoint, puede usar Microsoft Graph para descargarlo. Para obtener más información, vea Trabajar con archivos en Microsoft Graph y Access Files con Microsoft Graph.

  2. Agregue el código siguiente al JavaScript del complemento para asignar una función al evento del control de change entrada. (La función se storeFileAsBase64 crea en el paso siguiente).

    $("#file").on("change", storeFileAsBase64);

  3. Agregue el siguiente código. Tenga en cuenta lo siguiente sobre este código.

    • El reader.readAsDataURL método convierte el archivo en base64 y lo almacena en la reader.result propiedad . Cuando el método se completa, desencadena el controlador de onload eventos.
    • El onload controlador de eventos recorta los metadatos del archivo codificado y almacena la cadena codificada en una variable global.
    • La cadena codificada en base64 se almacena globalmente porque la leerá otra función que cree en un paso posterior.
    let chosenFileBase64;

async function storeFileAsBase64() {
    const reader = new FileReader();

    reader.onload = async (event) => {
        const startIndex = reader.result.toString().indexOf("base64,");
        const copyBase64 = reader.result.toString().substr(startIndex + 7);

        chosenFileBase64 = copyBase64;
    };

    const myFile = document.getElementById("file") as HTMLInputElement;
    reader.readAsDataURL(myFile.files[0]);
}

Insertar diapositivas con insertSlidesFromBase64

El complemento inserta diapositivas de otra presentación de PowerPoint en la presentación actual con el método Presentation.insertSlidesFromBase64 . A continuación se muestra un ejemplo sencillo en el que todas las diapositivas de la presentación de origen se insertan al principio de la presentación actual y las diapositivas insertadas mantienen el formato del archivo de origen. Tenga en cuenta que chosenFileBase64 es una variable global que contiene una versión codificada en base64 de un archivo de presentación de PowerPoint.

async function insertAllSlides() {
  await PowerPoint.run(async function(context) {
    context.presentation.insertSlidesFromBase64(chosenFileBase64);
    await context.sync();
  });
}

Puede controlar algunos aspectos del resultado de inserción, como dónde se insertan las diapositivas y si obtienen el formato de origen o de destino, pasando un objeto InsertSlideOptions como segundo parámetro a insertSlidesFromBase64. A continuación se muestra un ejemplo. Sobre este código, tenga en cuenta:

  • Hay dos valores posibles para la formatting propiedad: "UseDestinationTheme" y "KeepSourceFormatting". Opcionalmente, puede usar la InsertSlideFormatting enumeración (por ejemplo, PowerPoint.InsertSlideFormatting.useDestinationTheme).
  • La función insertará las diapositivas de la presentación de origen inmediatamente después de la diapositiva especificada por la targetSlideId propiedad . El valor de esta propiedad es una cadena de una de las tres formas posibles: nnn#, #mmmmmmmmm o nnn#mmmmmmmmm, donde nnn es el identificador de la diapositiva (normalmente 3 dígitos) y mmmmmmmmm es el identificador de creación de la diapositiva (normalmente 9 dígitos). Algunos ejemplos son 267#763315295, 267#y #763315295.
async function insertSlidesDestinationFormatting() {
  await PowerPoint.run(async function(context) {
    context.presentation
    .insertSlidesFromBase64(chosenFileBase64,
                            {
                                formatting: "UseDestinationTheme",
                                targetSlideId: "267#"
                            }
                          );
    await context.sync();
  });
}

Por supuesto, normalmente no sabrá en el momento de la codificación el identificador o el identificador de creación de la diapositiva de destino. Más comúnmente, un complemento pedirá a los usuarios que seleccionen la diapositiva de destino. En los pasos siguientes se muestra cómo obtener el identificador nnn# de la diapositiva seleccionada actualmente y cómo usarla como diapositiva de destino.

  1. Cree una función que obtenga el identificador de la diapositiva seleccionada actualmente mediante el método Office.context.document.getSelectedDataAsync de las API de JavaScript comunes. A continuación se muestra un ejemplo. Tenga en cuenta que la llamada a getSelectedDataAsync está incrustada en una función de devolución de promesa. Para obtener más información sobre por qué y cómo hacerlo, vea Encapsular Common-APIs en funciones que devuelven promesas.

    function getSelectedSlideID() {
  return new OfficeExtension.Promise<string>(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].id);
        }
      }
      catch (error) {
        reject(console.log(error));
      }
    });
  })
}

  2. Llame a la nueva función dentro de PowerPoint.run() de la función principal y pase el identificador que devuelve (concatenado con el símbolo "#") como valor de la targetSlideId propiedad del InsertSlideOptions parámetro . A continuación se muestra un ejemplo.

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

        const selectedSlideID = await getSelectedSlideID();

        context.presentation.insertSlidesFromBase64(chosenFileBase64, {
            formatting: "UseDestinationTheme",
            targetSlideId: selectedSlideID + "#"
        });

        await context.sync();
    });
}

Selección de las diapositivas que se van a insertar

También puede usar el parámetro InsertSlideOptions para controlar qué diapositivas de la presentación de origen se insertan. Para ello, asigne una matriz de los identificadores de diapositivas de la presentación de origen a la sourceSlideIds propiedad . A continuación se muestra un ejemplo en el que se insertan cuatro diapositivas. Tenga en cuenta que cada cadena de la matriz debe seguir uno u otro de los patrones usados para la targetSlideId propiedad .

async function insertAfterSelectedSlide() {
    await PowerPoint.run(async function(context) {
        const selectedSlideID = await getSelectedSlideID();
        context.presentation.insertSlidesFromBase64(chosenFileBase64, {
            formatting: "UseDestinationTheme",
            targetSlideId: selectedSlideID + "#",
            sourceSlideIds: ["267#763315295", "256#", "#926310875", "1270#"]
        });

        await context.sync();
    });
}

Nota:

Las diapositivas se insertarán en el mismo orden relativo en el que aparecen en la presentación de origen, independientemente del orden en que aparezcan en la matriz.

No hay ninguna manera práctica de que los usuarios puedan detectar el identificador o el identificador de creación de una diapositiva en la presentación de origen. Por este motivo, solo puede usar la sourceSlideIds propiedad cuando conozca los identificadores de origen en el momento de la codificación o el complemento pueda recuperarlos en tiempo de ejecución desde algún origen de datos. Dado que no se puede esperar que los usuarios memorizan los identificadores de diapositivas, también necesita una manera de permitir que el usuario seleccione diapositivas, quizás por título o por imagen, y luego correlacionar cada título o imagen con el identificador de la diapositiva.

En consecuencia, la sourceSlideIds propiedad se usa principalmente en escenarios de plantilla de presentación: el complemento está diseñado para trabajar con un conjunto específico de presentaciones que sirven como grupos de diapositivas que se pueden insertar. En este escenario, usted o el cliente deben crear y mantener un origen de datos que correlacione un criterio de selección (como títulos o imágenes) con identificadores de diapositivas o identificadores de creación de diapositivas que se hayan construido a partir del conjunto de presentaciones de origen posibles.