Office 加载项中的运行时

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

运行时类型

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

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

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

下表根据每种运行时类型显示了加载项的可能功能。

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

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

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

在 Office 网页版中，所有内容始终在浏览器类型运行时中运行。 除了一个例外，Web 上的加载项中的所有内容都 在同 一个浏览器进程中运行：用户在 Web 上打开 Office 的浏览器进程。 异常情况是，通过调用 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 网页版中使用，并且它不会打开任何将选项设置为 true的对话框displayInIFrame，则可以忽略此部分。 由于外接程序中的所有内容都在同一运行时进程中运行，因此只需使用全局变量在功能之间共享数据。
• 如上述 运行时类型中所述，功能使用的运行时类型在一定程度上因平台而异。 最好避免使用基于平台进行分支的外接程序代码，因此本节中的指导建议使用跨平台的技术。 下面只记录了一种需要分支代码的情况。

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

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

  注意

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

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

  注意

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

  从 Chrome 和 Edge 等基于 Chromium 的浏览器版本 115 开始， 启用存储分区 以防止特定侧通道跨站点跟踪 (另请参阅 Microsoft Edge 浏览器策略) 。 这意味着，存储 API 存储的数据（例如本地存储）仅适用于具有相同源和相同顶级站点的上下文。

  提示

  中的数据在 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 或 本地存储。

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

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

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

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

  注意

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

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

重要

在 2403 (内部版本 16.0.17425.20000) Office 2021 之前的 Office for Windows 版本中，仅限 JavaScript 的运行时直接支持 ECMAScript 2016 标准 JavaScript。 但是，可以使用更高版本的 JavaScript 或 TypeScript。 有关如何执行此操作的信息，请参阅 对最新版本的 JavaScript 的支持。

浏览器运行时

Office 外接程序使用不同的浏览器类型运行时，具体取决于运行 Office (Web、Mac 或 Windows) 的平台，以及 Windows 和 Office 的版本和内部版本。 例如，如果用户在 FireFox 浏览器中在 Web 上运行 Office，则使用 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 中共享运行时。
• 无法将对话框配置为共享运行时。 每个对话始终有自己的，除非在 Web 上的 Office 中启动对话， displayInIFrame 并将 选项设置为 true。
• 共享运行时从不使用原始 Microsoft Edge WebView (EdgeHTML) 运行时。 如果满足将 Microsoft Edge 与 WebView2 配合使用的条件 (基于 Chromium 的) 满足 (Office 外接程序) 使用的浏览器和 Web 视图控件 中指定的条件，则使用该运行时。 否则，将使用 Internet Explorer 11 运行时。