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.
| 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 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.
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() {
// 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();
});