使用统一清单指定 Office 应用程序和 API 要求

项目
02/14/2025

注意

有关使用仅外接程序清单指定要求的信息，请参阅使用仅外接程序清单指定 Office 主机和 API 要求。

Office 加载项可能依赖于特定 Office 应用程序 (也称为 Office 主机) 或 Office JavaScript 库 (office.js) 的特定成员。例如，你的外接程序可能：

在单个 Office 应用程序（如，Word 或 Excel）或多个应用程序中运行。
使用仅在某些 Office 版本中可用的 Office JavaScript API。例如，Excel 2016的批量许可永久版本不支持 Office JavaScript 库中所有与 Excel 相关的 API。
设计为仅在移动外形规格中使用。

在这些情况下，你需要确保你的外接程序永远不会安装在 Office 应用程序或 Office 版本（不能运行它）上。

在某些情况下，你还希望根据用户的 Office 应用程序和 Office 版本控制加载项的哪些功能对用户可见。三个示例如下：

加载项具有在 Word 和 PowerPoint 中都有用的功能（如文本作），但它具有一些仅在 PowerPoint 中有意义的其他功能，例如幻灯片管理功能。当加载项在 Word 中运行时，需要隐藏仅 PowerPoint 功能。
加载项具有一项功能，该功能需要 Office JavaScript API 方法，该方法在某些版本的 Office 应用程序（如 Microsoft 365 订阅 Excel）中受支持，但不受其他版本的支持，例如批量许可永久Excel 2016。但是，加载项具有其他功能，这些功能仅需要批量许可永久Excel 2016中支持的 Office JavaScript API 方法。在此方案中，你需要在该版本的 Excel 2016 上安装加载项，但需要不受支持的方法的功能应该对这些用户隐藏。
加载项具有桌面 Office 中支持的功能，但在移动 Office 中不受支持。

本文可帮助你了解如何确保加载项按预期工作，并尽可能覆盖最广泛的受众。

注意

有关 Office 加载项当前支持的位置的高级视图，请参阅 Office 外接程序的 Office 客户端应用程序和平台可用性页。

提示

使用工具（例如 Office 外接程序的 Yeoman 生成器或 Visual Studio 中的 Office 外接程序模板之一）创建外接程序项目时，本文所述的许多任务都是为你完成的。在这种情况下，请将任务解释为，这意味着你应该验证它是否已完成。

使用最新的 Office JavaScript API 库

外接程序应从内容分发网络 (CDN) 加载最新版本的 Office JavaScript API 库。为此，请确保加载项打开的第一个 HTML 文件中具有以下 <script> 标记。使用 CDN URL 中的 /1/ 可以确保引用的是最新版本的 Office.js。

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

指定哪些 Office 应用程序可以托管加载项

若要指定可安装外接程序的 Office 应用程序，请使用“extensions.requirements.scopes”数组。指定“mail”、“workbook”、“document”和“presentation”的任何子集。下表显示了哪些 Office 应用程序和平台组合对应于这些值。它还显示了可以为每个范围安装哪种类型的外接程序。

名称	Office 客户端应用程序	可用的加载项类型
document	web、Windows、Mac、iPad 上的Word	任务窗格
mail	Outlook 网页版、Windows (新的和经典) 、Android、iOS	邮件
演示文稿	PowerPoint web 版、Windows、Mac、iPad	任务窗格，内容
工作簿	Excel web 版、Windows、Mac、iPad	任务窗格，内容

注意

内容加载项具有“extensions.contentRuntimes”属性。它们不能具有“extensions.runtimes”属性，因此无法与任务窗格或邮件加载项组合使用。有关内容加载项的详细信息，请参阅内容 Office 外接程序。

例如，以下 JSON 指定加载项可以在任何版本的 Excel 上安装，其中包括Excel web 版、Windows 和 iPad，但不能安装在任何其他 Office 应用程序上。

"extensions": [
    {
        "requirements": {
            "scopes": [ "workbook" ],
        },
        ...
    }
]

注意

Office 应用程序在不同平台上受支持，并在桌面、Web 浏览器、平板电脑和移动设备上运行。通常无法指定哪个平台可用于运行加载项。例如，如果指定“workbook”，Excel web 版和 Windows 上都可用于运行加载项。但是，如果指定“mail”，则外接程序将不会在 Outlook 移动客户端上运行，除非你定义了移动扩展点。

指定外接程序所需的 Office API

你无法显式指定 Office 版本和内部版本或应可安装外接程序的平台，并且你不希望，因为每当加载项使用的加载项功能支持扩展到新版本或平台时，都必须修改清单。相反，请在清单中指定外接程序所需的 API。 Office 阻止加载项安装在不支持 API 的 Office 版本和平台的组合上，并确保外接程序不会出现在 “我的外接程序”中。

重要

