Office.Mailbox interface

Предоставляет доступ к объектной модели надстроек Microsoft Outlook.

Основные свойства:

diagnostics : предоставляет диагностические сведения для надстройки Outlook.
item : предоставляет методы и свойства для доступа к сообщению или встрече в надстройке Outlook.
userProfile : предоставляет сведения о пользователе в надстройке Outlook.

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

Свойства

diagnostics	Предоставляет надстройке Outlook диагностические сведения. Сведения о доступных диагностических свойствах см. в разделе Office.Diagnostics.
ewsUrl	Получает URL-адрес конечной точки веб-служб Exchange (EWS) для этой учетной записи электронной почты.
item	Элемент почтового ящика. В зависимости от контекста, в котором открыта надстройка, тип элемента может отличаться. Если вы хотите, чтобы функция IntelliSense использовалась только для определенного типа или режима, приведите этот элемент к одному из следующих значений. MessageCompose, MessageRead, AppointmentCompose, AppointmentRead Важно! Обратите внимание, что при вызове `Office.context.mailbox.item` сообщения следует помнить, что область чтения в клиенте Outlook должна быть включена. Рекомендации по настройке области чтения см. в статье "Использование и настройка области чтения для предварительного просмотра сообщений". `item` Может иметь значение NULL, если надстройка поддерживает закрепление области задач. Дополнительные сведения об обращении см. в статье "Реализация закрепленной области задач в Outlook".
masterCategories	Получает объект, предоставляющий методы для управления категориями master списке, связанном с почтовым ящиком.
restUrl	Возвращает URL-адрес конечной точки REST для этой учетной записи электронной почты.
userProfile	Сведения о пользователе, связанном с почтовым ящиком. К ним относятся тип учетной записи, отображаемое имя, адрес электронной почты и часовой пояс. Дополнительные сведения см. в разделе Office.UserProfile

Методы

addHandlerAsync(eventType, handler, options, callback)	Добавляет обработчик для поддерживаемого события. События доступны только в надстройках области задач.
addHandlerAsync(eventType, handler, callback)	Добавляет обработчик для поддерживаемого события. События доступны только в надстройках области задач.
convertToEwsId(id, restVersion)	Преобразует поддерживаемый идентификатор в формат веб-служб Exchange (EWS).
convertToLocalClientTime(timeValue)	Получает словарь, содержащий сведения о локальном времени клиента. Часовой пояс, используемый клиентом Outlook, зависит от платформы. Outlook в классической версии Windows (классическая) и Mac использует часовой пояс клиентского компьютера. Outlook в Интернете и новый Outlook для Windows используют часовой пояс, установленный в Центре администраторов Exchange (EAC). Значения даты и времени должны обрабатываться таким образом, чтобы значения, отображаемые в интерфейсе пользователя, всегда согласовывались с часовым поясом, ожидаемым пользователем. В Outlook для Windows (классическая версия) и на Mac этот `convertToLocalClientTime` метод возвращает объект словаря со значениями, соответствующими часовому поясу клиентского компьютера. В Outlook в Интернете и новом Outlook для Windows метод `convertToLocalClientTime` возвращает объект словаря со значениями, установленными в часовой пояс, указанный в EAC.
convertToRestId(id, restVersion)	Преобразует поддерживаемый идентификатор в формат REST.
convertToUtcClientTime(input)	Получает `Date` объект из словаря, содержащий сведения о времени. Этот `convertToUtcClientTime` метод преобразует словарь, содержащий местную дату и время, в `Date` объект с правильными значениями местной даты и времени.
displayAppointmentForm(itemId)	Отображает имеющуюся встречу из календаря. Этот `displayAppointmentForm` метод открывает существующую встречу в календаре в новом окне на рабочем столе. В Outlook для Mac этот метод можно использовать для отображения одной встречи, не входящей в повторяющийся ряд, или master встречи из повторяющегося ряда. Однако невозможно отобразить экземпляр ряда, так как нет доступа к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая область, и сообщение об ошибке не вернется.
displayAppointmentFormAsync(itemId, options, callback)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече. В Outlook для Mac этот метод можно использовать для отображения одной встречи, не входящей в повторяющийся ряд, или master встречи из повторяющегося ряда. Однако невозможно отобразить экземпляр ряда, так как нет доступа к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая область, и сообщение об ошибке не вернется. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayAppointmentFormAsync(itemId, callback)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече. В Outlook для Mac этот метод можно использовать для отображения одной встречи, не входящей в повторяющийся ряд, или master встречи из повторяющегося ряда. Однако невозможно отобразить экземпляр ряда, так как нет доступа к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая область, и сообщение об ошибке не вернется. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayMessageForm(itemId)	Отображает имеющееся сообщение. Метод `displayMessageForm` открывает существующее сообщение в новом окне на рабочем столе. В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере и сообщение об ошибке не будет возвращено.
displayMessageFormAsync(itemId, options, callback)	Отображает имеющееся сообщение. Метод `displayMessageFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение. В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере и не будет возвращено сообщение об ошибке. Не используйте метод "или`displayMessageFormAsync`" `displayMessageForm` с itemId, представляющим встречу. Используйте метод "или`displayAppointmentFormAsync`" `displayAppointmentForm` для отображения существующей встречи и`displayNewAppointmentForm`/или `displayNewAppointmentFormAsync` для отображения формы для создания новой встречи. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayMessageFormAsync(itemId, callback)	Отображает имеющееся сообщение. Метод `displayMessageFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение. В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере и не будет возвращено сообщение об ошибке. Не используйте метод "или`displayMessageFormAsync`" `displayMessageForm` с itemId, представляющим встречу. Используйте метод "или`displayAppointmentFormAsync`" `displayAppointmentForm` для отображения существующей встречи и`displayNewAppointmentForm`/или `displayNewAppointmentFormAsync` для отображения формы для создания новой встречи. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewAppointmentForm(parameters)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentForm` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете и новом Outlook для Windows этим методом всегда отображается форма с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить . Если вы укажете участников, форма будет включать участников и кнопку Отправить. В Outlook для Windows (классическая версия) и на Mac, если указать участников или ресурсы в параметре `requiredAttendees`, `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
displayNewAppointmentFormAsync(parameters, options, callback)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentFormAsync` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете и новом Outlook для Windows этим методом всегда отображается форма с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить. В Outlook для Windows (классическая версия) и на Mac, если указать участников или ресурсы в параметре `requiredAttendees`, `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewAppointmentFormAsync(parameters, callback)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentFormAsync` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете и новом Outlook для Windows этим методом всегда отображается форма с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить. В Outlook для Windows (классическая версия) и на Mac, если указать участников или ресурсы в параметре `requiredAttendees`, `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewMessageForm(parameters)	Отображает форму для создания сообщения. Метод `displayNewMessageForm` открывает форму, которая позволяет пользователю создать сообщение. Если параметры указаны, поля формы сообщения автоматически заполняются содержимым параметров. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
displayNewMessageFormAsync(parameters, options, callback)	Отображает форму для создания сообщения. Метод `displayNewMessageFormAsync` открывает форму, которая позволяет пользователю создать сообщение. Если параметры указаны, поля формы сообщения автоматически заполняются содержимым параметров. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
displayNewMessageFormAsync(parameters, callback)	Отображает форму для создания сообщения. Метод `displayNewMessageFormAsync` открывает форму, которая позволяет пользователю создать сообщение. Если параметры указаны, поля формы сообщения автоматически заполняются содержимым параметров. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
getCallbackTokenAsync(options, callback)	Получает строку, содержащую маркер, используемый для вызова REST API или веб-служб Exchange (EWS). Метод `getCallbackTokenAsync` совершает асинхронный вызов, чтобы получить непрозрачный токен с сервера Exchange Server, на котором размещен почтовый ящик пользователя. Время существования маркера обратного вызова составляет 5 минут. Маркер возвращается в виде строки в свойстве `asyncResult.value` .
getCallbackTokenAsync(callback, userContext)	Получает строку, содержащую маркер, используемый для получения вложения или элемента с Exchange Server. Метод `getCallbackTokenAsync` совершает асинхронный вызов, чтобы получить непрозрачный токен с сервера Exchange Server, на котором размещен почтовый ящик пользователя. Время существования маркера обратного вызова составляет 5 минут. Маркер возвращается в виде строки в свойстве `asyncResult.value` .
getIsIdentityManaged()	Возвращает значение true, если текущий почтовый ящик управляется службой Microsoft Intune.
getIsOpenFromLocationAllowed(openLocation)	Возвращает значение true, если политика управления мобильными приложениями (MAM) организации Intune позволяет надстройке получать доступ к данным из указанного расположения.
getIsSaveToLocationAllowed(saveLocation)	Возвращает значение true, если политика управления мобильными приложениями (MAM) организации Intune позволяет надстройке сохранять данные в указанное расположение.
getSelectedItemsAsync(options, callback)	Получает выбранные сообщения, с которыми надстройка может активировать и выполнить операции. Надстройка может активироваться максимум с 100 сообщениями одновременно. Дополнительные сведения о выборе нескольких элементов см. в статье Активация надстройки Outlook для нескольких сообщений.
getSelectedItemsAsync(callback)	Получает выбранные сообщения, с которыми надстройка может активировать и выполнить операции. Надстройка может активироваться максимум с 100 сообщениями одновременно. Дополнительные сведения о выборе нескольких элементов см. в статье Активация надстройки Outlook для нескольких сообщений.
getUserIdentityTokenAsync(callback, userContext)	Получает маркер, идентифицирующий пользователя и надстройку Office. Маркер возвращается в виде строки в свойстве `asyncResult.value` .
loadItemByIdAsync(itemId, options, callback)	Загружает один элемент почты по идентификатору веб-служб Exchange (EWS). Затем получает объект, предоставляющий свойства и методы загруженного элемента.
loadItemByIdAsync(itemId, callback)	Загружает один элемент почты по идентификатору веб-служб Exchange (EWS). Затем получает объект, предоставляющий свойства и методы загруженного элемента.
makeEwsRequestAsync(data, callback, userContext)	Делает асинхронный запрос к службе веб-служб Exchange (EWS) на сервере Exchange, на котором размещен почтовый ящик пользователя. Метод `makeEwsRequestAsync` отправляет запрос EWS от имени надстройки в Exchange.
removeHandlerAsync(eventType, options, callback)	Удаляет обработчиков для поддерживаемого типа события. События доступны только в надстройках области задач.
removeHandlerAsync(eventType, callback)	Удаляет обработчиков для поддерживаемого типа события. События доступны только в надстройках области задач.

