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

项目
04/12/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 加载项）) 或使用 XML 清单构建的外接程序版本。
隐藏或优先使用旧技术的版本。
指定使外接程序的统一清单版本可在不直接支持统一清单的 Office 版本上安装所需的图标。

注意

使用 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 外接程序的统一清单和 XML 清单版本。

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

Share via