仅使用作为“extensions”的直接子级的“requirements”属性来指定外接程序必须具有任何重要值的 API 成员。如果外接程序使用 API 实现某些功能，但具有不需要该 API 的其他有用功能，则应设计外接程序，使其可安装在不支持 API 但会降低这些组合体验的平台和 Office 版本组合上。为此，请使用不是“扩展”的直接子级的“要求”属性。有关详细信息，请参阅设计备用体验。

要求集

为了简化指定外接程序所需的 API 的过程，Office 会将大多数 API 分组到要求集中。通用 API 对象模型中的 API 按它们支持的开发功能分组。例如，连接到表绑定的所有 API 都位于名为“TableBindings 1.1”的要求集中。应用程序特定对象模型中的 API 按何时发布以供生产加载项使用分组。

要求集是版本控制。例如，支持对话框的 API 位于要求集 DialogApi 1.1 中。当将启用从任务窗格消息传送到对话的其他 API 发布后，这些 API 与 DialogApi 1.1 中的所有 API 一起分组到 DialogApi 1.2 中。 要求集的每个版本都是所有早期版本的超集。

要求集支持因 Office 应用程序、Office 应用程序版本及其运行平台而异。例如，在 Office 2021 之前，批量许可的 Office 永久版本不支持 DialogApi 1.2，但回到 Office 2016 的所有永久版本都支持 DialogApi 1.1。你希望外接程序可在支持其使用的 API 的每种平台和 Office 版本组合上安装，因此应始终在清单中指定外接程序所需的每个要求集 的最低 版本。本文稍后将详细介绍如何执行此作。

提示

有关要求集版本控制的详细信息，请参阅 Office 要求集可用性，有关要求集的完整列表以及每个要求集中 API 的信息，请从 Office 外接程序要求集开始。大多数 Office.js API 的参考主题还指定它们属于 (（如果有任何) ）的要求集。

extensions.requirements.capabilities 属性

使用“requirements.capabilities”属性指定 Office 应用程序必须支持的最低要求集才能安装外接程序。如果 Office 应用程序或平台不支持“requirements.capabilities”属性中指定的要求集或 API 成员，则外接程序不会在该应用程序或平台中运行，并且不会显示在 “我的外接程序”中。

提示

特定于应用程序的模型中的所有 API 都在要求集中，但通用 API 模型中的某些 API 不在要求集中。如果外接程序需要不在任何要求集中的 API，则可以实现运行时检查以获取 API 的可用性，并在不受支持时向外接程序的用户显示一条消息。有关详细信息，请参阅检查运行时的 API 可用性。

下面的代码示例演示如何配置可在支持以下内容的所有 Office 应用程序和平台组合中安装的加载项：

TableBindings 要求集，其最低版本为“1.1”。
OOXML 要求集，其最低版本为“1.1”。

"extensions": [
    {
        "requirements": {
            "capabilities": [ 
                {
                    "name": "TableBindings",
                    "minVersion": "1.1"
                },
                {
                    "name": "OOXML",
                    "minVersion": "1.1"
                }
            ],
        },
        ...
    }
]

提示

有关详细信息和使用“extensions.requirements”属性的另一个示例，请参阅 Microsoft 365 统一清单中指定 Office 外接程序要求中的“extensions.requirements”部分。

指定可安装加载项的外形规格

对于 Outlook 加载项，可以指定加载项是否应安装在桌面上， (包括平板电脑) 或移动外形规格。若要对此进行配置，请使用“extensions.requirements.formFactors”属性。以下示例演示如何使 Outlook 加载项在这两种外形规格上均可安装。

"extensions": [
    {
        "requirements": {
            ...
            "formFactors": [
                "desktop",
                "mobile"
            ]
        },
        ...
    }
]

针对备用体验进行设计

Office 外接程序平台提供的扩展性功能可以有效地分为三种类型：

安装加载项后立即可用的扩展性功能。此类功能的一个示例是外接程序命令，它们是自定义功能区按钮和菜单。
仅当加载项正在运行且使用 Office.js JavaScript API 实现的扩展性功能;例如“对话框”。
扩展性功能仅在运行时可用，但通过 Office.js JavaScript 和清单配置的组合实现。例如 Excel 自定义函数、单一登录和自定义上下文选项卡。

如果外接程序对其某些功能使用特定的扩展性功能，但具有不需要扩展性功能的其他有用功能，则应设计外接程序，使其可安装在不支持扩展功能的平台和 Office 版本组合上。它可以在这些组合上提供有价值的（尽管已减少）经验。

根据扩展性功能的实现方式，以不同的方式实现此设计：

有关完全使用 JavaScript 实现的功能，请参阅检查运行时的 API 可用性。
有关需要配置清单的功能，请参阅 Microsoft 365 的统一清单中指定 Office 外接程序要求中的“筛选器功能”部分。

通过