Enlazar y actualizar formas en una presentación de PowerPoint

Use enlaces de formas cuando el complemento necesite buscar y actualizar la misma forma más adelante, como actualizar un número desde un origen de datos externo.

Un enlace crea un identificador estable para una forma. El complemento puede usar ese identificador para volver a obtener la forma, actualizarla y controlar los casos en los que se eliminó la forma.

Los enlaces proporcionan dos ventajas clave:

• Establecen una relación entre el complemento y la forma del documento. El documento conserva los enlaces, por lo que puede acceder a ellos más adelante.
• Habilitan el acceso a las propiedades de forma 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. Mediante el identificador de enlace, el complemento puede acceder a la forma deseada para actualizar sus propiedades.

Escenario: Sincronización de formas con un origen de datos

Un escenario común es mantener actualizados los objetos visuales de presentación de un origen de datos. En lugar de reemplazar manualmente las imágenes, un complemento puede recuperar los datos más recientes, convertirlos en una imagen codificada en Base64 y actualizar la forma correcta mediante su identificador de enlace.

En una implementación general, considere dos componentes 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 BindingCollection.add para crear un enlace que haga referencia a una forma específica.

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

    await context.sync();
});

Llame BindingCollection.add a para agregar la forma a la colección de enlaces de PowerPoint. El ejemplo siguiente continúa desde el ejemplo anterior y agrega un nuevo enlace para myShape.

// Create a binding ID to track the shape for later updates.
const bindingId = "productChart";
// Create a binding by adding the 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.getItem(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 {
            const myBindings = context.presentation.bindings;
            myBindings.load("items");
            await context.sync();

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

Control de errores cuando se elimina un enlace o una forma

Al eliminar una forma, PowerPoint también quita su enlace asociado de la colección de enlaces. Cualquier referencia a ese enlace o forma puede producir un error al llamar a métodos o propiedades de acceso. Controle estos escenarios de error si el complemento almacena Binding u objetos 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.getItem(id);
            const shape = binding.getShape();

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

Vea también

Al mantener la frescura visual, es posible que también quiera comprobar la capa de formas mediante Shape.zOrderPosition.

• Creación y formato de formas en complementos de PowerPoint
• Modelo de objetos de JavaScript de PowerPoint en complementos de Office
• Crear el primer complemento de panel de tareas de PowerPoint
• Tutorial: Crear un complemento de panel de tareas de PowerPoint
• Enlazar a regiones de un documento u hoja de cálculo
• Referencia de la API de JavaScript de PowerPoint