diagnostics

Предоставляет надстройке Outlook диагностические сведения.

Сведения о доступных диагностических свойствах см. в разделе Office.Diagnostics.

diagnostics: Diagnostics;

Значение свойства

Office.Diagnostics

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-diagnostic-information.yaml

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

if (Office.context.requirements.isSetSupported("Mailbox", "1.16")) {
  const ewsTokenStatus = diagnostics.ews;
  ewsTokenStatus.getTokenStatusAsync({ isRest: false }, (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
      console.log(result.error.message);
      return;
    }

    const status = result.value;
    switch (status) {
      case Office.MailboxEnums.TokenStatus.Enabled:
        console.log("EWS token status: EWS callback tokens are enabled.");
        break;
      case Office.MailboxEnums.TokenStatus.Disabled:
        console.log("EWS token status: EWS callback tokens are disabled.");
        break;
      case Office.MailboxEnums.TokenStatus.Removed:
        console.log("EWS token status: The organization has an Exchange Online environment. Legacy Exchange tokens are no longer supported.");
        break;
    }
  });
}

ewsUrl

Получает URL-адрес конечной точки веб-служб Exchange (EWS) для этой учетной записи электронной почты.

ewsUrl: string;

Значение свойства

string

Для вызова ewsUrl участника в режиме чтения приложение должно иметь разрешение на чтение, указанное в его манифесте.
В режиме создания необходимо вызвать метод, saveAsync прежде чем можно будет использовать ewsUrl элемент. Приложение должно иметь разрешения на чтение и запись элементов , чтобы вызывать этот saveAsync метод.
Это свойство не поддерживается в Outlook для Android и в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.
Удаленная служба может использовать значение ewsUrl, чтобы выполнять вызовы EWS для почтового ящика пользователя. Например, можно создать удаленную службу для получения вложений из выбранного элемента.

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

item

Элемент почтового ящика. В зависимости от контекста, в котором открыта надстройка, тип элемента может отличаться. Если вы хотите, чтобы функция IntelliSense использовалась только для определенного типа или режима, приведите этот элемент к одному из следующих значений.

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Важно!

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

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

Значение свойства

Office.Item & Office.ItemCompose & Office.ItemRead & Office.Message & Office.MessageCompose & Office.MessageRead & Office.Appointment & Office.AppointmentCompose & Office.AppointmentRead

masterCategories

Получает объект, предоставляющий методы для управления категориями master списке, связанном с почтовым ящиком.

masterCategories: MasterCategories;

Значение свойства

Office.MasterCategories

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});

...

const masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

restUrl

Возвращает URL-адрес конечной точки REST для этой учетной записи электронной почты.

restUrl: string;

Значение свойства

string

Конечные точки Outlook REST версии 2.0 и бета-версии теперь устарели. Однако выпущенные в частном порядке надстройки, размещенные в AppSource, могут использовать службу REST до окончания расширенной поддержки Outlook 2019 14 октября 2025 г. Трафик от этих надстроек автоматически идентифицируется для исключения. Это исключение также распространяется на новые надстройки, разработанные после 31 марта 2024 года. Хотя надстройки могут использовать службу REST до 2025 года, мы настоятельно рекомендуем перенести надстройки, чтобы использовать Microsoft Graph. Инструкции см. в статье Сравнение конечных точек API REST в Microsoft Graph и Outlook.
Для вызова restUrl участника в режиме чтения ваша надстройка должна иметь разрешение на чтение элемента, указанное в ее манифесте.
В режиме создания необходимо вызвать метод, saveAsync прежде чем можно будет использовать restUrl элемент. Чтобы вызвать saveAsync этот метод, у надстройки должны быть разрешения на чтение и запись. Однако в делегированных или общих сценариях вместо этого следует использовать targetRestUrl свойство объекта SharedProperties (введенное в наборе требований 1.8). Дополнительные сведения см. в статье об общих папках и общем почтовом ящике .

