Trabajar con Eventos mediante la API de JavaScript de Excel

  • Artículo

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.

Evento Descripción Objetos admitidos
onActivated Se produce cuando se activa un objeto. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onActivated Se produce cuando se activa un libro. Workbook
onAdded Se produce cuando se agrega un objeto a la colección. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onAutoSaveSettingChanged Se produce cuando se cambia la configuración de autoSave en el libro. Workbook
onCalculated Se produce cuando una hoja de cálculo ha terminado el cálculo (o todas las hojas de cálculo de la colección han terminado). Worksheet, WorksheetCollection
onChanged Se produce cuando los datos de celdas o comentarios individuales han cambiado. CommentCollection, Table, TableCollection, Worksheet, WorksheetCollection
onColumnSorted Se produce cuando se han ordenado una o más columnas. Esto sucede cuando se produce una operación de ordenación de izquierda a derecha. Hoja de cálculo, WorksheetCollection
onDataChanged Se produce al cambiar los datos del enlace o al darles formato. Binding
onDeactivated Se produce cuando se desactiva un objeto. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onDeleted Se produce cuando se borra un objeto de la colección. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onFormatChanged Se produce cuando se cambia el formato de una hoja de cálculo. Hoja de cálculo, WorksheetCollection
onFormulaChanged Se produce cuando se cambia una fórmula. Hoja de cálculo, WorksheetCollection
onMoved Se produce cuando una hoja de cálculo se mueve dentro de un libro. WorksheetCollection
onNameChanged Se produce cuando se cambia el nombre de la hoja de cálculo. Hoja de cálculo, WorksheetCollection
onProtectionChanged Se produce cuando se cambia el estado de protección de la hoja de cálculo. Hoja de cálculo, WorksheetCollection
onRowHiddenChanged Se produce cuando cambia el estado oculto de fila en una hoja de cálculo específica. Hoja de cálculo, WorksheetCollection
onRowSorted Se produce cuando se han ordenado una o más filas. Esto sucede cuando se produce una operación de ordenación de arriba a abajo. Hoja de cálculo, WorksheetCollection
onSelectionChanged Se produce cuando se cambia la celda activa o el rango seleccionado. Binding, Table, Workbook, Worksheet, WorksheetCollection
onSettingsChanged Se produce al cambiar la configuración del documento. SettingCollection
onSingleClicked Se produce cuando se pulsa o se hace clic izquierdo en la hoja de cálculo. Hoja de cálculo, WorksheetCollection
onVisibilityChanged Se produce cuando se cambia la visibilidad de la hoja de cálculo. Hoja de cálculo, WorksheetCollection

Eventos en la versión preliminar

Nota:

Los siguientes eventos solo están disponibles actualmente en la versión preliminar pública. Para usar esta característica, debe usar la versión preliminar de la biblioteca de API de JavaScript de Office desde la red de entrega de contenido (CDN) deOffice.js. El tipo de archivo de definición para la compilación TypeScript e IntelliSense se encuentra en la CDN y DefinitelyTyped. Puede instalar estos tipos con npm install --save-dev @types/office-js-preview. Para obtener más información sobre las próximas API, visite Conjuntos de requisitos de API de JavaScript de Excel.

Evento Descripción Objetos admitidos
onFiltered Se produce cuando se aplica el filtro en un objeto. Tabla, TableCollection, Hoja de cálculo, WorksheetCollection

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 activará 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.

Precaución

Al eliminar un objeto en el que se registran los eventos (por ejemplo, una tabla con un evento registrado onChanged), el controlador de eventos ya no se desencadena, pero permanece en la memoria hasta que el complemento o la sesión de Excel se actualiza o se cierra.

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() {
  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