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

项目
08/06/2024

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.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.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 中的示例，如果链接到自定义按钮的操作是在运行时对象中配置的唯一操作，则应在阻止功能区对象的相同情况下阻止该运行时对象。

通过