Примеры

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

userProfile

Сведения о пользователе, связанном с почтовым ящиком. К ним относятся тип учетной записи, отображаемое имя, адрес электронной почты и часовой пояс.

Дополнительные сведения см. в разделе Office.UserProfile

userProfile: UserProfile;

Значение свойства

Office.UserProfile

addHandlerAsync(eventType, handler, options, callback)

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

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType | string

Событие, которое должно вызвать обработчик.

handler: any

Функция для обработки события. Функция должна принимать один параметр, представляющий собой объектный литерал. Свойство type параметра будет соответствовать параметру, eventType переданному в addHandlerAsync.

options: Office.AsyncContextOptions

Предоставляет возможность сохранения контекстных данных любого типа без изменений для использования в обратном вызове.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. После завершения метода вызывается функция, переданная в параметре callback , с одним параметром типа Office.AsyncResult.

Возвращаемое значение

void

Событие	Описание	Набор минимальных требований
`DragAndDropEvent`	Вложение сообщения или файла в окне клиента Outlook перетаскивается, а затем опускается в область задач надстройки. Это событие поддерживается только в Outlook в Интернете и новом Outlook для Windows.	1.5
`ItemChanged`	При закреплении области задач выбран другой элемент Outlook для просмотра.	1.5
`OfficeThemeChanged`	В Outlook изменена тема OfficeTheme.	1.14
`SelectedItemsChanged`	Выбрано или снято выделение одного или нескольких сообщений.	1.13

Примеры

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

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

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType | string

Событие, которое должно вызвать обработчик.

handler: any

Функция для обработки события. Функция должна принимать один параметр, представляющий собой объектный литерал. Свойство type параметра будет соответствовать параметру, eventType переданному в addHandlerAsync.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. После завершения метода вызывается функция, переданная в параметре callback , с одним параметром типа Office.AsyncResult.

Возвращаемое значение

void

Событие	Описание	Набор минимальных требований
`DragAndDropEvent`	Вложение сообщения или файла в окне клиента Outlook перетаскивается, а затем опускается в область задач надстройки. Это событие поддерживается только в Outlook в Интернете и новом Outlook для Windows.	1.5
`ItemChanged`	При закреплении области задач выбран другой элемент Outlook для просмотра.	1.5
`OfficeThemeChanged`	В Outlook изменена тема OfficeTheme.	1.14
`SelectedItemsChanged`	Выбрано или снято выделение одного или нескольких сообщений.	1.13

convertToEwsId(id, restVersion)

Преобразует поддерживаемый идентификатор в формат веб-служб Exchange (EWS).

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Параметры

id: string

Идентификатор, который нужно преобразовать в формат EWS. Строка может быть идентификатором элемента, отформатированным для REST API Outlook, или идентификатором беседы, полученным из Office.context.mailbox.item.conversationId.

restVersion: Office.MailboxEnums.RestVersion | string

Значение, определяющее версию REST API для Outlook, которая используется для извлечения идентификатора элемента.

Возвращаемое значение

string

Устаревшие маркеры удостоверений пользователей Exchange Online и маркеры обратного вызова больше не поддерживаются и отключены во всех клиентах Microsoft 365. Если для надстройки Outlook требуется делегированный доступ или удостоверение пользователя, рекомендуется использовать MSAL (библиотеку проверки подлинности Майкрософт) и проверку подлинности вложенных приложений (NAA). Маркеры удостоверений пользователей Exchange по-прежнему поддерживаются для локальной службы Exchange.
Этот способ не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.
Идентификаторы элементов, полученные с помощью REST API (например, Microsoft Graph), имеют формат, отличный от формата, используемого EWS. Метод convertToEwsId преобразовывает идентификатор в формате REST в формат EWS.

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

Получает словарь, содержащий сведения о локальном времени клиента.

Часовой пояс, используемый клиентом Outlook, зависит от платформы. Outlook в классической версии Windows (классическая) и Mac использует часовой пояс клиентского компьютера. Outlook в Интернете и новый Outlook для Windows используют часовой пояс, установленный в Центре администраторов Exchange (EAC). Значения даты и времени должны обрабатываться таким образом, чтобы значения, отображаемые в интерфейсе пользователя, всегда согласовывались с часовым поясом, ожидаемым пользователем.

В Outlook для Windows (классическая версия) и на Mac этот convertToLocalClientTime метод возвращает объект словаря со значениями, соответствующими часовому поясу клиентского компьютера. В Outlook в Интернете и новом Outlook для Windows метод convertToLocalClientTime возвращает объект словаря со значениями, установленными в часовой пояс, указанный в EAC.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Параметры

timeValue: Date

Объект Date.

Возвращаемое значение

Office.LocalClientTime

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-start-read.yaml

const time = Office.context.mailbox.item.start;
const localTime = Office.context.mailbox.convertToLocalClientTime(time);
console.log(`Appointment starts (local): ${localTime.month + 1}/${localTime.date}/${localTime.year}, ${localTime.hours}:${localTime.minutes}:${localTime.seconds}`);

convertToRestId(id, restVersion)

Преобразует поддерживаемый идентификатор в формат REST.

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Параметры

id: string

Идентификатор, который нужно преобразовать в формат REST. Эта строка может быть идентификатором элемента, отформатированным для EWS, который обычно извлекается из Office.context.mailbox.item.itemId, идентификатором беседы, полученным изOffice.context.mailbox.item.conversationId , или идентификатором ряда, полученным из Office.context.mailbox.item.seriesId.

restVersion: Office.MailboxEnums.RestVersion | string

Значение, указывающее версию REST API Outlook, используемую с преобразованным идентификатором.

Возвращаемое значение

string

Этот способ не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.
Идентификаторы элементов, полученные через веб-службы Exchange (EWS) или через свойство, itemId используют формат, отличный от формата, используемого REST API (например, Microsoft Graph). Метод convertToRestId преобразовывает идентификатор в формате EWS в формат REST.

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToUtcClientTime(input)

Получает Date объект из словаря, содержащий сведения о времени.

Этот convertToUtcClientTime метод преобразует словарь, содержащий местную дату и время, в Date объект с правильными значениями местной даты и времени.

convertToUtcClientTime(input: LocalClientTime): Date;

Параметры

input: Office.LocalClientTime

Значение локального времени для преобразования.

Возвращаемое значение

Date

Объект Date со временем в формате UTC.

Примеры

// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

displayAppointmentForm(itemId)

Отображает имеющуюся встречу из календаря.

Этот displayAppointmentForm метод открывает существующую встречу в календаре в новом окне на рабочем столе.

В Outlook для Mac этот метод можно использовать для отображения одной встречи, не входящей в повторяющийся ряд, или master встречи из повторяющегося ряда. Однако невозможно отобразить экземпляр ряда, так как нет доступа к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда.

В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов.

Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая область, и сообщение об ошибке не вернется.

displayAppointmentForm(itemId: string): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующей встречи в календаре.

Возвращаемое значение

void

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

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;
Office.context.mailbox.displayAppointmentForm(itemId);

displayAppointmentFormAsync(itemId, options, callback)

