Share via

自定义函数的仅 JavaScript 运行时

  • 项目

不使用共享运行时的自定义函数使用 仅限 JavaScript 的运行时 ，该运行时旨在优化计算性能。

重要

请注意，以下平台上可以使用 Excel 自定义函数。

  • Office 网页版
  • Windows 版 Office
    • Microsoft 365 订阅
    • 零售永久 Office 2016 及更高版本
    • 批量许可永久Office 2021及更高版本
  • Mac 版 Office

以下各项当前不支持 Excel 自定义函数：

  • iPad 版 Office
  • Windows 上 Office 2019 或更早版本的批量许可永久版本

注意

建议对 共享运行时使用自定义函数，除非有特定原因不使用共享运行时。 请注意，使用共享运行时意味着，如果满足条件，外接程序将使用基于 Microsoft Edge Chromium 的 WebView2 () ，否则外接程序将使用 Trident (Internet Explorer 11) 而不考虑 Windows 或 Microsoft 365 版本。 有关 WebView2 条件的说明，请参阅 Office 外接程序使用的浏览器和 Webview 控件。有关运行时的详细信息，请参阅 Office 外接程序中的运行时 和 运行时。

此仅限 JavaScript 的运行时提供对命名空间中的 OfficeRuntime API 的访问权限，自定义函数和任务窗格 (这些 API 在不同的运行时) 中运行以存储数据。

请求外部数据

在自定义函数中，你可以使用 Fetch 等 API 或使用 XmlHttpRequest (XHR)（一种发出与服务器交互的 HTTP 请求的标准 Web API）来请求外部数据。

请注意，自定义函数在创建 XmlHttpRequests 时必须使用其他安全措施，需要 相同源策略 和简单的 CORS。

简单的 CORS 实现不能使用 Cookie，并且仅支持 (GET、HEAD、POST) 的简单方法。 简单的 CORS 接受字段名称为 Accept、Accept-Language、Content-Language 的简单标题。 还可以在简单 CORS 中使用 Content-Type 标头，前提是内容类型为 application/x-www-form-urlencoded、 text/plain或 multipart/form-data。

存储和访问数据

在不使用共享运行时的自定义函数中，可以使用 OfficeRuntime.storage 对象来存储和访问数据。 对象 Storage 是一个持久且未加密的键值存储系统，它提供 localStorage 的替代方法，而使用仅 JavaScript 运行时的自定义函数不能使用 localStorage。 对象 Storage 为每个域提供 10 MB 的数据。 域可以由多个加载项共享。

对象 Storage 是共享存储解决方案，这意味着外接程序的多个部分可以访问相同的数据。 例如，用户身份验证的令牌可能存储在 对象中 Storage ，因为自定义函数 (可以使用仅限 JavaScript 的运行时) 访问，而任务窗格 (使用完整的 Webview 运行时) 。 同样，如果两个外接程序共享同一个域 (例如 www.contoso.com/addin1、 www.contoso.com/addin2) ，则还允许它们通过 Storage 对象来回共享信息。 请注意，具有不同子域的外接程序将具有不同的 (实例Storage，例如 、 subdomain.contoso.com/addin1differentsubdomain.contoso.com/addin2) 。

由于对象 Storage 可以是共享位置，因此请务必认识到可以重写键值对。

以下方法可用于 Storage 对象。

  • getItem
  • getItems
  • setItem
  • setItems
  • removeItem
  • removeItems
  • getKeys

注意

没有方法可以清除所有信息 (，例如 clear) 。 相反，需要使用 removeItems 来一次性删除多个条目。

OfficeRuntime.storage 示例

下面的代码示例调用 方法， OfficeRuntime.storage.setItem 将键和值设置为 storage。

function StoreValue(key, value) {

  return OfficeRuntime.storage.setItem(key, value).then(function (result) {
      return "Success: Item with key '" + key + "' saved to storage.";
  }, function (error) {
      return "Error: Unable to save item with key '" + key + "' to storage. " + error;
  });
}

后续步骤

了解如何 调试自定义函数。

另请参阅