Office 加载项清单

  • 项目

每个 Office 加载项都有一个清单。 有两种类型的清单：

  • XML 清单： 这是生产加载项当前支持的唯一清单类型。如名称所示，它是 XML 格式。 这种类型的清单不能用于将加载项与某些其他类型的 Teams 应用组合在一起的应用;即 Microsoft 365 平台的一些其他类型的扩展。
  • Microsoft 365 的统一清单： 这是一个 JSON 格式的清单，多年来一直用作 Teams 应用的清单。 目前仅支持外接程序作为预览版，并且仅在 Outlook for Windows 上支持它。 它不应与生产加载项一起使用。 当它正式发布时，使用此清单的加载项可以与单个应用中其他类型的 Teams 应用结合使用，该应用可作为一个单元整体安装。

本文的其余部分适用于这两种类型的清单。

提示

Office 外接程序的清单文件介绍了在最终用户安装外接程序并将其用于 Office 文档和应用程序时应如何激活加载项。

清单文件使 Office 外接程序能够执行以下操作：

  • 通过提供 ID、版本、说明、显示名称和默认区域设置进行自我描述。

  • 指定用于为加载项塑造品牌的图像，以及用于 Office 应用功能区中加载项命令的图标。

  • 指定外接程序如何与 Office 集成，包括任何自定义 UI，如外接程序创建的功能区按钮。

  • 指定内容外接程序请求的默认尺寸和 Outlook 外接程序请求的高度。

  • 声明 Office 外接程序所需的权限，例如读取或写入文档。

注意

如果你计划将加载项发布到 AppSource，并使其在 Office 体验中可用，请确保你遵守商业市场认证政策。 例如，加载项必须适用于支持你定义的方法的所有平台，才能通过验证（有关详细信息，请参阅第 1120.3 部分以及 Office 加载项应用程序和可用性页）。

托管要求

所有映像 URI（例如用于 外接程序命令的 URI）都必须支持生产中的缓存。 托管映像的服务器不应在 HTTP 响应中返回 Cache-Control 指定 no-cache、 no-store或类似选项的标头。 但是，在开发加载项和对图像文件进行更改时，缓存可能会阻止你看到更改，因此 Cache-Control 建议在开发中使用标头。

外接程序中代码或内容文件的所有 URL 都应 受到 SSL 保护， (HTTPS) 。 强烈建议对加载项使用 HTTPS 终结点（尽管无需在所有加载项方案中都严格遵循此要求）。 不受 SSL (HTTPS) 保护的加载项会在使用期间生成不安全的内容警告和错误。 如果计划在 Office web 版 中运行加载项或将外接程序发布到 AppSource，则它必须受到 SSL 保护。 如果加载项访问外部数据和服务，它应受 SSL 保护，以保护传输中的数据。 自签名证书可用于开发和测试，但前提是证书在本地计算机上受信任。

关于提交到 AppSource 的最佳做法

确保外接程序 ID 有效且具有唯一 GUID。 Web 上提供可用于创建唯一 GUID 的各种 GUID 生成器工具。

提交到 AppSource 的外接程序还必须在清单中包含支持 URL。 有关详细信息，请参阅提交到 AppSource 的应用和加载项的验证策略。

指定要在外接程序窗口中打开的域

在 Office 网页版中运行时，可以将任务窗格导航到任何 URL。 但是，在桌面平台中，如果外接程序尝试转到托管起始页 (的域中的 URL，而不是清单文件) 中指定的域，该 URL 将在 Office 应用程序的外接程序窗格外的新浏览器窗口中打开。

若要替代此 (桌面 Office) 行为，请在清单的外接程序窗口中指定要打开的每个域。 如果加载项尝试转至该列表的域中的 URL，则它将在 Office 网页版和桌面版中的任务窗口中打开。 如果它尝试转至列表之外的域中的 URL，则在桌面版 Office 中，该 URL 将在新的浏览器窗口中（外接程序窗格之外）打开。

注意

该行为有两个例外情况。

  • 它仅适用于外接程序的根窗格。 如果外接程序页中嵌入了 iframe，则可以将该 iframe 定向到任何 URL，而不管它是否在清单中列出，甚至在桌面 Office 中也是如此。
  • 使用 displayDialogAsync API 打开对话框时，传递给 方法的 URL 必须与外接程序位于同一域中，但该对话框随后可以定向到任何 URL，而不管它是否在清单中列出，甚至在桌面 Office 中也是如此。

指定从中执行 Office .js API 调用的域

外接程序可以从清单文件中引用的广告域进行Office.js API 调用。 如果外接程序中还有其他需要访问Office.js API 的 iframe，请将该源 URL 的域添加到清单文件。 如果清单中未列出源的 iframe 尝试进行Office.js API 调用，则外接程序将收到 权限被拒绝错误。

另请参阅