在 Microsoft 365 的统一清单中指定 Office 外接程序要求

项目
02/14/2025

Microsoft 365 的统一清单中有几个“要求”属性。 extensions.requirements 属性控制可安装加载项的 Office 应用程序和版本。其他“要求”属性用于在特定 Office 应用程序或版本中选择性地禁止显示加载项的某些功能，这些功能不需要或不受支持。有关详细信息，请参阅筛选器功能。

extensions.requirements

“extensions.requirements”属性指定Microsoft 365 加载项的范围、外形规格和要求集。如果 Microsoft 365 版本不支持指定的要求，则扩展将无法安装。用户在搜索和安装加载项时不会在 Office UI 中看到它。一些示例：

如果“requirements.capabilities.name”属性设置为“Mailbox”，并将“requirements.capabilities.minVersion”设置为“1.10”，则不支持 邮箱要求集 大于版本 1.9 的旧版 Office 上无法安装外接程序。
如果“requirements.scopes”设置为“mail”，则加载项只能在 Outlook 上安装。
如果“requirements.formFactors”设置为仅“桌面”，则无法在移动设备上运行的 Office 上安装加载项。

可以有多个功能对象。以下示例演示如何确保加载项只能在支持两个不同要求集的 Office 版本上安装，而不能在移动设备上安装。

"extensions": [
    ...
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.10"
            },
            {
                "name": "DialogAPI",
                "minVersion": "1.2"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    }
]

筛选器功能

“扩展”的后代对象中的“要求”属性用于阻止加载项的某些功能，同时仍允许安装加载项。此筛选的实现在安装源处完成，例如 AppSource 或 Microsoft 365 管理 Center。如果 Office 版本不支持为该功能指定的要求，则在将该功能安装在 Office 应用程序中之前，该功能的 JSON 节点将从清单中删除。

提示

请勿在“extensions”的后代对象中包含功能、formFactor 或范围要求，该对象的限制 性低于 祖先“extensions.requirements”属性中的相应功能、formFactor 或范围要求（如果有）。由于加载项不能安装在不符合上级要求的客户端上，因此不会进行功能筛选。例如，如果“extensions.requirements.capabilities”属性需要 Mailbox 1.10，则在任何后代对象中都不需要 Mailbox 1.9 。

extensions.alternates.requirements

加载项开发人员可以使用“extensions.alternates”属性执行以下作：

除了使用统一清单的版本之外，还维护在较旧的扩展性平台 (（如 COM 或 VSTO 外接程序) ）或仅外接程序清单等加载项版本。
隐藏或优先使用旧技术的版本。
指定使外接程序的统一清单版本可在不直接支持统一清单的 Office 版本上安装所需的图标。

注意

在连接到 Microsoft 365 订阅版本 2304 (内部版本 16320.000000) 或更高版本的 Office web 版、新的 Outlook 和 Office on Windows 中，直接支持使用 Microsoft 365 统一清单的 Office 加载项。

当包含统一清单的应用包部署在 AppSource 或 Microsoft 365 管理中心时，将从统一清单生成并存储仅外接程序清单。此仅外接程序清单允许在不直接支持统一清单的平台上安装外接程序，包括 Mac 上的 Office、移动版 Office、Windows 上早于 2304 (内部版本 16320.00000) 的 Office 订阅版本，以及 Windows 上的 Office 永久版本。

有关详细信息，请参阅管理 Office 外接程序的统一清单和仅外接程序清单版本。

“extensions.alternates”的“requirements”子属性，仅在满足某些要求时选择性地应用“隐藏”或“首选”子属性。

例如，假设你想要在 Office UI 中隐藏 (，以便) 旧版外接程序安装加载项，但仅在支持 Mailbox 1.10 要求集的 Office 版本中。可以使用如下所示的标记执行此作：

