Trabajar con Eventos mediante la API de JavaScript de Excel

Este artículo describe conceptos importantes relacionados con el trabajo con eventos de Excel y proporciona ejemplos de código que muestran cómo registrar controladores de eventos, controlar eventos y quitar los controladores de eventos con la API de JavaScript de Excel.

Eventos de Excel

Cada vez que se suceden ciertos tipos de cambios en un libro de Excel, se activa una notificación de eventos. Con la API de JavaScript de Excel, puede registrar los controladores de eventos que permiten al complemento ejecutar automáticamente una función designada cuando se produce un evento específico. En este momento, los eventos siguientes son compatibles.

Eventos en la versión preliminar

Desencadenadores de eventos

Los eventos sin un libro de Excel se pueden desencadenar a través de:

• La interacción del usuario mediante la interfaz de usuario (IU) de Excel que cambia el libro
• El código del complemento (JavaScript) de Office que cambia el libro
• El código del complemento (macro) de VBA que cambia el libro

Cualquier cambio que cumpla con el comportamiento predeterminado de Excel desencadenará los eventos correspondientes en un libro.

Ciclo de vida de un controlador de eventos

El controlador de eventos se crea cuando un complemento un controlador de eventos. Se destruye cuando el complemento anula el controlador de eventos o cuando el complemento se actualiza, se vuelve a cargar o se cierra. Los controladores de eventos no permanecen como parte del archivo de Excel o en sesiones con Excel en la web.

Eventos y coautoría

Con la coautoría, varios usuarios pueden trabajar en colaboración y editar el mismo libro de Excel simultáneamente. Para los eventos que se pueden activar gracias a un coautor, como onChanged, el correspondiente objeto Event contendrá una propiedad source que indicará si el usuario actual ha activado el evento de forma local (event.source == Local) o lo ha activado un coautor remoto (event.source == Remote).

Registrar un controlador de eventos

El siguiente ejemplo de código registra un controlador de eventos para el evento onChanged en la hoja de cálculo denominada Ejemplo. El código especifica que, cuando los datos cambian en esa hoja de cálculo, la función handleChange debería ejecutarse.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    worksheet.onChanged.add(handleChange);

    await context.sync();
    console.log("Event handler successfully registered for onChanged event in the worksheet.");
}).catch(errorHandlerFunction);

Controlar un evento

Como se muestra en el ejemplo anterior, cuando registra un controlador de eventos, indica la función que debe ejecutarse cuando se produce el evento especificado. Puede diseñar esa función para realizar la acción que necesite el escenario. El ejemplo de código siguiente muestra una función de controlador de eventos que simplemente escribe información sobre el evento en la consola.

async function handleChange(event) {
    await Excel.run(async (context) => {
        await context.sync();        
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);       
    }).catch(errorHandlerFunction);
}

Eliminación de un controlador de eventos

El siguiente ejemplo de código registra un controlador de eventos para el evento onSelectionChanged en la hoja de cálculo denominada Ejemplo y define la función handleSelectionChange que se ejecutará cuando se produzca el evento. También define la función remove() a la que puede llamarse posteriormente para eliminar ese controlador de eventos. Tenga en RequestContext cuenta que el usado para crear el controlador de eventos es necesario para quitarlo.

let eventResult;

async function run() {
  await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    eventResult = worksheet.onSelectionChanged.add(handleSelectionChange);

    await context.sync();
    console.log("Event handler successfully registered for onSelectionChanged event in the worksheet.");
  });
}

async function handleSelectionChange(event) {
  await Excel.run(async (context) => {
    await context.sync();
    console.log("Address of current selection: " + event.address);
  });
}

async function remove() {
  // The `RequestContext` used to create the event handler is needed to remove it.
  // In this example, `eventContext` is being used to keep track of that context.
  await Excel.run(eventResult.context, async (context) => {
    eventResult.remove();
    await context.sync();
    
    eventResult = null;
    console.log("Event handler successfully removed.");
  });
}

Habilitar y deshabilitar eventos

El rendimiento de un complemento puede mejorar mediante la deshabilitación de eventos. Por ejemplo, la aplicación nunca podría necesitar recibir eventos o podría ignorarlos mientras realiza ediciones de lotes de varias entidades.

Los eventos se habilitan y deshabilitan a nivel de runtime. La propiedad enableEvents determina si se desencadenan eventos y si se activan sus controladores.

El ejemplo de código siguiente muestra cómo habilitar y deshabilitar eventos.

await Excel.run(async (context) => {
    context.runtime.load("enableEvents");
    await context.sync();

    let eventBoolean = !context.runtime.enableEvents;
    context.runtime.enableEvents = eventBoolean;
    if (eventBoolean) {
        console.log("Events are currently on.");
    } else {
        console.log("Events are currently off.");
    }
    
    await context.sync();
});

Vea también

• Modelo de objetos de JavaScript en Excel para Complementos de Office