Наборы обязательных элементов API JavaScript для Outlook

Надстройки Outlook объявляют, какие версии API им требуются в манифесте. Разметка зависит от того, используете ли вы формат XML-манифеста или унифицированный манифест для Microsoft 365.

Версия API определяется свойством extensions.requirements.capabilities. Задайте для свойства "capabilities.name" значение "Почтовый ящик", а для свойства "capabilities.minVersion" — минимальный набор требований API, который поддерживает сценарии надстройки.

Например, в следующем фрагменте манифеста указан минимальный набор обязательных элементов 1.1.

"extensions": [
{
  "requirements": {
    "capabilities": [
      {
        "name": "Mailbox", "minVersion": "1.1"
      }
    ]
  },
  ...
}

Все API Outlook относятся к наборуMailbox требований. У набора требований Mailbox есть версии, а каждый новый выпускаемый набор API-интерфейсов приведен в наборе более поздней версии. Не все клиенты Outlook поддерживают новейший набор API, но если клиент Outlook объявляет поддержку набора требований, обычно он поддерживает все API в этом наборе требований (проверка документацию по конкретному API или функции для любых исключений).

Установка минимальной версии набора обязательных элементов в манифесте определяет, в которых клиент Outlook будет отображать надстройку. Если клиент не поддерживает минимальный набор требований, он не загружает надстройку. Например, если указан набор обязательных элементов версии 1.3, это означает, что надстройка не будет отображаться ни в одном клиенте Outlook, который не поддерживает хотя бы 1.3.

Примечание.

Хотя Outlook в Android и в iOS поддерживает набор требований 1.5, ваша мобильная надстройка теперь может реализовать некоторые API из более поздних наборов требований. Дополнительные сведения о том, какие API поддерживаются в Outlook Mobile, см. в статье API JavaScript, поддерживаемые в Outlook на мобильных устройствах.

Использование API из более поздних наборов требований

Установка набора требований не ограничивает доступные API, которые может использовать надстройка. Например, если надстройка указывает набор требований "Почтовый ящик 1.1", но выполняется в клиенте Outlook, который поддерживает "Почтовый ящик 1.3", надстройка может использовать API из набора требований "Почтовый ящик 1.3".

Чтобы использовать более новые API, разработчики могут проверить, поддерживает ли конкретное приложение набор обязательных элементов, выполнив следующее.

if (Office.context.requirements.isSetSupported('Mailbox', '1.3')) {
  // Perform actions.
}
else {
  // Provide alternate flow/logic.
}

Кроме того, разработчики могут проверить наличие более новых API с помощью стандартных методов JavaScript.

if (item.somePropertyOrMethod !== undefined) {
  // Use item.somePropertyOrMethod.
  item.somePropertyOrMethod;
}

Такие проверки не нужно выполнять для API-интерфейсов, присутствующих в версии набора обязательных элементов, указанной в манифесте.

Выбор минимального набора требований

Разработчикам следует использовать набор обязательных элементов самой ранней версии, содержащий набор критически важных API для сценария их работы, без которого надстройка не будет работать.

Наборы обязательных элементов, поддерживаемые серверами Exchange и клиентами Outlook

В этом разделе указан диапазон наборов обязательных элементов, поддерживаемых сервером Exchange и клиентами Outlook. Сведения о требованиях к серверу и клиенту для запуска надстроек Outlook см. в статье Требования надстроек Outlook.

Важно!

Если целевой сервер Exchange и клиент Outlook поддерживают разные наборы обязательных элементов, возможно, вы ограничены применением более ранней версии набора обязательных элементов. Например, если надстройка работает в Outlook 2019 в Windows (набор самых высоких требований: 1.6) в Exchange 2016 (набор самых высоких требований: 1.5), надстройка может быть ограничена набором требований 1.5.

Поддержка сервера Exchange

Указанные ниже серверы поддерживают надстройки Outlook.

Продукт Основная версия Exchange Поддерживаемые наборы обязательных элементов API
Exchange Online Последняя сборка 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.31
Локальная среда Exchange2 2019 1.1, 1.2, 1.3, 1.4, 1.5
2016 1.1, 1.2, 1.3, 1.4, 1.5
2013 1.1

Примечание.

1 Чтобы требовать набор API 1.3 удостоверений в коде надстройки Outlook, проверка, если он поддерживается путем вызова isSetSupported('IdentityAPI', '1.3'). Его объявление в манифесте надстройки Outlook не поддерживается. Также можно определить, поддерживается ли API, проверив, не undefined ли он. Подробнее см. в статье Использование API из наборов требования более поздних версий.

2 Даже если надстройка реализует функции из наборов требований, не поддерживаемых в локальной среде Exchange, ее все равно можно добавить в клиент Outlook до тех пор, пока набор требований, указанный в манифесте, соответствует требованиям, поддерживаемым локальной средой Exchange. Однако реализованная функция будет работать только в том случае, если клиент Outlook, в котором установлена надстройка, поддерживает минимальный набор требований, необходимый компоненту. Чтобы определить наборы требований, поддерживаемые различными клиентами Outlook, см. раздел Поддержка клиентов Outlook. Мы рекомендуем дополнить его документацией по конкретной функции для любых исключений.

Поддержка клиентов Outlook

Надстройки поддерживаются в Outlook на следующих платформах.

Платформа Основная версия Office или Outlook Поддерживаемые наборы обязательных элементов API
Windows — подписка На Microsoft 365
— розничные бессрочные Outlook 2016 и более поздние версии
1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81, 1.91, 1.101, 1.111, 1.121, 1.131
IdentityAPI 1.32
OpenBrowserWindowApi 1.1
новый Outlook в Windows (предварительная версия) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.32
Корпоративный бессрочный Outlook 2021 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81, 1.91
IdentityAPI 1.32
OpenBrowserWindowApi 1.1
Корпоративный бессрочный Outlook 2019 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
Outlook 2016 с лицензированием с бессрочным лицензированием 1.1, 1.2, 1.3, 1.43
Бессрочный Outlook 2013 1.1, 1.2, 1.33, 1.43
Mac классический пользовательский интерфейс 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
IdentityAPI 1.32
OpenBrowserWindowApi 1.1
новый пользовательский интерфейс4 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.32
Android5 6 7 Подписки 1.1, 1.2, 1.3, 1.4, 1.5
iOS5 6 7 Подписки 1.1, 1.2, 1.3, 1.4, 1.5
Веб-браузер5 8 современный пользовательский интерфейс Outlook при подключении к
Exchange Online: подписка, Outlook.com
1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.32
классический пользовательский интерфейс Outlook при подключении к
Локальная среда Exchange
1.1, 1.2, 1.3, 1.4, 1.5, 1.6

Примечание.

1 Поддержка версий для более поздних наборов требований в Outlook для Windows с подпиской Microsoft 365 или розничной бессрочной лицензией следующим образом:

  • Поддержка версии 1.8 доступна в версии 1910 (сборка 12130.20272).
  • Поддержка версии 1.9 доступна в версии 2008 (сборка 13127.20296).
  • Поддержка версии 1.10 доступна в версии 2104 (сборка 13929.20296).
  • Поддержка версии 1.11 доступна в версии 2110 (сборка 14527.20226).
  • Поддержка версии 1.12 доступна в версии 2206 (сборка 15330.20196).
  • Поддержка версии 1.13 доступна в версии 2304 (сборка 16327.20248).

Дополнительные сведения в соответствии с вашей версией см. на странице журнала обновлений для Office 2021 или Microsoft 365 и о том, как найти версию клиента Office и канал обновления.

2 Чтобы потребовать набор API удостоверений 1.3 в коде надстройки Outlook, проверьте, поддерживается ли он вызовом isSetSupported('IdentityAPI', '1.3'). Его объявление в манифесте надстройки Outlook не поддерживается. Также можно определить, поддерживается ли API, проверив, не undefined ли он. Подробнее см. в статье Использование API из наборов требования более поздних версий.

3Поддержка версии 1.3 в Outlook 2013 добавлена в рамках обновления для Outlook 2013 (KB3114349) от 8 декабря 2015 г. Поддержка версии 1.4 в Outlook 2013 добавлена в рамках обновления для Outlook 2013 (KB3118280) от 13 сентября 2016 г. Поддержка версии 1.4 в корпоративной бессрочной Outlook 2016 была добавлена в рамках обновления Office 2016 (KB4022223) от 3 июля 2018 г.

4 Поддержка нового пользовательского интерфейса Mac доступна в Outlook версии 16.38.506. Дополнительные сведения см. в разделе Поддержка надстроек в Outlook в новом интерфейсе Mac.

5 Надстройки не поддерживаются в Outlook для Android, iOS и современных мобильных веб-приложениях с локальными учетными записями Exchange. Некоторые устройства iOS по-прежнему поддерживают надстройки при использовании локальных учетных записей Exchange с классическими Outlook в Интернете. Сведения о поддерживаемых устройствах см. в разделе Требования к запуску надстроек для Office.

6 В настоящее время при проектировании и реализации надстроек для мобильных клиентов существуют дополнительные рекомендации. Дополнительные сведения см. в разделе Рекомендации по коду при добавлении поддержки команд надстроек в Outlook на мобильных устройствах.

7 Хотя Outlook в Android и в iOS поддерживает набор требований 1.5, ваша мобильная надстройка теперь может реализовать некоторые API из более поздних наборов требований. Дополнительные сведения о том, какие API поддерживаются в Outlook Mobile, см. в статье API JavaScript, поддерживаемые в Outlook на мобильных устройствах.

8 надстройки не работают в современных Outlook в Интернете на смартфонах iPhone и Android. Сведения о поддерживаемых устройствах см. в разделе Требования к запуску надстроек для Office.

Совет

Классическую и современную версии Outlook в веб-браузере можно различить по внешнему виду панели инструментов почтового ящика.

современная версия

Современная панель инструментов Outlook.

классическая версия

Классическая панель инструментов Outlook.

Ссылка на рабочую библиотеку API JavaScript для Office

Чтобы использовать API в любом из нумерованных наборов обязательных элементов, следует ссылаться на рабочую библиотеку в сети доставки содержимого (CDN) Office.js. Сведения об использовании api предварительной версии см. в разделе Тестирование api предварительной версии.

Интерфейсы API тестовой предварительной версии

Новые API JavaScript для Outlook сначала выпускаются в "предварительной версии", а затем становятся частью определенного нумерованного набора обязательных элементов после выполнения достаточного тестирования и получения отзывов пользователей. Чтобы отправить отзыв о предварительной версии API, используйте способ обратной связи, представленный в конце веб-страницы с описанием API.

Примечание.

Api предварительной версии могут быть изменены и не предназначены для использования в рабочей среде.

Дополнительные сведения о предварительных версиях интерфейсов API см. в статье Предварительная версия набора обязательных элементов API для Outlook.