通过

文档打开时在 Office 加载项中运行代码

  • 项目

重要

共享运行时仅在某些 Office 应用程序中受支持。 有关详细信息，请参阅共享运行时要求集。

你可以配置 Office 加载项，以在文档打开后立即加载和运行代码。 如果需要在加载项可见之前注册事件处理程序、预加载任务窗格的数据、同步 UI 或执行其他任务，这将非常有用。

注意

配置是使用代码在运行时调用的方法实现的。 这意味着外接程序 不会 在用户 第一次 打开文档时运行。 必须在任何文档上首次手动打开加载项。 在方法运行后，无论是在 Office.initialize、Office.onReady 中，还是因为用户采用运行它的代码路径;然后，每当重新打开文档时，外接程序将立即加载，或 Office.onReady 方法中的任何代码都会Office.initialize运行。

注意

本文要求将 Office 外接程序配置为使用 共享运行时。 有关详细信息，请参阅 将 Office 外接程序配置为使用共享运行时。

将外接程序配置为在文档打开时加载

以下代码将外接程序配置为在打开文档时加载并开始运行。

Office.addin.setStartupBehavior(Office.StartupBehavior.load);

注意

方法是 setStartupBehavior 异步的。

在 Office.initialize 或 Office.onReady 中放置启动代码

当外接程序配置为在文档打开时加载时，它将立即运行。 将 Office.initialize 调用事件处理程序。 将启动代码置于 或 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 或 为 参数Office.initializeOffice.onReady），则再次打开行为。 因此，在此方案中，关闭它仅适用于 下次 打开文档时，而不是 所有 后续打开。

Office.addin.setStartupBehavior(Office.StartupBehavior.none);

获取当前加载行为

在某些情况下，加载项可能需要知道它是否已配置为在下次打开当前文档时自动启动。 若要确定当前启动行为是什么，请运行以下方法，该方法返回 Office.StartupBehavior 值。

let behavior = await Office.addin.getStartupBehavior();

另请参阅