Указание требований к надстройке Office в унифицированном манифесте для Microsoft 365
В едином манифесте Microsoft 365 есть несколько свойств "requirements". Свойство extensions.requirements управляет приложениями и версиями Office, в которых можно установить надстройку. Другие свойства "requirements" используются для выборочного подавления некоторых функций надстройки в определенных приложениях Или версиях Office, где эти функции будут ненужными или неподдерживаемые. Дополнительные сведения см. в разделе Функции фильтрации.
extensions.requirements
Свойство extensions.requirements указывает области, форм-факторы и наборы требований для надстроек Microsoft 365. Если версия Microsoft 365 не поддерживает указанные требования, расширение не будет доступно для установки. Пользователи не увидят его в пользовательском интерфейсе Office для поиска и установки надстроек. Некоторые примеры:
- Если для свойства "requirements.capabilities.name" задано значение "Почтовый ящик", а для "requirements.capabilities.minVersion" — "1.10", надстройка не устанавливается в более ранних версиях Office, которые не поддерживают наборы обязательных почтовых ящиков версии 1.9.
- Если параметру requirements.scopes присвоено значение mail, надстройка устанавливается только в Outlook.
- Если параметру requirements.formFactors присвоено только значение "desktop", надстройка не устанавливается в Office, работающем на мобильном устройстве.
У вас может быть несколько объектов возможностей. В следующем примере показано, как убедиться, что надстройка может устанавливаться только в версиях Office, поддерживающих два разных набора требований, а не на мобильных устройствах.
"extensions": [
...
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.10"
},
{
"name": "DialogAPI",
"minVersion": "1.2"
}
],
"formFactors": [
"desktop"
]
}
]
Функции фильтрации
Свойства "requirements" в дочерних объектах "расширений" используются для блокировки некоторых функций надстройки, по-прежнему разрешая установку надстройки. Реализация этой фильтрации выполняется в источнике установки, например AppSource или Microsoft 365 Admin Center. Если версия Office не поддерживает требования, указанные для компонента, узел JSON для компонента удаляется из манифеста перед установкой в приложение Office.
Совет
Не включайте требование возможности, formFactor или область в объект-потомок extensions, который является менее строгим, чем требование соответствующей возможности, formFactor или область в свойстве-предке extensions.requirements, если оно есть. Так как надстройка не может быть установлена на клиентах, которые не соответствуют требованиям предка, фильтрация функций в любом случае не будет выполняться. Например, если для свойства extensions.requirements.capabilities требуется почтовый ящик 1.10, нет смысла требовать почтовый ящик 1.9 в каких-либо дочерних объектах.
extensions.alternates.requirements
Свойство extensions.alternates позволяет разработчикам надстроек выполнять следующие действия:
- Поддерживайте версию надстройки, построенную на более старой платформе расширяемости (например, надстройки COM или VSTO), или используя манифест только надстройки, в дополнение к версии, которая использует унифицированный манифест.
- Скрыть или отдать предпочтение версии, которая использует старую технологию.
- Укажите значки, необходимые для установки унифицированной версии манифеста надстройки в версиях Office, которые не поддерживают единый манифест напрямую.
Примечание.
Надстройки Office, использующие унифицированный манифест для Microsoft 365, поддерживаются непосредственно в Office в Интернете, в новом Outlook для Windows и в Office в Windows, подключенных к подписке Microsoft 365 версии 2304 (сборка 16320.00000) или более поздней версии.
Когда пакет приложения, содержащий унифицированный манифест, развертывается в AppSource или центре Microsoft 365 Admin, из унифицированного манифеста создается только манифест надстройки и сохраняется. Только этот манифест надстройки позволяет устанавливать надстройку на платформах, которые не поддерживают унифицированный манифест напрямую, включая Office для Mac, Office на мобильных устройствах, версии Office для Windows по подписке до 2304 (сборка 16320.00000) и бессрочные версии Office в Windows.
Дополнительные сведения см. в статье Управление унифицированным манифестом и версией манифеста только надстройки Office.
Подсвойство "requirements" типа extensions.alternates позволяет выборочно применять вложенные свойства "скрыть" или "предпочтительнее" только при выполнении определенных требований.
Например, предположим, что вы хотите скрыть (в пользовательском интерфейсе Office для установки надстроек) старую версию надстройки, но только в версиях Office, поддерживающих набор обязательных почтовых ящиков 1.10 . Это можно сделать с помощью следующей разметки:
"extensions": [
...
{
...
"alternates": [
...
{
...
"hide": {
"storeOfficeAddin": {
"officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
"assetId": "WA999999999"
}
},
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.10"
}
]
}
}
]
}
]
extensions.autoRunEvents.requirements
Свойство extensions.autoRunEvents настраивает надстройку для автоматического выполнения указанного кода в ответ на указанные события. Подсвойство "requirements" можно использовать для блокировки этого поведения в некоторых версиях Office.
Например, предположим, что надстройка Outlook настроена для автозапуска в ответ на событие OnMailSend и предположим, что код в выполняемой функции требует набора обязательных почтовых ящиков 1.13 . Но надстройка имеет другие функции, которые были бы полезны в версиях Office, которые поддерживают только версию 1.12. Чтобы убедиться, что надстройка доступна для установки в версиях, поддерживающих версию 1.12, разработчик может задать для свойства extensions.requirements.capabilities значение параметра Mailbox 1.12 вместо 1.13. Но чтобы заблокировать функцию автозапуска в версиях, не поддерживающих версию 1.13, разработчик может добавить свойство extensions.autoRunEvents.requirements.capabilities, указывающее mailbox 1.13. Ниже приведен пример.
"extensions": [
...
{
...
"autoRunEvents": [
...
{
...
"events": {
"type": "OnMailSend",
"actionId": "logOutgoingEmail",
"options": {
"sendMode": "promptUser"
}
},
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.13"
}
]
}
}
]
}
]
extensions.contextMenus.requirements
Свойство extensions.contextMenus настраивает контекстные меню надстройки. Контекстное меню — это контекстное меню, которое появляется при щелчке правой кнопкой мыши (или выборе и удержании) в пользовательском интерфейсе Office. Подсвойство "requirements" можно использовать для разрешения контекстных меню только при соблюдении определенных требований.
Например, предположим, что вы хотите отображать контекстные меню только в версиях Excel, поддерживающих набор требований AddinCommands 1.1. Это можно сделать с помощью следующей разметки:
"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 можно настроить так, чтобы предоставить одно описание надстройки для клиентов Excel, которые поддерживают наборы требований от 1.6 до 1.16, но другое описание для клиентов, поддерживающих версии 1.17 и более поздних версий. Ниже приведен пример. Обратите внимание, что в этом примере, если надстройка настроена для установки на клиентах Excel, которые не поддерживают набор требований 1.6, то на этих клиентах не будет использоваться ни один из этих объектов 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 . Но надстройка имеет другие функции, которые были бы полезны в версиях Office, поддерживающих только версию 1.8. Чтобы убедиться, что надстройка доступна для установки в версиях, поддерживающих версию 1.8, разработчик может задать для свойства extensions.requirements.capabilities значение параметра Mailbox 1.8 вместо 1.9. Но чтобы запретить появление настраиваемой кнопки на ленте в версиях, не поддерживающих версию 1.9, разработчик может добавить свойство extensions.ribbons.requirements.capabilities, указывающее почтовый ящик 1.9. Ниже приведен пример. Дополнительные сведения о настраиваемой конфигурации ленты см. в статье Создание команд надстроек с помощью унифицированного манифеста для 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 , для которого требуется почтовый ящик 1.13. Предположим, что в этом же сценарии объект среды выполнения, настроенный для поддержки действия logOutgoingEmail, не настроен для поддержки каких-либо других действий. В этом случае разработчик должен заблокировать объект среды выполнения в версиях, которые не поддерживают почтовый ящик 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" можно использовать для обеспечения доступности настраиваемых сочетаний клавиш только на платформах, поддерживающих API SharedRuntime 1.1. В следующем примере показано, как настроить эту функцию в манифесте.
"extensions": [
...
{
...
"keyboardShortcuts": [
{
//Insert details of the keyboard shortcut configuration here.
"requirements" : {
"capabilities": [
{
"name": "SharedRuntime",
"minVersion": "1.1"
}
]
}
}
]
}
]
Office Add-ins