Наборы обязательных элементов API JavaScript для Outlook
Надстройки Outlook объявляют, какие версии API им требуются в манифесте. Разметка зависит от того, используете ли вы только формат манифеста надстройки или унифицированный манифест для 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, 1.14 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 |
Примечание.
1 Чтобы требовать набор API 1.3 удостоверений в коде надстройки Outlook, проверка, если он поддерживается путем вызова isSetSupported('IdentityAPI', '1.3'). Его объявление в манифесте надстройки Outlook не поддерживается. Также можно определить, поддерживается ли API, проверив, не undefined ли он. Подробнее см. в статье Использование API из наборов требования более поздних версий.
2 Даже если надстройка реализует функции из наборов требований, не поддерживаемых в локальной среде Exchange, ее все равно можно добавить в клиент Outlook до тех пор, пока набор требований, указанный в манифесте, соответствует требованиям, поддерживаемым локальной средой Exchange. Однако реализованная функция будет работать только в том случае, если клиент Outlook, в котором установлена надстройка, поддерживает минимальный набор требований, необходимый компоненту. Чтобы определить наборы требований, поддерживаемые различными клиентами Outlook, см. раздел Поддержка клиентов Outlook. Мы рекомендуем дополнить его документацией по конкретной функции для любых исключений.
Поддержка клиентов Outlook
Надстройки поддерживаются в Outlook на следующих платформах.
Примечание.
1 Надстройки не поддерживаются в Outlook для Android, iOS и современных мобильных веб-приложениях с локальными учетными записями Exchange. Некоторые устройства iOS по-прежнему поддерживают надстройки при использовании локальных учетных записей Exchange с классическими Outlook в Интернете. Сведения о поддерживаемых устройствах см. в разделе Требования к запуску надстроек для Office.
2 Надстройки не работают в современных Outlook в Интернете на смартфонах iPhone и Android. Сведения о поддерживаемых устройствах см. в разделе Требования к запуску надстроек для Office.
3 Чтобы требовать набор API 1.3 удостоверений в коде надстройки Outlook, проверка, если он поддерживается путем вызова isSetSupported('IdentityAPI', '1.3'). Его объявление в манифесте надстройки Outlook не поддерживается. Также можно определить, поддерживается ли API, проверив, не undefined ли он. Подробнее см. в статье Использование API из наборов требования более поздних версий.
4 Сведения о минимальных поддерживаемых версиях для последних наборов требований в классической версии Outlook для Windows с подпиской Microsoft 365 или розничной бессрочной лицензией см. в статье Поддержка версий для наборов требований в классической версии Outlook для Windows.
5 Поддержка версии 1.4 в корпоративной лицензированной бессрочной Outlook 2016 была добавлена в рамках обновления Office 2016 (KB4022223) от 3 июля 2018 г.
6 Поддержка нового пользовательского интерфейса Mac доступна в Outlook версии 16.38.506. Дополнительные сведения см. в разделе Поддержка надстроек в Outlook в новом интерфейсе Mac.
7 Хотя классический Outlook для Mac не поддерживает набор обязательных почтовых ящиков 1.9, он поддерживает набор требований DialogApi 1.2. Сведения о минимально поддерживаемой версии и сборке см. в разделе Наборы обязательных элементов API Диалога.
8 В настоящее время при разработке и реализации надстроек для мобильных клиентов существуют дополнительные рекомендации. Дополнительные сведения см. в разделе Рекомендации по коду при добавлении поддержки команд надстроек в Outlook на мобильных устройствах. Хотя Outlook в Android и в iOS поддерживает набор требований 1.5, ваша мобильная надстройка теперь может реализовать некоторые API из более поздних наборов требований. Дополнительные сведения о том, какие API поддерживаются в Outlook Mobile, см. в статье API JavaScript, поддерживаемые в Outlook на мобильных устройствах.
Совет
Классическую и современную версии Outlook в веб-браузере можно различить по внешнему виду панели инструментов почтового ящика.
современная версия
классическая версия
Поддержка версий для наборов требований в классической версии Outlook в Windows
В следующей таблице приведена поддержка версий для более поздних наборов обязательных почтовых ящиков в классической версии 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) |
| 1.14 | Версия 2404 (сборка 17530.15000) |
Дополнительные сведения о версии клиента см. на странице журнала обновлений Для Microsoft 365 или Office 2024 и на странице о том, как найти версию клиента Office и канал обновления.
Ссылка на рабочую библиотеку API JavaScript для Office
Чтобы использовать API в любом из нумерованных наборов обязательных элементов, следует ссылаться на рабочую библиотеку в сети доставки содержимого (CDN) Office.js. Сведения об использовании api предварительной версии см. в разделе Тестирование api предварительной версии.
Интерфейсы API тестовой предварительной версии
Новые API JavaScript для Outlook сначала выпускаются в "предварительной версии", а затем становятся частью определенного нумерованного набора обязательных элементов после выполнения достаточного тестирования и получения отзывов пользователей. Чтобы отправить отзыв о предварительной версии API, используйте способ обратной связи, представленный в конце веб-страницы с описанием API.
Примечание.
Api предварительной версии могут быть изменены и не предназначены для использования в рабочей среде.
Дополнительные сведения о предварительных версиях интерфейсов API см. в статье Предварительная версия набора обязательных элементов API для Outlook.
Office Add-ins