Отображает имеющуюся встречу из календаря.

Метод displayAppointmentFormAsync открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече.

В Outlook для Mac этот метод можно использовать для отображения одной встречи, не входящей в повторяющийся ряд, или master встречи из повторяющегося ряда. Однако невозможно отобразить экземпляр ряда, так как нет доступа к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда.

В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов.

Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая область, и сообщение об ошибке не вернется.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

displayAppointmentFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующей встречи в календаре.

options: Office.AsyncContextOptions

Объектный литерал, содержащий одно или несколько из следующих свойств:- asyncContext: Разработчики могут предоставить любой объект, к которому они хотят получить доступ, в функции обратного вызова.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayAppointmentFormAsync(itemId, function(asyncResult) {
  console.log("Result: " + JSON.stringify(asyncResult));
});

displayAppointmentFormAsync(itemId, callback)

Отображает имеющуюся встречу из календаря.

Метод displayAppointmentFormAsync открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече.

В Outlook для Mac этот метод можно использовать для отображения одной встречи, не входящей в повторяющийся ряд, или master встречи из повторяющегося ряда. Однако невозможно отобразить экземпляр ряда, так как нет доступа к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда.

В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов.

Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая область, и сообщение об ошибке не вернется.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

displayAppointmentFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующей встречи в календаре.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

displayMessageForm(itemId)

Отображает имеющееся сообщение.

Метод displayMessageForm открывает существующее сообщение в новом окне на рабочем столе.

В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов.

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

displayMessageForm(itemId: string): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующего сообщения.

Возвращаемое значение

void

Этот способ не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.
Не используйте displayMessageForm идентификатор с элементомИд, представляющий встречу. Используйте метод displayAppointmentForm, чтобы отобразить сведения о существующей встрече, а метод displayNewAppointmentForm— для отображения формы создания встречи.

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;
Office.context.mailbox.displayMessageForm(itemId);

displayMessageFormAsync(itemId, options, callback)

Отображает имеющееся сообщение.

Метод displayMessageFormAsync открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение.

В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов.

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

Не используйте метод "илиdisplayMessageFormAsync" displayMessageForm с itemId, представляющим встречу. Используйте метод "илиdisplayAppointmentFormAsync" displayAppointmentForm для отображения существующей встречи иdisplayNewAppointmentForm/или displayNewAppointmentFormAsync для отображения формы для создания новой встречи.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

displayMessageFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующего сообщения.

options: Office.AsyncContextOptions

Объектный литерал, содержащий одно или несколько из следующих свойств:- asyncContext: Разработчики могут предоставить любой объект, к которому они хотят получить доступ, в функции обратного вызова.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = (document.getElementById("itemId") as HTMLInputElement).value;

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayMessageFormAsync(itemId, function (asyncResult) {
 console.log("Result: " + JSON.stringify(asyncResult));
});

displayMessageFormAsync(itemId, callback)

Отображает имеющееся сообщение.

Метод displayMessageFormAsync открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение.

В Outlook в Интернете и новом Outlook для Windows указанная форма открывается только в том случае, если текст формы не превышает 32 тыс. символов.

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

Не используйте метод "илиdisplayMessageFormAsync" displayMessageForm с itemId, представляющим встречу. Используйте метод "илиdisplayAppointmentFormAsync" displayAppointmentForm для отображения существующей встречи иdisplayNewAppointmentForm/или displayNewAppointmentFormAsync для отображения формы для создания новой встречи.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

displayMessageFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующего сообщения.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

displayNewAppointmentForm(parameters)

Отображает форму для создания новой встречи в календаре.

Метод displayNewAppointmentForm открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым.

В Outlook в Интернете и новом Outlook для Windows этим методом всегда отображается форма с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить . Если вы укажете участников, форма будет включать участников и кнопку Отправить.

В Outlook для Windows (классическая версия) и на Mac, если указать участников или ресурсы в параметре requiredAttendees, optionalAttendeesили resources , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть.

Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Параметры

parameters: Office.AppointmentForm

Описание AppointmentForm нового назначения. Все свойства являются необязательными.

Возвращаемое значение

void

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

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm({
  requiredAttendees: ["bob@contoso.com"] as any,
  optionalAttendees: ["sam@contoso.com"] as any,
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"] as any,
  body: "Hello World!"
});

displayNewAppointmentFormAsync(parameters, options, callback)

Отображает форму для создания новой встречи в календаре.

Метод displayNewAppointmentFormAsync открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым.

В Outlook в Интернете и новом Outlook для Windows этим методом всегда отображается форма с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить.

В Outlook для Windows (классическая версия) и на Mac, если указать участников или ресурсы в параметре requiredAttendees, optionalAttendeesили resources , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть.

Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

parameters: Office.AppointmentForm

Описание AppointmentForm нового назначения. Все свойства являются необязательными.

options: Office.AsyncContextOptions

Объектный литерал, содержащий одно или несколько из следующих свойств:- asyncContext: Разработчики могут предоставить любой объект, к которому они хотят получить доступ, в функции обратного вызова.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new appointment form has been created.
Office.context.mailbox.displayNewAppointmentFormAsync(
  {
    requiredAttendees: ["bob@contoso.com"] as any,
    optionalAttendees: ["sam@contoso.com"] as any,
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"] as any,
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewAppointmentFormAsync(parameters, callback)

Отображает форму для создания новой встречи в календаре.

Метод displayNewAppointmentFormAsync открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым.

В Outlook в Интернете и новом Outlook для Windows этим методом всегда отображается форма с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить.

В Outlook для Windows (классическая версия) и на Mac, если указать участников или ресурсы в параметре requiredAttendees, optionalAttendeesили resources , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть.

Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

parameters: Office.AppointmentForm

Описание AppointmentForm нового назначения. Все свойства являются необязательными.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

displayNewMessageForm(parameters)

Отображает форму для создания сообщения.

Метод displayNewMessageForm открывает форму, которая позволяет пользователю создать сообщение. Если параметры указаны, поля формы сообщения автоматически заполняются содержимым параметров.

Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.

displayNewMessageForm(parameters: MessageForm): void;

Параметры

parameters: Office.MessageForm

Объект MessageForm , содержащий содержимое, которое нужно добавить в форму для создания сообщения. Все свойства являются необязательными.

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
  ccRecipients: ["sam@contoso.com"],
  subject: "Outlook add-ins are cool!",
  htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
  attachments: [
    {
      type: "file",
      name: "image.png",
      url: "https://i.imgur.com/9S36xvA.jpg",
      isInline: true
    }
  ]
});

displayNewMessageFormAsync(parameters, options, callback)

Отображает форму для создания сообщения.

Метод displayNewMessageFormAsync открывает форму, которая позволяет пользователю создать сообщение. Если параметры указаны, поля формы сообщения автоматически заполняются содержимым параметров.

Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.

