Office 加载项清单

  • 项目

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

  • XML 清单：这是非 Outlook 加载项当前唯一支持的清单类型。如名称所示，它是 XML 格式。 此类清单不能用于将外接程序与 Microsoft 365 平台的某些其他类型的扩展组合在一起的应用。
  • Microsoft 365 的统一清单：这是 JSON 格式清单的扩展版本，多年来一直用作 Teams 应用的清单。 使用此清单的外接程序可以与 Microsoft 365 平台的其他类型的扩展组合在一个可作为一个单元安装的应用中。

注意

使用 Microsoft 365 统一清单的 Office 加载项在 Office web 版、新的 Windows 版 Outlook (预览版) 中以及连接到 Microsoft 365 订阅版本 2304 (内部版本 16320.00000) 或更高版本的 Office 上直接受支持。

在 AppSource 或 Microsoft 365 管理 Center 中部署包含统一清单的应用包时，如果清单具有有效的“alternateIcons”属性，则会从统一清单生成并存储 XML 清单。 此 XML 清单使加载项可以安装在不直接支持统一清单的平台上，包括 Mac 版 Office、移动版 Office、Windows 2304 (内部版本 16320.00000) 的 Office 订阅版本，以及 Windows 上的 Office 永久版本。

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

提示

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 web 版 或新的 Outlook on Windows (预览版) 中运行时，可以将任务窗格导航到任何 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 调用，则外接程序将收到 权限被拒绝错误。

另请参阅