可将 Office 加载项配置为在打开文档后立即加载并运行代码。 如果需要注册事件处理程序、为任务窗格预加载数据、同步 UI 或在加载项可见之前执行其他任务，这将非常有用。
提示
本文介绍了一种功能，该功能允许加载项以编程方式将自身配置为在文档打开时运行代码。 该技术具有 文档范围，这意味着它必须单独应用于每个文档。 此功能不同于三个类似功能：
- 可以在清单中配置加载项，以便在 任何 文档打开时运行代码。 此功能具有 Office 应用程序范围。 Microsoft 365 管理员在 Microsoft 365 租户的管理员门户中安装加载项后，该加载项将在清单中配置该加载项以支持的 Office 应用程序中打开的每个 Office 文档上启动并运行代码。 有关详细信息，请参阅 使用事件激活加载项，尤其是有关
OnDocumentOpened事件的信息。 - 加载项可以以编程方式将文档配置为在文档打开时自动打开加载项的任务窗格。 此功能还必须单独应用于每个文档。 有关详细信息，请参阅 自动打开包含文档的任务窗格。
- 可以在清单中配置加载项，以便在最终用户 安装加载项时 打开其任务窗格。 此功能的范围限于 单个文档：安装加载项时打开的文档。 有关详细信息，请参阅 安装加载项时自动打开任务窗格。
该配置是使用代码在运行时调用的方法实现的。 这意味着加载项 不会 在用户首次打开文档 时 运行。 加载项必须在任何文档上首次手动打开。 该方法运行后，无论是在 Office.initialize、Office.onReady 中，还是因为用户采用了运行它的代码路径;然后，只要重新打开文档，加载项就会立即加载，并且 OR Office.onReady 方法中Office.initialize的任何代码都会运行。
注意
本文要求将 Office 加载项配置为使用 共享运行时。 有关详细信息，请参阅 配置 Office 加载项以使用共享运行时。
重要
共享运行时仅在某些 Office 应用程序中受支持。 有关详细信息，请参阅共享运行时要求集。
将加载项配置为在文档打开时加载
以下代码将加载项配置为在打开文档时加载并开始运行。
Office.addin.setStartupBehavior(Office.StartupBehavior.load);
注意
该 setStartupBehavior 方法是异步的。
将启动代码放入 Office.initialize 或 Office.onReady 中
将加载项配置为在文档打开时加载时，它将立即运行。
Office.initialize将调用事件处理程序。 将启动代码放在 or Office.onReady 事件处理程序中Office.initialize。
下面的 Excel 加载项代码显示如何为活动工作表中的更改事件注册事件处理程序。 如果将加载项配置为在文档打开时加载，则此代码将在文档打开时注册事件处理程序。 可以在打开任务窗格之前处理更改事件。
// This is called as soon as the document opens.
// Put your startup code here.
Office.initialize = () => {
// Add the event handler.
Excel.run(async context => {
let sheet = context.workbook.worksheets.getActiveWorksheet();
sheet.onChanged.add(onChange);
await context.sync();
console.log("A handler has been registered for the onChanged event.");
});
};
/**
* Handle the changed event from the worksheet.
*
* @param event The event information from Excel
*/
async function onChange(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);
});
}
下面的 PowerPoint 加载项代码显示如何为 PowerPoint 文档中的选择更改事件注册事件处理事件处理程序。 如果将加载项配置为在文档打开时加载，则此代码将在文档打开时注册事件处理程序。 可以在打开任务窗格之前处理更改事件。
// This is called as soon as the document opens.
// Put your startup code here.
Office.onReady(info => {
if (info.host === Office.HostType.PowerPoint) {
Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, onChange);
console.log("A handler has been registered for the onChanged event.");
}
});
/**
* Handle the changed event from the PowerPoint document.
*
* @param event The event information from PowerPoint
*/
async function onChange(event) {
console.log("Change type of event: " + event.type);
}
将加载项配置为文档打开时的空加载行为
在某些情况下，可能需要关闭“打开文档时运行”行为。 以下代码将加载项配置为在文档打开时不启动。 而是在用户以某种方式参与时启动，例如选择功能区按钮或打开任务窗格。 如果之前未在当前文档上调用过该方法，则此代码无效，并将 用作 Office.StartupBehavior.load 参数。
注意
如果加载项调用该方法，则 Office.StartupBehavior.load 该方法作为参数 in 或 Office.initializeOffice.onReady，则会再次打开该行为。 因此，在这种情况下，将其关闭仅适用于 下次 打开文档时，而不适用于 所有 后续打开。
Office.addin.setStartupBehavior(Office.StartupBehavior.none);
获取当前加载行为
在某些情况下，加载项可能需要知道是否配置为在下次打开当前文档时自动启动。 若要确定当前的启动行为，请运行以下方法，该方法返回 Office.StartupBehavior 值。
let behavior = await Office.addin.getStartupBehavior();