Office 加载项中的运行时

Office 加载项在 Office 中嵌入的运行时中执行。 作为解释语言，JavaScript 必须在 JavaScript 运行时中运行。 Node.js 和新式浏览器就是此类运行时的示例。

运行时类型

Office 加载项使用两种类型的运行时：

• 仅限 JavaScript 的运行时：一个 JavaScript 引擎，支持 WebSocket、 完整 CORS (跨源资源共享) 和客户端存储数据。 它不支持 本地存储 或 Cookie。
• 浏览器运行时：包括仅 JavaScript 运行时的所有功能，并添加了对 本地存储、呈现 HTML 的 呈现引擎 和 Cookie 的支持。

有关这些类型的详细信息，请参阅本文后面的 仅限 JavaScript 运行时 和 浏览器运行时。

下表显示了加载项的哪些可能功能使用每种类型的运行时。

运行时类型	加载项功能
仅限 JavaScript	Excel 自定义函数 (，除非共享运行时或外接程序在 Office web 版) 基于 outlook 事件的任务 中运行， (仅当外接程序在 Windows 上的 Outlook 中运行) Outlook 集成垃圾邮件报告功能 (预览) (仅当加载项在 Outlook on Windows)
浏览器	任务窗格 对话 框 函数命令 当共享运行时或外接程序在基于 Office web 版) Outlook 事件的任务 中运行时 (Excel 自定义函数 ， (加载项在 Outlook on Mac 中运行时或Outlook 网页版) Outlook 集成垃圾邮件报告功能 (预览) 仅当加载项在 Outlook on Mac 或 Web 上或在新的 Outlook on Windows (预览中运行时 () )

下表显示了用于加载项的各种可能功能的运行时类型的相同信息。

加载项功能	Windows 上的运行时类型	Mac 上的运行时类型	Web 上的运行时类型
Excel 自定义函数	仅 JavaScript (，但在 共享运行时时浏览器)	仅 JavaScript (，但在 共享运行时时浏览器)	浏览器
Outlook 基于事件的任务	仅限 JavaScript (经典 Outlook on Windows) 浏览器 (新的 Outlook on Windows (预览版) )	浏览器	浏览器
Outlook 集成垃圾邮件报告功能 (预览)	仅限 JavaScript (经典 Outlook on Windows) 浏览器 (新的 Outlook on Windows (预览版) )	浏览器	浏览器
任务窗格	浏览器	浏览器	浏览器
对话框	浏览器	浏览器	浏览器
函数命令	浏览器	浏览器	浏览器

在 Office web 版 中，所有内容始终在浏览器类型运行时中运行。 除了一个例外，Web 上的加载项中的所有内容都在同一个浏览器进程中运行：用户打开Office web 版的浏览器进程。 异常情况是，通过调用 Office.ui.displayDialogAsync 打开对话框，并且未传递 DialogOptions.displayInIFrame 选项并将其设置为 true。 当选项未 (因此具有默认值 false) 时，对话框将在其自己的进程中打开。 相同的原则适用于 OfficeRuntime.displayWebDialog 方法和 OfficeRuntime.DisplayWebDialogOptions.displayInIFrame 选项。

当加载项在 Web 以外的平台上运行时，以下原则适用。

• 对话在其自己的运行时进程中运行。

• 基于 Outlook 事件的加载项或垃圾邮件报告加载项在其自己的运行时进程中运行。

  注意

  Outlook 中 基于事件的激活 和 集成的垃圾邮件报告 功能必须使用相同的运行时。 Outlook 目前不支持多个运行时。

• 默认情况下，任务窗格、函数命令和 Excel 自定义函数都在其自己的运行时进程中运行。 但是，对于某些 Office 主机应用程序，可以配置外接程序清单，以便任何两个或所有三个都可以在同一运行时中运行。 请参阅 共享运行时。

根据主机 Office 应用程序和加载项中使用的功能，加载项中可能有许多运行时。 每个进程通常在其自己的进程中运行，但不一定同时运行。 示例如下。

• 不共享任何运行时且包含以下功能的 PowerPoint 或Word加载项具有多达三个运行时。

  • 任务窗格

  • 函数命令

  • 对话框 (可以从任务窗格或函数命令启动对话框。)

    注意

    同时打开多个对话框不是一种很好的做法，但如果加载项允许用户同时从任务窗格打开一个对话框，并从函数命令打开另一个对话框，则此加载项将具有四个运行时。 任务窗格和函数命令的给定调用一次只能有一个打开的对话;但是，如果多次调用函数命令，则每次调用都会在其前置任务顶部打开一个新对话框，因此可能会有许多运行时。 此列表的其余部分忽略了多个打开对话框的可能性。

• 不共享任何运行时且包含以下功能的 Excel 加载项具有多达 四 个运行时。

  • 任务窗格
  • 函数命令
  • 自定义函数
  • 对话框 (可以从任务窗格、函数命令或自定义函数启动对话框。)

• 具有相同功能的 Excel 外接程序（配置为跨任务窗格、函数命令和自定义函数共享同一运行时）具有 两个 运行时。 共享运行时一次只能打开一个对话框。

• 具有相同功能的 Excel 外接程序（除了没有对话框），并且配置为跨任务窗格、函数命令和自定义函数共享同一运行时外，具有 一个 运行时。

• 具有以下功能的 Outlook 外接程序具有多达 四 个运行时。 Outlook 不支持共享运行时。

  • 任务窗格
  • 函数命令
  • 基于事件的任务或集成的垃圾邮件报告功能
  • 对话框 (可以从任务窗格或函数命令启动对话框，但不能从基于事件的 task 启动。)

跨运行时共享数据

注意

• 如果您知道外接程序将仅用于 Office web 版并且它不会打开任何将 选项设置为 true的对话框displayInIFrame，则可以忽略此部分。 由于外接程序中的所有内容都在同一运行时进程中运行，因此只需使用全局变量在功能之间共享数据。
• 如上述 运行时类型中所述，功能使用的运行时类型在一定程度上因平台而异。 最好避免使用基于平台进行分支的外接程序代码，因此本节中的指导建议使用跨平台的技术。 下面只记录了一种需要分支代码的情况。

对于 Excel、PowerPoint 和 Word 加载项，当除对话框之外的任何两个或更多功能都需要共享数据时，请使用共享运行时。 在 Outlook 或共享运行时不可行的情况下，需要其他方法。 位于独立运行时进程中的外接程序部件不会自动共享全局数据，加载项的 Web 应用程序服务器会将这些部件视为单独的会话，因此 Window.sessionStorage 不能用于在它们之间共享数据。 以下指南假定你未使用共享运行时。

• 使用 Office.ui.messageParent 和 Dialog.messageChild 方法在对话与其父任务窗格、函数命令或自定义函数之间传递数据。

  注意

  OfficeRuntime.storage无法在对话中调用方法，因此这不是在对话与另一个运行时之间共享数据的选项。

• 若要在任务窗格和函数命令之间共享数据，请将数据存储在 Window.localStorage 中，该数据存储在访问同一特定 源的所有运行时之间共享。

  注意

  LocalStorage 在仅限 JavaScript 的运行时中不可访问，因此在 Excel 自定义函数中不可用。 它还不能用于与基于 Outlook 事件的任务共享数据 (因为这些任务在某些平台上使用仅限 JavaScript 的运行时) 。

  从基于 Chromium 的浏览器（例如 Chrome 和 Edge）的版本 115 开始，存储分区将进行测试，以防止特定侧通道跨站点跟踪 (另请参阅 Microsoft Edge 浏览器策略) 。 这意味着，存储 API 存储的数据（例如本地存储）仅适用于具有相同源和相同顶级站点的上下文。 若要解决此问题，请在浏览器中转到 chrome://flags 或 edge://flags，然后将 实验性第三方存储分区 (#third-party-storage-partitioning) 标志设置为 “已禁用”。

  提示

  中的数据在 Window.localStorage 外接程序的会话之间保留，并且由具有相同源的外接程序共享。 加载项通常不需要这两个特征。

  • 为确保给定外接程序的每个会话在加载项启动时重新启动，请调用 Window.localStorage.clear 方法。
  • 若要允许保留一些存储值，但重新初始化其他值，请在加载项启动时使用 Window.localStorage.setItem ，以便对应重置为初始值的每个项使用。
  • 若要完全删除项，请调用 Window.localStorage.removeItem。

• 若要在 Excel 自定义函数与任何其他运行时之间共享数据，请使用 OfficeRuntime.storage。

• 若要在基于 Outlook 事件的任务与任务窗格或函数命令之间共享数据，必须按 Office.context.platform 属性的值对代码进行分支。

  • 当该值 (PC Windows) 时，请使用 Office.sessionData API 存储和检索数据。
  • 如果值为 Mac，请使用 Window.localStorage ，如此列表中前面所述。

共享数据的其他方法包括：

• 将共享数据存储在可供所有运行时访问的联机数据库中。
• 将共享数据存储在加载项域的 Cookie 中，以便在浏览器运行时之间共享。 仅限 JavaScript 的运行时不支持 Cookie。

有关详细信息，请参阅 持久保存加载项状态和设置 和 获取和设置 Outlook 加载项的外接程序元数据。

仅限 JavaScript 的运行时

Office 外接程序中使用的仅限 JavaScript 运行时是最初为React Native创建的开放源代码运行时的修改。 它包含一个 JavaScript 引擎，该引擎对 WebSocket、 完整 CORS (跨源资源共享) 和 OfficeRuntime.storage 的支持进行了补充。 它没有呈现引擎，并且不支持 Cookie 或 本地存储。

此类型的运行时仅在 Outlook on Windows 和 Excel 自定义函数中基于事件的加载项和垃圾邮件报告加载项中使用， 自定义 函数 共享运行时除外。

• 当用于 Excel 自定义函数时，运行时会在工作表重新计算或自定义函数计算时启动。 在工作簿关闭之前，它不会关闭。

• 在 Outlook 基于事件或垃圾邮件报告加载项中使用时，运行时会在事件发生时启动。 当出现以下第一个情况时，它将结束。

  • 事件处理程序调用 completed 其事件参数的 方法。
  • 自触发事件以来已过去五分钟。
  • 用户从触发事件的窗口更改焦点，例如消息撰写窗口 (仅适用于基于事件的加载项) 。

  注意

  Outlook 中 基于事件的激活 和 集成的垃圾邮件报告 功能必须使用相同的运行时。 Outlook 目前不支持多个运行时。

仅 JavaScript 运行时比浏览器运行时使用的内存更少，启动速度更快，但功能较少。

重要

仅限 JavaScript 的运行时直接支持 JavaScript 的 ECMAScript 2016 标准，但可以使用更高版本的 JavaScript 或 TypeScript。 有关如何执行此操作的信息，请参阅 对最新版本的 JavaScript 的支持。

浏览器运行时

Office 外接程序使用不同的浏览器类型运行时，具体取决于运行 Office (Web、Mac 或 Windows) 的平台，以及 Windows 和 Office 的版本和内部版本。 例如，如果用户在 FireFox 浏览器中运行 Office web 版，则使用 Firefox 运行时。 如果用户在 Mac 上运行 Office，则使用 Safari 运行时。 如果用户在 Windows 上运行 Office，则 Edge 或 Internet Explorer 提供运行时，具体取决于 Windows 和 Office 的版本。 可在 Office 外接程序使用的浏览器和 Web 视图控件中找到详细信息。

所有这些运行时都包含 HTML 呈现引擎，并提供对 WebSocket、 完整 CORS (跨源资源共享) 、 本地存储和 Cookie 的支持。

浏览器运行时的生命周期因它实现的功能以及是否共享而有所不同。

• 启动具有任务窗格的加载项时，将启动浏览器运行时，除非它是已在运行的共享运行时。 如果是共享运行时，则会在文档关闭时关闭。 如果不是共享运行时，则会在关闭任务窗格时关闭。

• 打开对话框时，浏览器运行时将启动。 对话框关闭时，它会关闭。

• 执行函数命令 (当用户选择其按钮或菜单项) 时发生时，浏览器运行时将启动，除非它是已在运行的共享运行时。 如果是共享运行时，则会在文档关闭时关闭。 如果它不是共享运行时，则会在发生以下第一个操作时关闭。

  • 函数命令调用 completed 其事件参数的 方法。
  • 自触发事件以来已过去五分钟。 (如果在函数命令中打开了某个对话框，并且当父运行时超时时该对话框仍处于打开状态，则对话框运行时将一直保持运行状态，直到对话框关闭。)

• 当 Excel 自定义函数使用共享运行时时，当自定义函数计算共享运行时是否由于某种其他原因尚未启动时，浏览器类型的运行时将启动。 文档关闭时，它会关闭。

注意

共享运行时时，代码可以在不关闭加载项的情况下关闭任务窗格。 有关详细信息 ，请参阅显示或隐藏 Office 外接程序的任务窗格 。

与仅 JavaScript 运行时相比，浏览器运行时具有更多功能，但启动速度较慢，使用更多内存。

共享运行时

“共享运行时”不是一种运行时类型。 它是指由加载项的功能共享的 浏览器类型运行时 ，否则每个运行时都有自己的运行时。 具体而言，可以选择配置外接程序的任务窗格和函数命令来共享运行时。 在 Excel 外接程序中，还可以配置自定义函数以共享任务窗格或函数命令的运行时，或同时共享这两者。 执行此操作时，自定义函数在浏览器类型的运行时中运行，而不是 在其他情况下运行的仅限 JavaScript 的运行时 。 有关共享运行时的优点和限制的信息，以及配置外接程序以 使用共享运行时 的说明，请参阅配置外接程序以使用共享运行时。 简言之，仅限 JavaScript 的运行时使用的内存更少，启动速度更快，但功能较少。

注意

• 只能在 Excel、PowerPoint 和 Word 中共享运行时。
• 无法将对话框配置为共享运行时。 每个对话始终有自己的，除非在 Office web 版 中启动对话，displayInIFrame并将 选项设置为 true。
• 共享运行时从不使用原始 Microsoft Edge WebView (EdgeHTML) 运行时。 如果满足将 Microsoft Edge 与基于 WebView2 (Chromium 的) 配合使用的条件 (，如 Office 外接程序) 使用的浏览器和 Webview 控件中所述，则使用该运行时。 否则，将使用 Internet Explorer 11 运行时。