初始化 Office 加载项

  • 项目

Office 加载项通常使用启动逻辑执行以下操作：

  • 检查用户的 Office 版本是否支持代码调用的所有 Office API。

  • 确保存在某些项目，例如具有特定名称的工作表。

  • 提示用户在 Excel 中选择一些单元格，然后插入用这些所选值初始化的图表。

  • 建立绑定。

  • 使用 Office 对话框 API 提示用户输入默认加载项设置值。

但是，在加载库之前，Office 外接程序无法成功调用任何 Office JavaScript API。 本文介绍代码可以确保库已加载的两种方法。

  • 使用 Office.onReady()进行初始化。
  • 使用 Office.initialize进行初始化。

提示

建议使用 Office.onReady() 取代 Office.initialize。 尽管 Office.initialize 仍受支持，但 Office.onReady() 提供了更大的灵活性。 只能向 Office.initialize 分配一个处理程序，Office 基础结构仅调用一次处理程序。 可以在代码的不同位置调用 Office.onReady() ，并使用不同的回调。

有关这两种方法之间的差别信息，请参阅 Office.initialize 和 Office.onReady() 之间的主要差别。

有关初始化加载项时的事件顺序的更多详细信息，请参阅 加载 DOM 和运行时环境。

使用 Office.onReady() 进行初始化

Office.onReady() 是一个异步函数，它在检查是否加载 Office.js 库时返回 Promise 对象。 加载库时，它会将 Promise 解析为一个 对象，该对象指定具有 Office.HostType 枚举值的 Office 客户端应用程序 (Excel、 Word、 等 ) 具有 Office.PlatformType 枚举值的平台 (PC、 Mac、 OfficeOnline等 ) 。 如果在调用 Office.onReady() 时已加载库，则 Promise 将立即解析。

调用 Office.onReady() 的一种方法是向其传递回调函数。 下面是一个示例。

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

或者，可以将 then() 方法链接到 Office.onReady() 的调用，而不是传递回调。 例如，以下代码检查用户的 Excel 版本是否支持加载项可能调用的所有 API。

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

下面是在 TypeScript 中使用 async 和 await 关键字的相同示例。

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

如果使用其他包含其自己的初始化处理程序或测试的 JavaScript 框架，则 通常 应将这些框架置于 对 Office.onReady()的响应中。 例如，将按如下所示引用 JQuery 的$(document).ready() 方法：

Office.onReady(function() {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
});

但是，此做法存在例外情况。 例如，假设你想要在浏览器 (中打开加载项，而不是在 Office 应用程序中旁加载它) ，以便使用浏览器工具调试 UI。 在此方案中，一旦 Office.js 确定它正在 Office 主机应用程序外部运行，它将调用回调并解析主机和平台的承诺 null 。

另一个例外是，如果希望在加载加载项时进度指示器显示在任务窗格中。 在此方案中，代码应调用 jQuery ready 并使用其回调来呈现进度指示器。 然后，回调 Office.onReady 可以将进度指示器替换为最终 UI。

使用 Office.initialize 进行初始化

当 Office.js 库加载并准备好用于用户交互时将触发初始化事件。 可将处理程序分配到实现初始化逻辑的 Office.initialize。 以下是检查用户的 Excel 版本是否支持加载项可能调用的所有 API 的示例。

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

如果使用其他包含其自己的初始化处理程序或测试的 JavaScript 框架，则 这些框架通常 应放置在事件中 Office.initialize ， (前面 使用 Office.onReady () 部分中所述的异常也) 。 例如，将按如下所示引用 JQuery 的$(document).ready() 方法：

Office.initialize = function () {
    // Office is ready.
    $(document).ready(function () {
        // The document is ready.
    });
  };

对于任务窗格和内容加载项，Office.initialize 提供了其他 reason 参数。 此参数指定如何将加载项添加到当前文档。 可以使用此参数针对首次插入加载项时和加载项已存在于文档中时实施不同的逻辑。

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

有关详细信息，请参阅 Office.initialize 事件和 InitializationReason 枚举。

Office.initialize 和 Office.onReady 之间的主要差别

  • 可以仅将一个处理程序分配到 Office.initialize 并仅由 Office 基础结构调用一次，但可以在代码中的不同位置调用 Office.onReady() 并使用不同的回调。 例如，只要自定义脚本使用运行初始化逻辑的回调进行加载，代码就可以调用 Office.onReady()。代码还可以在任务窗格中设置一个按钮，其脚本会使用不同的回调调用 Office.onReady()。 如果是这样，则会在单击该按钮后运行第二个回调。

  • Office.initialize 事件将在 Office.js 初始化其本身的内部过程的末尾处触发。 并且它会在内部过程结束后立即触发。 如果将处理程序分配到事件所使用的代码在事件触发后执行的时间过长，则处理程序将不会运行。 例如，如果使用的是 WebPack 任务管理器，则在加载 Office.js 后但在加载自定义 JavaScript 前，它会配置加载项的主页以加载填充代码文件。 在脚本加载和分配处理程序时，初始化事件已经发生。 但是，调用 Office.onReady()永远不会“太晚” 。 如果初始化事件已经发生，则回调将立即运行。

注意

即使没有启动逻辑，也应在加载项 JavaScript 加载时调用 Office.onReady() 或将空函数分配到 Office.initialize。 某些 Office 应用程序和平台组合在发生其中一个任务窗格之前不会加载任务窗格。 以下示例显示了这两种方法。

Office.onReady();

Office.initialize = function () {};

调试初始化

有关调试 Office.initialize 和 Office.onReady() 函数的信息，请参阅 调试 initialize 和 onReady 函数。

另请参阅