Указание требований к надстройке 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. Если версия Office не поддерживает требования, указанные для компонента, узел JSON для компонента удаляется из манифеста перед установкой в приложение Office.

extensions.alternates.requirements

Свойство extensions.alternates позволяет разработчикам надстроек выполнять следующие действия:

  • Поддерживайте версию надстройки, построенную на более старой платформе расширяемости (например, надстройки COM или VSTO), или используя манифест только надстройки, в дополнение к версии, которая использует унифицированный манифест.
  • Скрыть или отдать предпочтение версии, которая использует старую технологию.
  • Укажите значки, необходимые для установки унифицированной версии манифеста надстройки в версиях Office, которые не поддерживают единый манифест напрямую.

Примечание.

Надстройки Office, использующие единый манифест Microsoft 365, поддерживаются непосредственно в Office в Интернете, в новом Outlook для Windows и в Office для Windows, подключенных к подписке Microsoft 365 версии 2304 (сборка 16320.00000) или более поздней.

Если пакет приложения, содержащий унифицированный манифест, развертывается в AppSource или Центре администрирования Microsoft 365 , то, если манифест имеет допустимое свойство alternateIcons, из единого манифеста создается только манифест надстройки и сохраняется. Только этот манифест надстройки позволяет устанавливать надстройку на платформах, которые не поддерживают унифицированный манифест напрямую, включая 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.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, если действие, связанное с настраиваемой кнопкой, является единственным действием, настроенным в объекте среды выполнения, этот объект среды выполнения должен быть заблокирован в тех же обстоятельствах, в которых заблокирован объект ленты.