使用 Excel JavaScript API 处理事件

项目
05/24/2023

本文介绍了与处理 Excel 中事件相关的重要概念，并提供了代码示例，以展示如何使用 Excel JavaScript API 注册事件处理程序、处理事件和删除事件处理程序。

Excel 中的事件

每当 Excel 工作簿中出现某种类型的更改时，就会触发事件通知。使用 Excel JavaScript API，可以注册事件处理程序，以便加载项能够在发生特定事件时自动运行指定的函数。下列事件暂不受支持。

事件	说明	支持的对象
`onActivated`	激活对象时发生。	Chart、ChartCollection、Shape、Worksheet、WorksheetCollection
`onActivated`	激活工作簿时发生。	Workbook
`onAdded`	当向集合中添加对象时发生。	ChartCollection、 CommentCollection、 TableCollection、 WorksheetCollection
`onAutoSaveSettingChanged`	在工作簿上更改 `autoSave` 设置时发生。	Workbook
`onCalculated`	工作表完成计算（或集合的所有工作表都已完成）时发生。	Worksheet、WorksheetCollection
`onChanged`	当单个单元格或注释的数据已更改时发生。	CommentCollection、 Table、 TableCollection、 Worksheet、 WorksheetCollection
`onColumnSorted`	在已对一个或多个列进行排序时发生。这是从左到右排序操作的结果。	Worksheet、WorksheetCollection
`onDataChanged`	当绑定内的数据或格式变化时发生。	Binding
`onDeactivated`	停用对象时发生。	Chart、ChartCollection、Shape、Worksheet、WorksheetCollection
`onDeleted`	当从集合中删除对象时发生。	ChartCollection、 CommentCollection、 TableCollection、 WorksheetCollection
`onFormatChanged`	在工作表上的格式变化时发生。	Worksheet、WorksheetCollection
`onFormulaChanged`	更改公式时发生。	Worksheet、WorksheetCollection
`onMoved`	在工作簿中移动工作表时发生。	WorksheetCollection
`onNameChanged`	更改工作表名称时发生。	Worksheet、WorksheetCollection
`onProtectionChanged`	更改工作表保护状态时发生。	Worksheet、WorksheetCollection
`onRowHiddenChanged`	在特定工作表上的行隐藏状态更改时发生。	Worksheet、WorksheetCollection
`onRowSorted`	在已对一个或多个行进行排序时发生。这是从上到下排序操作的结果。	Worksheet、WorksheetCollection
`onSelectionChanged`	当活动单元格或选定范围更改时发生。	绑定、表、工作簿、工作表、 WorksheetCollection
`onSettingsChanged`	当文档中的设置变化时发生。	SettingCollection
`onSingleClicked`	在工作表中进行左键单击/点击操作时发生。	Worksheet、WorksheetCollection
`onVisibilityChanged`	在更改工作表可见性时发生。	Worksheet、WorksheetCollection

预览版中的事件

注意

以下事件当前仅适用于公共预览版。若要使用此功能，必须使用Office.js 内容分发网络 (CDN) 的 Office JavaScript API 库的预览版本。用于 TypeScript 编译和 IntelliSense 的类型定义文件位于 CDN 和 DefinitelyTyped 中。可以使用 npm install --save-dev @types/office-js-preview 来安装这些类型。要详细了解即将推出的 API，请访问 Excel JavaScript API 要求集。

事件	说明	支持的对象
`onFiltered`	当将筛选器应用于对象时发生。	Table、TableCollection、Worksheet、WorksheetCollection

事件触发器

Excel 工作簿内的事件可以通过下列方式触发：

更改工作簿的 Excel 用户界面 (UI) 用户交互
更改工作簿的 Office 加载项 (JavaScript) 代码
更改工作簿的 VBA 加载项（宏）代码

任何符合 Excel 默认行为的更改都会在工作簿中触发一个或多个相应事件。

事件处理程序的生命周期

当加载项注册事件处理程序时，将创建事件处理程序。当加载项取消注册事件处理程序或者刷新、重新加载或关闭加载项时，将销毁事件处理程序。事件处理程序不会暂留为 Excel 文件的一部分，也不会跨与 Excel 网页版的会话保留。

警告

删除了注册事件的对象（例如，注册 onChanged 事件的表）时，事件处理程序不再触发但会保留在内存中，直到加载项或 Excel 会话刷新或关闭为止。

事件和共同创作

借助共同创作功能，多个人可以共同协作，同时编辑同一个 Excel 工作簿。对于可由共同创作者触发的事件（如 onChanged），相应的 Event 对象会包含 source 属性，以指示事件是由当前用户在本地触发 (event.source = Local)，还是由远程共同创作者触发 (event.source = Remote)。

注册事件处理程序

下面的代码示例为 Sample 工作表中的 onChanged 事件注册事件处理程序。此代码指定 handleChange 函数应在工作表中的数据有变化时运行。

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

处理事件

如上一示例所示，注册事件处理程序时，指定函数应在指定事件发生时运行。可以将函数设计为执行方案所需的任何操作。下面的代码示例展示了事件处理程序函数如何直接将事件信息写入控制台。

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

删除事件处理程序

下面的代码示例为 Sample 工作表中的 onSelectionChanged 事件注册事件处理程序，并将 handleSelectionChange 函数定义为在事件发生时运行。它还定义了随后可以调用的 remove() 函数，以删除相应事件处理程序。请注意， RequestContext 需要用于创建事件处理程序的来删除它。

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

启用和禁用事件

可以通过禁用事件来改进加载项性能。例如，你的应用可能永远不需要接收事件，也可能在执行多个实体的批量编辑时忽略事件。

启用和禁用事件是在运行时级别进行的。 enableEvents 属性确定是否触发事件并激活其处理程序。

以下代码示例展示了如何打开和关闭事件。

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

另请参阅

Excel 加载项中的 Word JavaScript 对象模型