displayNewMessageFormAsync(parameters: MessageForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

parameters: Office.MessageForm

Объект MessageForm , содержащий содержимое, которое нужно добавить в форму для создания сообщения. Все свойства являются необязательными.

options: Office.AsyncContextOptions

Объектный литерал, содержащий одно или несколько из следующих свойств:- asyncContext: Разработчики могут предоставить любой объект, к которому они хотят получить доступ, в функции обратного вызова.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new message form has been created.
Office.context.mailbox.displayNewMessageFormAsync(
  {
    toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
    ccRecipients: ["sam@contoso.com"],
    subject: "Outlook add-ins are cool!",
    htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
    attachments: [
      {
        type: "file",
        name: "image.png",
        url: "https://i.imgur.com/9S36xvA.jpg",
        isInline: true
      }
    ]
  },
  (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewMessageFormAsync(parameters, callback)

Отображает форму для создания сообщения.

Метод displayNewMessageFormAsync открывает форму, которая позволяет пользователю создать сообщение. Если параметры указаны, поля формы сообщения автоматически заполняются содержимым параметров.

Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.

displayNewMessageFormAsync(parameters: MessageForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

parameters: Office.MessageForm

Объект MessageForm , содержащий содержимое, которое нужно добавить в форму для создания сообщения. Все свойства являются необязательными.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult .

Возвращаемое значение

void

getCallbackTokenAsync(options, callback)

Получает строку, содержащую маркер, используемый для вызова REST API или веб-служб Exchange (EWS).

Метод getCallbackTokenAsync совершает асинхронный вызов, чтобы получить непрозрачный токен с сервера Exchange Server, на котором размещен почтовый ящик пользователя. Время существования маркера обратного вызова составляет 5 минут.

Маркер возвращается в виде строки в свойстве asyncResult.value .

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Параметры

options: Office.AsyncContextOptions & { isRest?: boolean }

Объектный литерал, содержащий одно или несколько из следующих свойств:- isRest: Определяет, будет ли предоставленный маркер использоваться для REST API Outlook или веб-служб Exchange. Значение по умолчанию: false. asyncContext : любые данные состояния, передаваемые асинхронному методу.

callback: (asyncResult: Office.AsyncResult<string>) => void

Когда метод завершается, функция, переданная в параметре обратного вызова, вызывается с одним параметром типа Office.AsyncResult. Маркер возвращается в виде строки в свойстве asyncResult.value . При наличии ошибки свойства asyncResult.error и asyncResult.diagnostics могут предоставлять дополнительные сведения.

Возвращаемое значение

void

Устаревшие маркеры удостоверений пользователей Exchange Online и маркеры обратного вызова больше не поддерживаются и отключены во всех клиентах Microsoft 365. Если для надстройки Outlook требуется делегированный доступ или удостоверение пользователя, рекомендуется использовать MSAL (библиотеку проверки подлинности Майкрософт) и проверку подлинности вложенных приложений (NAA). Маркеры удостоверений пользователей Exchange по-прежнему поддерживаются для локальной службы Exchange.
Конечные точки Outlook REST версии 2.0 и бета-версии теперь устарели. Однако выпущенные в частном порядке надстройки, размещенные в AppSource, могут использовать службу REST до окончания расширенной поддержки Outlook 2019 14 октября 2025 г. Трафик от этих надстроек автоматически идентифицируется для исключения. Это исключение также распространяется на новые надстройки, разработанные после 31 марта 2024 года. Хотя надстройки могут использовать службу REST до 2025 года, мы настоятельно рекомендуем перенести надстройки, чтобы использовать Microsoft Graph. Инструкции см. в статье Сравнение конечных точек API REST в Microsoft Graph и Outlook.
Чтобы определить, доступны ли маркеры REST или EWS в организации, вызовите Office.context.mailbox.diagnostics.ews.getTokenStatusAsync. Этот getTokenStatusAsync метод доступен для предварительного просмотра в Outlook в Интернете и в Windows (новая и классическая (версия 2510, сборка 19328.20000 и более поздние версии)).
Этот способ не поддерживается, если надстройка загружается в почтовый ящик Outlook.com или Gmail.
Этот способ поддерживается только в режиме чтения в Outlook для Android и iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.
Операции EWS не поддерживаются в надстройках, работающих в Outlook на iOS и Android. Маркер REST всегда возвращается в клиентах Outlook Mobile, даже если options.isRest ему присвоено значение false.
Для вызова getCallbackTokenAsync метода в режиме чтения требуется минимальный уровень разрешений для элемента чтения.
Вызов getCallbackTokenAsync метода в режиме создания требует сохранения элемента. Метод saveAsync требует минимального уровня разрешений для элемента чтения/записи.
Рекомендации по сценариям делегирования или общего доступа см. в статье об общих папках и общем почтовом ящике .

Маркеры REST

При запросе маркера REST (options.isRest = true), полученный маркер не будет работать для проверки подлинности вызовов EWS. В областях маркер будет ограничен доступом только для чтения к текущему элементу и его вложениям, если только в манифесте надстройки не указано разрешение на чтение и запись. Если указано разрешение на чтение и запись для почтового ящика , результирующий маркер предоставит доступ на чтение и запись к почте, календарю и контактам, включая возможность отправки почты.

С помощью свойства restUrl надстройка должна определить правильный URL-адрес для вызовов REST API.

Этот API работает в следующих областях.

Mail.ReadWrite
Mail.Send
Calendars.ReadWrite
Contacts.ReadWrite

Маркеры EWS

При запросе маркера EWS (options.isRest = false) полученный маркер не будет работать для проверки подлинности вызовов REST API. Область действия маркера будет ограничена доступом к текущему элементу.

С помощью свойства ewsUrl надстройка должна определить правильный URL-адрес для вызовов EWS.

Во внешнюю систему можно передать как маркер, так и идентификатор вложения или идентификатор элемента. Эта система использует маркер в качестве маркера авторизации носителя для вызова операции веб-службы Exchange (EWS) GetAttachment или операции GetItem для возврата вложения или элемента. Например, можно создать удаленную службу для получения вложений из выбранного элемента.

Ошибки:

Если вызов завершился сбоем, используйте свойство asyncResult.диагностика для просмотра сведений об ошибке.

GenericTokenError: An internal error has occurred.- В средах Exchange Online эта ошибка возникает, когда маркер не удается получить, поскольку отключены устаревшие маркеры Exchange для надстроек Outlook. В качестве единого входа для надстройки рекомендуется использовать NAA.
HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- В средах Exchange Online эта ошибка возникает, когда маркер не удается получить, поскольку отключены устаревшие маркеры Exchange для надстроек Outlook. В качестве единого входа для надстройки рекомендуется использовать NAA.
NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

getCallbackTokenAsync(callback, userContext)

Получает строку, содержащую маркер, используемый для получения вложения или элемента с Exchange Server.

Метод getCallbackTokenAsync совершает асинхронный вызов, чтобы получить непрозрачный токен с сервера Exchange Server, на котором размещен почтовый ящик пользователя. Время существования маркера обратного вызова составляет 5 минут.

Маркер возвращается в виде строки в свойстве asyncResult.value .

getCallbackTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Параметры

callback: (asyncResult: Office.AsyncResult<string>) => void

Когда метод завершается, функция, переданная в параметре обратного вызова, вызывается с одним параметром типа Office.AsyncResult. Маркер возвращается в виде строки в свойстве asyncResult.value . При наличии ошибки свойства asyncResult.error и asyncResult.diagnostics могут предоставлять дополнительные сведения.

userContext: any

Необязательный параметр. Данные о состоянии, передаваемые в асинхронный метод.

Возвращаемое значение

void

Устаревшие маркеры удостоверений пользователей Exchange Online и маркеры обратного вызова больше не поддерживаются и отключены во всех клиентах Microsoft 365. Если для надстройки Outlook требуется делегированный доступ или удостоверение пользователя, рекомендуется использовать MSAL (библиотеку проверки подлинности Майкрософт) и проверку подлинности вложенных приложений (NAA). Маркеры удостоверений пользователей Exchange по-прежнему поддерживаются для локальной службы Exchange.
Во внешнюю систему можно передать как маркер, так и идентификатор вложения или идентификатор элемента. Эта система использует маркер в качестве маркера авторизации носителя для вызова операции веб-службы Exchange (EWS) GetAttachment или GetItem для возврата вложения или элемента. Например, можно создать удаленную службу для получения вложений из выбранного элемента.
Чтобы определить, доступны ли маркеры REST или EWS в организации, вызовите Office.context.mailbox.diagnostics.ews.getTokenStatusAsync. Этот getTokenStatusAsync метод доступен для предварительного просмотра в Outlook в Интернете и в Windows (новая и классическая (версия 2510, сборка 19328.20000 и более поздние версии)).
Для вызова getCallbackTokenAsync метода в режиме чтения требуется минимальный уровень разрешений для элемента чтения.
Вызов getCallbackTokenAsync метода в режиме создания требует сохранения элемента. Метод saveAsync требует минимального уровня разрешений для элемента чтения/записи.
Этот способ не поддерживается в Outlook для Android или в iOS. Операции EWS не поддерживаются в надстройках, работающих в Outlook на мобильных клиентах. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.
Этот способ не поддерживается, если надстройка загружается в почтовый ящик Outlook.com или Gmail.
Рекомендации по сценариям делегирования или общего доступа см. в статье об общих папках и общем почтовом ящике .

Ошибки:

Если вызов завершился сбоем, используйте свойство asyncResult.диагностика для просмотра сведений об ошибке.

GenericTokenError: An internal error has occurred.- В средах Exchange Online эта ошибка возникает, когда маркер не удается получить, поскольку отключены устаревшие маркеры Exchange для надстроек Outlook. В качестве единого входа для надстройки рекомендуется использовать NAA.
HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- В средах Exchange Online эта ошибка возникает, когда маркер не удается получить, поскольку отключены устаревшие маркеры Exchange для надстроек Outlook. В качестве единого входа для надстройки рекомендуется использовать NAA.
NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/user-callback-token.yaml

Office.context.mailbox.getCallbackTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

getIsIdentityManaged()

Возвращает значение true, если текущий почтовый ящик управляется службой Microsoft Intune.

getIsIdentityManaged(): boolean;

Возвращаемое значение

boolean

True, если текущий почтовый ящик управляется службой Microsoft Intune.

Этот способ поддерживается только в Outlook для Android и в iOS, начиная с версии 4.2443.0. Дополнительные сведения об API, поддерживаемых Outlook на мобильных устройствах, см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.

Ошибки:

MAMServiceNotAvailable . Клиенту не удается получить политику управления мобильными приложениями (MAM).

Примеры

// Checks if the mailbox is managed by Microsoft Intune.
const isIdentityManaged = Office.context.mailbox.getIsIdentityManaged();
console.log(`Intune-managed mailbox: ${isIdentityManaged}`);

getIsOpenFromLocationAllowed(openLocation)

Возвращает значение true, если политика управления мобильными приложениями (MAM) организации Intune позволяет надстройке получать доступ к данным из указанного расположения.

getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;

Параметры

openLocation: Office.MailboxEnums.OpenLocation

Расположение, из которого надстройка пытается получить доступ к данным.

Возвращаемое значение

boolean

Имеет значение "True", если политика организации Intune MAM разрешает надстройке доступ к данным из указанного расположения.

Этот способ поддерживается только в Outlook для Android и в iOS, начиная с версии 4.2443.0. Дополнительные сведения об API, поддерживаемых Outlook на мобильных устройствах, см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.

Ошибки:

InvalidOpenLocationInput : недопустимое значение указанного расположения.
MAMServiceNotAvailable . Клиенту не удается получить политику MAM.

Примеры

// Checks if the add-in can access data from the device's photo library.
const isOpenFromPhotoLibraryAllowed = Office.context.mailbox.getIsOpenFromLocationAllowed(Office.MailboxEnums.OpenLocation.PhotoLibrary);
if (isOpenFromPhotoLibraryAllowed) {
    console.log("Access to the photo library is allowed.");
    // Do something.
} else {
    console.log("Access to the photo library isn't allowed.");
}

getIsSaveToLocationAllowed(saveLocation)

Возвращает значение true, если политика управления мобильными приложениями (MAM) организации Intune позволяет надстройке сохранять данные в указанное расположение.

getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;

Параметры

saveLocation: Office.MailboxEnums.SaveLocation

Расположение, в котором надстройка пытается сохранить данные.

Возвращаемое значение

boolean

Имеет значение "True", если политика MAM Intune организации позволяет надстройке сохранять данные в указанное расположение.

Этот способ поддерживается только в Outlook для Android и в iOS, начиная с версии 4.2443.0. Дополнительные сведения об API, поддерживаемых Outlook на мобильных устройствах, см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.

Ошибки:

InvalidSaveLocationInput : недопустимое значение указанного расположения.
MAMServiceNotAvailable . Клиенту не удается получить политику MAM.

Примеры

// Checks if the add-in can save data to SharePoint.
const isSaveToSharePointAllowed = Office.context.mailbox.getIsSaveToLocationAllowed(Office.MailboxEnums.SaveLocation.SharePoint);
if (isSaveToSharePointAllowed) {
    console.log("Saving to SharePoint is allowed.");
    // Do something.
} else {
    console.log("Saving to SharePoint isn't allowed.");
}

getSelectedItemsAsync(options, callback)

Получает выбранные сообщения, с которыми надстройка может активировать и выполнить операции. Надстройка может активироваться максимум с 100 сообщениями одновременно. Дополнительные сведения о выборе нескольких элементов см. в статье Активация надстройки Outlook для нескольких сообщений.

getSelectedItemsAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Параметры

options: Office.AsyncContextOptions

Объектный литерал, содержащий одно или несколько из следующих свойств:- asyncContext: Разработчики могут предоставить любой объект, к которому они хотят получить доступ, в функции обратного вызова.

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult . Свойства выбранных сообщений, такие как идентификатор элемента и тема, возвращаются в виде массива объектов SelectedItemDetails в свойстве asyncResult.value . Объекты в массиве следуют порядку выбора сообщений.

Возвращаемое значение

void

getSelectedItemsAsync(callback)

Получает выбранные сообщения, с которыми надстройка может активировать и выполнить операции. Надстройка может активироваться максимум с 100 сообщениями одновременно. Дополнительные сведения о выборе нескольких элементов см. в статье Активация надстройки Outlook для нескольких сообщений.

getSelectedItemsAsync(callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Параметры

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult . Свойства выбранных сообщений, такие как идентификатор элемента и тема, возвращаются в виде массива объектов SelectedItemDetails в свойстве asyncResult.value . Объекты в массиве следуют порядку выбора сообщений.

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-message-properties.yaml

// Retrieves the selected messages' properties and logs them to the console.
Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  asyncResult.value.forEach((message) => {
    console.log(`Item ID: ${message.itemId}`);
    console.log(`Conversation ID: ${message.conversationId}`);
    console.log(`Internet message ID: ${message.internetMessageId}`);
    console.log(`Subject: ${message.subject}`);
    console.log(`Item type: ${message.itemType}`);
    console.log(`Item mode: ${message.itemMode}`);
    console.log(`Has attachment: ${message.hasAttachment}`);
  });
});

getUserIdentityTokenAsync(callback, userContext)

Получает маркер, идентифицирующий пользователя и надстройку Office.

Маркер возвращается в виде строки в свойстве asyncResult.value .

getUserIdentityTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Параметры

callback: (asyncResult: Office.AsyncResult<string>) => void

Когда метод завершается, функция, переданная в параметре обратного вызова, вызывается с одним параметром типа Office.AsyncResult. Маркер возвращается в виде строки в свойстве asyncResult.value . При наличии ошибки свойства asyncResult.error и asyncResult.diagnostics могут предоставлять дополнительные сведения.

userContext: any

Необязательный параметр. Данные о состоянии, передаваемые в асинхронный метод.

Возвращаемое значение

void

Устаревшие маркеры удостоверений пользователей Exchange Online и маркеры обратного вызова больше не поддерживаются и отключены во всех клиентах Microsoft 365. Если для надстройки Outlook требуется делегированный доступ или удостоверение пользователя, рекомендуется использовать MSAL (библиотеку проверки подлинности Майкрософт) и проверку подлинности вложенных приложений (NAA). Маркеры удостоверений пользователей Exchange по-прежнему поддерживаются для локальной службы Exchange.
Метод getUserIdentityTokenAsync возвращает маркер, который можно использовать для идентификации надстройки и пользователя и проверки подлинности с помощью внешней системы.
Этот способ не поддерживается, если надстройка загружается в почтовый ящик Outlook.com или Gmail.

Ошибки:

Если вызов завершился сбоем, используйте свойство asyncResult.диагностика для просмотра сведений об ошибке.

GenericTokenError: An internal error has occurred.- В средах Exchange Online эта ошибка возникает, когда маркер не удается получить, поскольку отключены устаревшие маркеры Exchange для надстроек Outlook. В качестве единого входа для надстройки рекомендуется использовать NAA.
HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- В средах Exchange Online эта ошибка возникает, когда маркер не удается получить, поскольку отключены устаревшие маркеры Exchange для надстроек Outlook. В качестве единого входа для надстройки рекомендуется использовать NAA.
NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/user-identity-token.yaml

Office.context.mailbox.getUserIdentityTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`)
        return;
    }

    console.log(result.value);
});

loadItemByIdAsync(itemId, options, callback)

Загружает один элемент почты по идентификатору веб-служб Exchange (EWS). Затем получает объект, предоставляющий свойства и методы загруженного элемента.

loadItemByIdAsync(itemId: string, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<LoadedMessageCompose | LoadedMessageRead>) => void): void;

Параметры

itemId: string

Идентификатор EWS элемента почты.

options: Office.AsyncContextOptions

Объектный литерал, содержащий свойство asyncContext . В этом свойстве укажите любой объект, к которому вы хотите получить доступ в функции обратного вызова.

callback: (asyncResult: Office.AsyncResult<Office.LoadedMessageCompose | Office.LoadedMessageRead>) => void

Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult . В свойстве asyncResult.value возвращается объект A LoadedMessageCompose илиLoadedMessageRead. Этот объект предоставляет свойства элемента, загруженного в данный момент.

Возвращаемое значение

void

Этот метод применим только к сообщениям.
При реализации функции множественного выбора элемента вызовите Office.context.mailbox.getSelectedItemsAsync вызов, чтобы получить идентификаторы элементов каждого выбранного элемента, чтобы их можно было загружать по одному.
Прежде чем реализовать loadItemByIdAsync метод с функцией множественного выбора элемента, определите, можно ли уже получить доступ к необходимым свойствам выбранного элемента с помощью вызова Office.context.mailbox.getSelectedItemsAsync . Если вы можете, вам не нужно звонить loadItemByIdAsync.
За один раз можно загрузить только один элемент почты. Когда вы реализуете loadItemByIdAsync, необходимо вызвать unloadAsync после обработки элемента. Это необходимо сделать перед вызовом loadItemByIdAsync другого предмета.
Метод loadItemByIdAsync можно вызывать только для сообщений в одном почтовом ящике.

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-loaded-message-properties.yaml

async function getSenderEmailAddress(item) {
  const itemId = item.itemId;
  await new Promise<void>((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        resolve();
        return;
      }

      const loadedItem = result.value;
      const sender = (loadedItem.from as any).emailAddress;
      appendToListItem(sender);

      // Unload the current message before processing another selected message.
      loadedItem.unloadAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          resolve();
          return;
        }

        resolve();
      });
    });
  });
}

loadItemByIdAsync(itemId, callback)

Загружает один элемент почты по идентификатору веб-служб Exchange (EWS). Затем получает объект, предоставляющий свойства и методы загруженного элемента.

loadItemByIdAsync(itemId: string, callback: (asyncResult: Office.AsyncResult<LoadedMessageCompose | LoadedMessageRead>) => void): void;

Параметры

itemId: string

Идентификатор EWS элемента почты.

callback: (asyncResult: Office.AsyncResult<Office.LoadedMessageCompose | Office.LoadedMessageRead>) => void

Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult . В свойстве asyncResult.value возвращается объект A LoadedMessageCompose илиLoadedMessageRead. Этот объект предоставляет свойства элемента, загруженного в данный момент.

Возвращаемое значение

void

Этот метод применим только к сообщениям.
При реализации функции множественного выбора элемента вызовите Office.context.mailbox.getSelectedItemsAsync вызов, чтобы получить идентификаторы элементов каждого выбранного элемента, чтобы их можно было загружать по одному.
Прежде чем реализовать loadItemByIdAsync метод с функцией множественного выбора элемента, определите, можно ли уже получить доступ к необходимым свойствам выбранного элемента с помощью вызова Office.context.mailbox.getSelectedItemsAsync . Если вы можете, вам не нужно звонить loadItemByIdAsync.
За один раз можно загрузить только один элемент почты. Когда вы реализуете loadItemByIdAsync, необходимо вызвать unloadAsync после обработки элемента. Это необходимо сделать перед вызовом loadItemByIdAsync другого предмета.
Метод loadItemByIdAsync можно вызывать только для сообщений в одном почтовом ящике.

makeEwsRequestAsync(data, callback, userContext)

Делает асинхронный запрос к службе веб-служб Exchange (EWS) на сервере Exchange, на котором размещен почтовый ящик пользователя.

Метод makeEwsRequestAsync отправляет запрос EWS от имени надстройки в Exchange.

makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Параметры

data: any

Запрос EWS.

callback: (asyncResult: Office.AsyncResult<string>) => void

Когда метод завершается, функция, переданная в параметре callback , вызывается с единственным параметром, asyncResultкоторый является объектом Office.AsyncResult . XML-ответ запроса EWS предоставляется в виде строки в свойстве asyncResult.value . В Outlook в Интернете на Windows (новая и классическая (начиная с версии 2303, сборка 16225.10000)) и на Mac (начиная с версии 16.73 (23042601)), если размер ответа превышает 5 МБ, в свойстве asyncResult.error возвращается сообщение об ошибке. В более ранних версиях Outlook для Windows (классическая версия) и на Mac сообщение об ошибке возвращается, если размер ответа превышает 1 МБ.

userContext: any

Необязательный параметр. Данные о состоянии, передаваемые в асинхронный метод.

Возвращаемое значение

void

Устаревшие маркеры удостоверений пользователей Exchange Online и маркеры обратного вызова больше не поддерживаются и отключены во всех клиентах Microsoft 365. Если для надстройки Outlook требуется делегированный доступ или удостоверение пользователя, рекомендуется использовать MSAL (библиотеку проверки подлинности Майкрософт) и проверку подлинности вложенных приложений (NAA). Маркеры удостоверений пользователей Exchange по-прежнему поддерживаются для локальной службы Exchange.
Чтобы разрешить makeEwsRequestAsync метод выполнения запросов EWS, администратор сервера должен выбрать OAuthAuthenticationtrue каталог EWS сервера клиентского доступа.
Чтобы использовать этот makeEwsRequestAsync метод, у надстройки должно быть разрешение на чтение и запись почтового ящика. Сведения об использовании разрешений на чтение и запись для почтового ящика , а также об операциях EWS, которые можно вызывать с помощью этого makeEwsRequestAsync метода, см. в статье Указание разрешений для доступа к почтовому ящику со стороны надстройки почты.
Если вашей надстройке требуется доступ к связанным элементам папок или ее XML-запрос должен указывать кодировку UTF-8 (\<?xml version="1.0" encoding="utf-8"?\>), она должна использовать Microsoft Graph или REST API для доступа к почтовому ящику пользователя.
Этот способ не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.
Этот способ не поддерживается, если надстройка загружена в почтовый ящик Gmail.
При использовании метода makeEwsRequestAsync в надстройках, работающих в Outlook более ранних версий, чем 15.0.4535.1004, необходимо установить значение кодировки ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>). Чтобы определить версию клиента Outlook, используйте свойство mailbox.diagnostics.hostVersion . Вам не нужно устанавливать значение кодировки, если надстройка работает в Outlook в Интернете и в новом Outlook для Windows. Чтобы определить клиент Outlook, в котором работает надстройка, используйте свойство mailbox.diagnostics.hostName .

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/get-icaluid-as-attendee.yaml

const ewsId = Office.context.mailbox.item.itemId;
const request = `<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header><t:RequestServerVersion Version="Exchange2013" /></soap:Header>
      <soap:Body>
        <m:GetItem>
          <m:ItemShape>
            <t:BaseShape>AllProperties</t:BaseShape>
          </m:ItemShape >
          <m:ItemIds>
            <t:ItemId Id="${ewsId}" />
          </m:ItemIds>
        </m:GetItem>
      </soap:Body>
    </soap:Envelope>`;

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  console.log(getUID(result.value));
});

...

const request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
    '  <soap:Header><t:RequestServerVersion Version="Exchange2010" /></soap:Header>' +
    '  <soap:Body>' +
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">' +
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>' +
    '      <m:Items>' +
    '        <t:Message>' +
    '          <t:Subject>Hello, Outlook!</t:Subject>' +
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>' +
    '          <t:ToRecipients>' +
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>' +
    '          </t:ToRecipients>' +
    '        </t:Message>' +
    '      </m:Items>' +
    '    </m:CreateItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(`Failed to make EWS request: ${result.error.message}.`);
        return;
    }
    console.log(result.value);
});

removeHandlerAsync(eventType, options, callback)

Удаляет обработчиков для поддерживаемого типа события. События доступны только в надстройках области задач.

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType | string

Событие, которое должно отменить обработчик.

options: Office.AsyncContextOptions

Предоставляет возможность сохранения контекстных данных любого типа без изменений для использования в обратном вызове.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. После завершения метода вызывается функция, переданная в параметре callback , с одним параметром типа Office.AsyncResult.

Возвращаемое значение

void

Событие	Описание	Набор минимальных требований
`DragAndDropEvent`	Вложение сообщения или файла в окне клиента Outlook перетаскивается, а затем опускается в область задач надстройки. Это событие поддерживается только в Outlook в Интернете и новом Outlook для Windows.	1.5
`ItemChanged`	При закреплении области задач выбран другой элемент Outlook для просмотра.	1.5
`OfficeThemeChanged`	В Outlook изменена тема OfficeTheme.	1.14
`SelectedItemsChanged`	Выбрано или снято выделение одного или нескольких сообщений.	1.13

removeHandlerAsync(eventType, callback)

Удаляет обработчиков для поддерживаемого типа события. События доступны только в надстройках области задач.

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType | string

Событие, которое должно отменить обработчик.

callback: (asyncResult: Office.AsyncResult<void>) => void

Необязательный параметр. После завершения метода вызывается функция, переданная в параметре callback , с одним параметром типа Office.AsyncResult.

Возвращаемое значение

void

Событие	Описание	Набор минимальных требований
`DragAndDropEvent`	Вложение сообщения или файла в окне клиента Outlook перетаскивается, а затем опускается в область задач надстройки. Это событие поддерживается только в Outlook в Интернете и новом Outlook для Windows.	1.5
`ItemChanged`	При закреплении области задач выбран другой элемент Outlook для просмотра.	1.5
`OfficeThemeChanged`	В Outlook изменена тема OfficeTheme.	1.14
`SelectedItemsChanged`	Выбрано или снято выделение одного или нескольких сообщений.	1.13

Примеры

Office.context.mailbox.removeHandlerAsync(Office.EventType.OfficeThemeChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});

Комментарии

Используется

Примеры

Свойства

Методы

Сведения о свойстве

diagnostics

Значение свойства

Комментарии

Примеры

ewsUrl

Значение свойства

Комментарии

Примеры

item

Значение свойства

masterCategories

Значение свойства

Комментарии

Примеры

restUrl

Значение свойства

Комментарии

Примеры

userProfile

Значение свойства

Сведения о методе

addHandlerAsync(eventType, handler, options, callback)

Параметры

Возвращаемое значение

Комментарии

Примеры

addHandlerAsync(eventType, handler, callback)

Параметры

Возвращаемое значение

Комментарии

convertToEwsId(id, restVersion)

Параметры

Возвращаемое значение

Комментарии

Примеры

convertToLocalClientTime(timeValue)

Параметры

Возвращаемое значение

Комментарии

Примеры

convertToRestId(id, restVersion)

Параметры

Возвращаемое значение

Комментарии

Примеры

convertToUtcClientTime(input)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayAppointmentForm(itemId)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayAppointmentFormAsync(itemId, options, callback)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayAppointmentFormAsync(itemId, callback)

Параметры

Возвращаемое значение

Комментарии

displayMessageForm(itemId)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayMessageFormAsync(itemId, options, callback)

Параметры

Возвращаемое значение

Комментарии