Поделиться через

API надстроек Outlook

  • Статья

Чтобы использовать API-интерфейсы в надстройке Outlook, необходимо указать расположение библиотеки Office.js, набор требований, схему и разрешения. В основном вы будете использовать API JavaScript для Office, предоставляемые через объект Mailbox .

Библиотека Office.js

Для взаимодействия с API надстройки Outlook необходимо использовать API JavaScript в Office.js. Сеть доставки содержимого (CDN) для библиотеки — https://appsforoffice.microsoft.com/lib/1.1/hosted/Office.js. Надстройки, отправляемые в AppSource, должны ссылаться на библиотеку Office.js в этой сети CDN. Нельзя использовать локальную ссылку.

Добавьте ссылку на сеть CDN в теге <script>, вложенном в тег <head>, на веб-странице (HTML-, ASPX- или PHP-файле), где определяется пользовательский интерфейс надстройки.

<script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/Office.js" type="text/javascript"></script>

При добавлении новых API-интерфейсов не будет меняться URL-адрес Office.js. Мы укажем другую версию в URL-адресе, только если изменится поведение API.

Важно!

При разработке надстройки для любого клиентского приложения Office ссылайся на API JavaScript для Office из <head> раздела страницы. Это гарантирует, что API полностью инициализируется раньше всех элементов body.

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

Все API Outlook относятся к набору обязательных почтовых ящиков. Существуют разные версии набора обязательных элементов Mailbox. Каждый новый набор API, который мы выпускаем, относится к более высокой версии набора. Не все клиенты Outlook поддерживают самый новый набор API при их выпуске, но если для клиента Outlook объявлена поддержка определенного набора обязательных элементов, то он поддерживает все API из этого набора.

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

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

Чтобы проверить доступность API-интерфейсов из набора требований, версия которого выше указанной в манифесте, вы можете использовать стандартный код JavaScript:

if (item.somePropertyOrFunction) {
   item.somePropertyOrFunction...  
}

Примечание.

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

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

  • Манифест только надстройки<: используйте элемент Requirements>. Обратите внимание, что дочерний <элемент Methods элемента Requirements> не поддерживается в надстройках Outlook, поэтому вы не можете объявить поддержку определенных методов.><
  • Унифицированный манифест для Microsoft 365: используйте свойство extensions.capabilities.

Дополнительные сведения см. в разделах Манифесты надстроек Office и Общие сведения о наборах требований API Outlook.

Разрешения

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

Существует четыре уровня разрешений; ограниченный, считываемый элемент, элемент чтения и записи, а также почтовый ящик для чтения и записи. Для получения дополнительных сведений. Дополнительные сведения см. в разделе Общие сведения о разрешениях надстройки Outlook.

Объект Mailbox

Надстройки Outlook, в основном, используют набор API, предоставляемый через объект Mailbox. Чтобы получить доступ к объектам и членам, специально используемым в надстройках Outlook, например к объекту Item , используйте свойство mailbox объекта Context для доступа к объекту Mailbox , как показано в следующей строке кода.

// Access the Item object.
const item = Office.context.mailbox.item;

Важно!

При вызове Office.context.mailbox.item сообщения обратите внимание, что область чтения в клиенте Outlook должна быть включена. Инструкции по настройке области чтения см. в статье Использование и настройка области чтения для предварительного просмотра сообщений.

Кроме того, надстройки Outlook могут использовать следующие объекты.

  • Объект Office для инициализации.

  • Объект Context для получения доступа к контенту и отображения языковых свойств.

Сведения об использовании JavaScript в надстройках Outlook см. в разделе Надстройки Outlook. Сведения об API JavaScript для Outlook см. на странице справочника по API Outlook .

См. также