Enlace a formas en una presentación de PowerPoint

El complemento de PowerPoint puede enlazarse a formas para acceder a ellas de forma coherente a través de un identificador. El complemento establece un enlace llamando a BindingCollection.add y asignando un identificador único. Use el identificador en cualquier momento para hacer referencia a la forma y acceder a sus propiedades. La creación de enlaces proporciona el siguiente valor al complemento.

• Establece una relación entre el complemento y la forma del documento. Los enlaces se conservan en el documento y se puede acceder a él más adelante.
• Permite el acceso a las propiedades de formas para leer o actualizar, sin necesidad de que el usuario seleccione ninguna forma.

En la imagen siguiente se muestra cómo un complemento podría enlazarse a dos formas en una diapositiva. Cada forma tiene un identificador de enlace creado por el complemento: star y pie. Con el identificador de enlace, el complemento puede acceder a la forma deseada para actualizar las propiedades.

Escenario: Uso de enlaces para sincronizar con un origen de datos

Un escenario común para usar enlaces es mantener las formas actualizadas con un origen de datos. A menudo, al crear una presentación, los usuarios copian y pegan imágenes del origen de datos en la presentación. Con el tiempo, para mantener actualizadas las imágenes, copiarán y pegarán manualmente las imágenes más recientes del origen de datos. Un complemento puede ayudar a automatizar este proceso mediante la recuperación de imágenes actualizadas del origen de datos en nombre del usuario. Cuando un relleno de forma necesita actualizarse, el complemento usa el enlace para buscar la forma correcta y actualizar el relleno de forma con la imagen más reciente.

En una implementación general, hay dos componentes que se deben tener en cuenta para enlazar una forma en PowerPoint y actualizarla con una nueva imagen de un origen de datos.

1. Origen de datos. Se trata de cualquier origen de datos o biblioteca de recursos, como Microsoft SharePoint o Microsoft OneDrive.
2. Complemento de PowerPoint. El complemento obtiene datos del origen de datos en función de lo que el usuario necesita. Convierte los datos en una imagen codificada en Base64. Este es el único tipo de relleno que la forma enlazada puede aceptar. Inserta una forma en la solicitud del usuario y la enlaza con un identificador único. A continuación, rellena la forma con la imagen Base64 basada en el origen de datos original. Las formas se actualizan según la solicitud del usuario y el complemento usa el identificador de enlace para buscar la forma y actualizar la imagen con la última imagen de Base64 guardada.

Creación de una forma enlazada en PowerPoint

Use el PowerPoint.BindingCollection.add() método de la presentación para crear un enlace que haga referencia a una forma determinada.

En el ejemplo siguiente se muestra cómo crear una forma en la primera diapositiva seleccionada.

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

Llame BindingCollection.add a para agregar el enlace a la colección de enlaces en PowerPoint. En el ejemplo siguiente se muestra cómo agregar un nuevo enlace para una forma a la colección de enlaces.

// Create a binding ID to track the shape for later updates. 
const bindingId = "productChart"; 
// Create binding by adding the new shape to the bindings collection. 
context.presentation.bindings.add(myShape, PowerPoint.BindingType.shape, bindingId); 

Actualizar una forma enlazada con datos actualizados

Una vez que haya una actualización en los datos de la imagen, actualice la imagen de forma; para ello, búsquela mediante el identificador de enlace. En el ejemplo de código siguiente se muestra cómo buscar una forma enlazada con el identificador y rellenarla con una imagen actualizada. El complemento actualiza la imagen en función de la solicitud del origen de datos o la proporciona directamente el origen de datos.

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

Eliminación de un enlace

En el ejemplo siguiente se muestra cómo eliminar un enlace de la colección de enlaces.

async function deleteBinding(bindingId) {
    await PowerPoint.run(async (context) => {
        context.presentation.bindings.getItemAt(bindingId).delete();
        await context.sync();
    });
}

Enlaces de carga

Cuando un usuario abre una presentación y el complemento se carga por primera vez, puede cargar todos los enlaces para seguir trabajando con ellos. En el código siguiente se muestra cómo cargar todos los enlaces de una presentación y mostrarlos en la consola.

async function loadBindings() {
    await PowerPoint.run(async (context) => {
        try {
            let myBindings = context.presentation.bindings;
            myBindings.load("items");
            await context.sync();

            // Log all binding IDs to console.
            if (myBindings.items.length > 0) {
                myBindings.items.forEach(async (binding) => {
                    console.log(binding.id);
                });
            }
        } catch (err) {
            console.error(err);
        }
    });
}

Control de errores cuando se elimina un enlace o una forma

Cuando se elimina una forma, su enlace asociado también se quita de la colección de enlaces de PowerPoint. Cualquier referencia de objeto que tenga al enlace o a la forma devolverá errores si tiene acceso a las propiedades o métodos de esos objetos. Asegúrese de controlar posibles escenarios de error para una forma eliminada si el complemento mantiene los objetos Binding o Shape.

El código siguiente muestra un enfoque para el control de errores cuando un objeto de enlace hace referencia a un enlace eliminado. Use una instrucción try/catch y, a continuación, llame a una función para volver a cargar todas las referencias de enlace y forma cuando se produzca un error.

async function getShapeFromBindingID(id) {
    await PowerPoint.run(async (context) => {
        try {
            const binding = context.presentation.bindings.getItemAt(id);
            const shape = binding.getShape();

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

Vea también

Al mantener la actualización en las formas, también puede que desee comprobar el zOrder. Vea la propiedad zOrderPosition para obtener más información.

• Trabajar con formas mediante la API de JavaScript de PowerPoint
• Enlazar a regiones de un documento u hoja de cálculo