"extensions": [
    ...
    {
        ...
        "alternates": [
            ...
            {
                ...
                "hide": {
                    "storeOfficeAddin": {
                        "officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
                        "assetId": "WA999999999"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.10"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.autoRunEvents.requirements

“extensions.autoRunEvents”属性将外接程序配置为自动运行指定的代码以响应指定的事件。在某些 Office 版本中，可以使用“要求”子属性来阻止此行为。

例如，假设 Outlook 加载项配置为自动启动以响应 OnMailSend 事件，并假设运行的函数中的代码需要 Mailbox 1.13 要求集。但加载项具有其他功能，这些功能在仅支持版本 1.12 的 Office 版本中非常有用。为了确保加载项可在支持 1.12 的版本中安装，开发人员可以将“extensions.requirements.capabilities”属性设置为要求集 Mailbox 1.12 而不是 1.13。但是，若要在不支持 1.13 的版本中阻止自动启动功能，开发人员可以添加指定 Mailbox 1.13 的“extensions.autoRunEvents.requirements.capabilities”属性。示例如下。

"extensions": [
    ...
    {
        ...
        "autoRunEvents": [
            ...
            {
                ...
                "events": {
                    "type": "OnMailSend",
                    "actionId": "logOutgoingEmail",
                    "options": {
                        "sendMode": "promptUser"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.contextMenus.requirements

“extensions.contextMenus”属性配置加载项的上下文菜单。上下文菜单是在 Office UI 中右键单击 (或选择并按住) 时显示的快捷菜单。 “requirements”子属性可用于仅当满足某些要求时允许上下文菜单。

例如，假设你只想在支持 AddinCommands 1.1 要求集的 Excel 版本中显示上下文菜单。可以使用如下所示的标记执行此作：

"extensions": [
    ...
    {
        ...
        "contextMenus": [
            ...
            {
                // Insert details of the context menu configuration here.

                "requirements": {
                    "scopes": [
                        "workbook"
                    ],
                    "capabilities": [
                        {
                            "name": "AddinCommands",
                            "minVersion": "1.1"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.getStartedMessages.requirements

数组中的 extensions.getStartedMessages 对象提供有关 Office 中各个位置中显示的 Office 外接程序的信息，例如安装 Office 外接程序时 Office 中显示的标注。数组中最多可以有三个对象。如果有多个对象，请使用 extensions.getStartedMessages.requirements 属性，以确保在任何给定的 Office 客户端中使用不超过一个这些对象。如果 extensions.getStartedMessages 省略或筛选掉数组中的所有对象，则标注将改用“name.short”和“description.short”清单属性中的值。

例如，假设 Excel 加载项简化了向区域添加条件格式的过程。加载项使用的一些 API 是随 ExcelApi 1.17 要求集一起引入的，但外接程序仍提供仅需要 ExcelApi 1.6 要求集的有用功能。该extensions.getStartedMessages数组可配置为支持从 1.6 到 1.16 的要求集的 Excel 客户端提供加载项的一个说明，但对于支持 1.17 及更高版本的客户端，则提供不同的说明。示例如下。请注意，在此示例中，如果外接程序配置为可在不支持要求集 1.6 的 Excel 客户端上安装，则在这些客户端上不会使用 getStartedMessage 对象。相反，Office 将使用“name.short”和“description.short”属性。

"extensions": [
    ...
    {
        ...
        "getStartedMessages": [
            {
                "title": "Contoso Excel Formatting",
                "description": "Use conditional formatting with our add-in.",
                "learnMoreUrl": "https://contoso.com/simple-conditional-formatting-details.html",
                "requirements": {
                    "capabilities": [
                        {
                            "name": "ExcelApi",
                            "minVersion": "1.6",
                            "maxVersion": "1.16"
                        }
                    ]
                }
            },
            {
                "title": "Contoso Advanced Excel Formatting",
                "description": "Use conditional formatting and dynamic formatting changes with our add-in.",
                "learnMoreUrl": "https://contoso.com/advanced-conditional-formatting-details.html",
                "requirements": {
                    "capabilities": [
                        {
                            "name": "ExcelApi",
                            "minVersion": "1.17"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.ribbons.requirements

安装加载项时，“extensions.ribbons”属性用于自定义 Office 应用程序功能区。 “requirements”子属性可用于防止某些版本的 Office 中的自定义。

例如，假设 Outlook 外接程序配置为将自定义按钮添加到功能区，并且该按钮运行使用 Mailbox 1.9 要求集中引入的代码的函数。但加载项具有其他功能，这些功能在仅支持版本 1.8 的 Office 版本上非常有用。为了确保加载项可在支持 1.8 的版本上安装，开发人员可以将“extensions.requirements.capabilities”属性设置为要求集 Mailbox 1.8 而不是 1.9。但是，若要阻止自定义按钮显示在不支持 1.9 的版本的功能区上，开发人员可以添加指定 Mailbox 1.9 的“extensions.ribbons.requirements.capabilities”属性。示例如下。有关自定义功能区配置的详细信息，请参阅使用 Microsoft 365 的统一清单创建外接程序命令。

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                // Insert details of the ribbon configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.9"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.runtimes.requirements

“extensions.runtimes”属性配置每个扩展点可以使用的运行时集和作集。有关其用法的详细信息，请参阅创建外接程序命令、为任务窗格配置运行时和为函数命令配置运行时。有关 Office 外接程序中的运行时的详细信息，请参阅 Office 外接程序中的运行时。

“requirements”子属性可用于防止运行时包含在 Office 版本或不使用它的 Office 应用程序中。

extensions.autoRunEvents.requirements 中所示的上一个示例演示如何在不支持函数中的所有代码logOutgoingEmail的版本中阻止自动启动功能，其中包括需要 Mailbox 1.13 的代码。假设在同一方案中，配置为支持“logOutgoingEmail”作的“运行时”对象未配置为支持任何其他作。在这种情况下，开发人员应在不支持 Mailbox 1.13 的版本中阻止运行时对象，因为它永远不会被使用。示例如下。有关运行时配置的详细信息，请参阅使用 Microsoft 365 的统一清单创建外接程序命令。

"extensions": [
    ...
    {
        ...
        "runtimes": [
            ...
            {
                // Insert details of the runtime configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

同样，对于 extensions.ribbons.requirements 中的示例，如果链接到自定义按钮的作是在运行时对象中配置的唯一作，则应在阻止功能区对象的相同情况下阻止该运行时对象。

extensions.keyboardShortcuts.requirements (开发人员预览版)

属性 extensions.keyboardShortcuts 定义自定义键盘快捷方式或组合键以运行特定作。若要了解如何创建自定义快捷方式，请参阅向 Office 外接程序添加自定义键盘快捷方式。

“requirements”子属性可用于确保自定义快捷方式仅在支持 SharedRuntime 1.1 API 的平台上可用。以下示例演示如何在清单中配置此项。

"extensions": [
    ...
    {
        ...
        "keyboardShortcuts": [
            {
                //Insert details of the keyboard shortcut configuration here.

                "requirements" : {
                    "capabilities": [
                        {
                            "name": "SharedRuntime",
                            "minVersion": "1.1"
                        }
                    ]
                }
            }
        ]
    }
]

通过