Office. Mailbox interface

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要说明：

应用必须具有其清单中指定的 读取项 权限，才能在读取模式下调用 ewsUrl 成员。
在撰写模式下，必须先调用 saveAsync 该方法，然后才能使用该 ewsUrl 成员。应用必须具有 读取/写入项 权限才能调用该 saveAsync 方法。
Android 或 iOS 上的 Outlook 不支持此属性。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
远程服务可使用 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

获取一个对象，该对象提供管理与邮箱关联的类别主列表的方法。

masterCategories: MasterCategories;

属性值

Office.MasterCategories

注解

API 集：邮箱 1.8

最低权限级别： 读/写邮箱

适用的 Outlook 模式：Compose 或 Read

示例

// 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

获取此电子邮件帐户的 REST 终结点的 URL。

restUrl: string;

属性值

string

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要说明：

Outlook REST v2.0 和 beta 终结点现已弃用。但是，在 2025 年 10 月 14 日结束对 Outlook 2019 的外延支持之前，专用发布和 AppSource 托管的加载项仍可使用 REST 服务。系统会自动识别来自这些加载项的流量以便获得豁免。此豁免也适用于 2024 年 3 月 31 日之后开发的新加载项。尽管加载项能够在 2025 年之前使用 REST 服务，但我们强烈建议你迁移加载项以使用 Microsoft Graph。有关指南，请参阅比较 Microsoft Graph 和 Outlook REST API 终结点。
加载项必须具有在其清单中指定的 读取项 权限，才能在读取模式下调用 restUrl 成员。
在撰写模式中，必须调用 saveAsync 方法，才能使用 restUrl 成员。加载项必须具有 读取/写入项 权限才能调用 saveAsync 该方法。但是，在委托或共享方案中，应改用 targetRestUrl 要求集 1.8) 中引入 (SharedProperties 对象的属性。有关详细信息，请参阅共享文件夹和共享邮箱一文。

示例

// 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参数的属性将与传递给 addHandlerAsync的参数匹配eventType。

options: Office.AsyncContextOptions

提供用于保留任何类型的上下文数据（不变）以供回调使用的选项。

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

可选。当该方法完成时， callback 将使用类型 Office.AsyncResult为 .

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要事项：对象支持 Mailbox 以下事件。

事件	说明	最低要求集
`DragAndDropEvent`	Outlook 客户端窗口中的邮件或文件附件被拖放到加载项的任务窗格中。此事件仅在 Outlook 网页版和新版 Outlook on 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参数的属性将与传递给 addHandlerAsync的参数匹配eventType。

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

可选。当该方法完成时， callback 将使用类型 Office.AsyncResult为 .

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要事项：对象支持 Mailbox 以下事件。

事件	说明	最低要求集
`DragAndDropEvent`	Outlook 客户端窗口中的邮件或文件附件被拖放到加载项的任务窗格中。此事件仅在 Outlook 网页版和新版 Outlook on Windows 中受支持。	1.5
`ItemChanged`	在任务窗格固定时，将选择不同的 Outlook 项进行查看。	1.5
`OfficeThemeChanged`	Outlook 中的 OfficeTheme 已更改。	1.14
`SelectedItemsChanged`	选中或取消选择一封或多封邮件。	1.13

convertToEwsId(id, restVersion)

将受支持的 ID 转换为 Exchange Web 服务 (EWS) 格式。

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

参数

id: string

要转换为 EWS 格式的 ID。此字符串可以是针对 Outlook REST API 格式化的项目 ID，也可以是从 Office.context.mailbox.item.conversationId.

restVersion: Office.MailboxEnums.RestVersion | string

指示用于检索项目 ID 的 Outlook REST API 的版本。

返回

string

注解

API 集：邮箱 1.3

最低权限级别：受限

适用的 Outlook 模式：Compose 或 Read

重要说明：

不再支持旧版 Exchange Online 用户标识令牌和回调令牌，并在所有 Microsoft 365 租户中关闭。如果 Outlook 加载项需要委派的用户访问或用户标识，建议使用 MSAL (Microsoft 身份验证库) 和嵌套应用身份验证 (NAA) 。 Exchange 内部部署仍支持 Exchange 用户标识令牌。
Android 或 iOS 上的 Outlook 不支持此方法。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
通过 REST API (（如 Microsoft Graph ）检索的项 ID) 使用与 EWS 使用的格式不同的格式。方法将 REST 格式化的 ID 转换为正确的 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 客户端使用的时区因平台而异。 Windows (经典) 上的 Outlook 和 Mac 上的 Outlook 使用客户端计算机时区。 Windows 上的 Outlook 网页版和新版 Outlook 使用 Exchange 管理员中心 (EAC) 设置的时区。应对日期和时间值进行处理，以便用户界面上显示的值始终与用户预期的时区一致。

在 Windows (经典) 和 Mac 上的 Outlook 中，该 convertToLocalClientTime 方法返回值设置为客户端计算机时区的字典对象。在 Outlook 网页版和 Windows 上的新 Outlook 中，该convertToLocalClientTime方法返回一个字典对象，其值设置为 EAC 中指定的时区。

convertToLocalClientTime(timeValue: Date): LocalClientTime;

参数

timeValue: Date

Date 对象。

返回

Office.LocalClientTime

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

示例

// 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)

将支持的 ID 转换为 REST 格式。

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

参数

id: string

要转换为 REST 格式的 ID。此字符串可以是针对 EWS 格式化的项目 ID（通常Office.context.mailbox.item.itemId从、、对话 ID 检索到Office.context.mailbox.item.conversationId ）或系列 ID 检索自Office.context.mailbox.item.seriesId 。

restVersion: Office.MailboxEnums.RestVersion | string

指示与转换后的 ID 一起使用的 Outlook REST API 版本的值。

返回

string

注解

API 集：邮箱 1.3

最低权限级别：受限

适用的 Outlook 模式：Compose 或 Read

重要说明：

Android 或 iOS 上的 Outlook 不支持此方法。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
通过 Exchange Web 服务 (EWS) 或通过属性检索 itemId 的项 ID 使用的格式与 REST API (使用的格式不同，例如 Microsoft Graph) 。方法将 EWS 格式化的 ID 转换为正确的 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

包含以 UTC 表示的时间的 Date 对象。

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

示例

// 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 方法在桌面的新窗口中打开现有的日历约会。

在 Mac 上的 Outlook 中，可以使用此方法显示不属于定期系列的单个约会或定期系列的主约会。但是，你无法显示该系列的实例，因为你无法访问 (包括项目 ID) 定期系列实例的属性。

在 Outlook 网页版和新的 Outlook on Windows 中，仅当表单正文小于或等于 32,000 个字符时，此方法才会打开指定表单。

如果指定的项目标识符无法识别现有约会，则会在客户端计算机或设备上打开一个空白窗格，并且不会返回任何错误消息。

displayAppointmentForm(itemId: string): void;

参数

itemId: string

现有日历约会的 Exchange Web 服务 (EWS) 标识符。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要提示： Android 或 iOS 上的 Outlook 不支持此方法。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

示例

// 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 方法将打开桌面新窗口中或移动设备对话框中的现有日历约会。

在 Mac 上的 Outlook 中，可以使用此方法显示不属于定期系列的单个约会或定期系列的主约会。但是，你无法显示该系列的实例，因为你无法访问 (包括项目 ID) 定期系列实例的属性。

在 Outlook 网页版和新的 Outlook on Windows 中，仅当表单正文小于或等于 32,000 个字符时，此方法才会打开指定表单。

如果指定的项目标识符无法识别现有约会，则会在客户端计算机或设备上打开一个空白窗格，并且不会返回任何错误消息。

注意：iOS 或 Android 上的 Outlook 不支持此方法。

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

参数

itemId: string

现有日历约会的 Exchange Web 服务 (EWS) 标识符。

options: Office.AsyncContextOptions

包含以下一个或多个属性的对象文本：- asyncContext：开发人员可以在回调函数中提供他们希望访问的任何对象。

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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

示例

// 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 方法将打开桌面新窗口中或移动设备对话框中的现有日历约会。

在 Mac 上的 Outlook 中，可以使用此方法显示不属于定期系列的单个约会或定期系列的主约会。但是，你无法显示该系列的实例，因为你无法访问 (包括项目 ID) 定期系列实例的属性。

在 Outlook 网页版和新的 Outlook on Windows 中，仅当表单正文小于或等于 32,000 个字符时，此方法才会打开指定表单。

如果指定的项目标识符无法识别现有约会，则会在客户端计算机或设备上打开一个空白窗格，并且不会返回任何错误消息。

注意：iOS 或 Android 上的 Outlook 不支持此方法。

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

参数

itemId: string

现有日历约会的 Exchange Web 服务 (EWS) 标识符。

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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

displayMessageForm(itemId)

显示现有邮件。

该 displayMessageForm 方法在桌面的新窗口中打开现有邮件。

在 Outlook 网页版和新的 Outlook on Windows 中，仅当表单正文小于或等于 32,000 个字符时，此方法才会打开指定表单。

如果指定的项标识符无法识别现有消息，则客户端计算机上不会显示任何消息，也不会返回错误消息。

displayMessageForm(itemId: string): void;

参数

itemId: string

现有消息的 Exchange Web 服务 (EWS) 标识符。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要说明：

Android 或 iOS 上的 Outlook 不支持此方法。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
不要将与 displayMessageForm 表示约会的 itemId 一起使用。使用 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 on Windows 中，仅当表单正文小于或等于 32,000 个字符时，此方法才会打开指定表单。

如果指定的项标识符无法识别现有消息，则客户端计算机上不会显示任何消息，也不会返回错误消息。

不要将 OR displayMessageFormdisplayMessageFormAsync 方法与表示约会的 itemId 一起使用。使用 or displayAppointmentFormAsync 方法显示现有约会，或displayNewAppointmentForm使用 displayAppointmentForm OR displayNewAppointmentFormAsync 显示窗体以创建新约会。

注意：iOS 或 Android 上的 Outlook 不支持此方法。

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

参数

itemId: string

现有消息的 Exchange Web 服务 (EWS) 标识符。

options: Office.AsyncContextOptions

包含以下一个或多个属性的对象文本：- asyncContext：开发人员可以在回调函数中提供他们希望访问的任何对象。

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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

示例

// 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 on Windows 中，仅当表单正文小于或等于 32,000 个字符时，此方法才会打开指定表单。

如果指定的项标识符无法识别现有消息，则客户端计算机上不会显示任何消息，也不会返回错误消息。

不要将 OR displayMessageFormdisplayMessageFormAsync 方法与表示约会的 itemId 一起使用。使用 or displayAppointmentFormAsync 方法显示现有约会，或displayNewAppointmentForm使用 displayAppointmentForm OR displayNewAppointmentFormAsync 显示窗体以创建新约会。

注意：iOS 或 Android 上的 Outlook 不支持此方法。

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

参数

itemId: string

现有消息的 Exchange Web 服务 (EWS) 标识符。

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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

displayNewAppointmentForm(parameters)

显示用于新建日历约会的表单。

displayNewAppointmentForm 方法打开可让用户新建约会或会议的窗体。如果指定了参数，将使用参数的内容自动填充约会窗体字段。

在 Outlook 网页版和 Windows 上的新版 Outlook 中，此方法始终显示包含“与会者”字段的表单。如果未将任何与会者指定为输入参数，该方法将显示带有 “保存 ”按钮的表单。如果已指定与会者，窗体将包含与会者和“发送”按钮。

在 Windows (经典) 和 Mac 上的 Outlook 中，如果在、 optionalAttendees或resources参数中requiredAttendees指定任何与会者或资源，此方法将显示带有“发送”按钮的会议表单。如果未指定任何收件人，此方法将显示一个包含“保存并关闭”按钮的约会窗体。

如果任何参数超过指定大小限制，或者指定了未知参数名称，则会引发异常。

displayNewAppointmentForm(parameters: AppointmentForm): void;

参数

parameters: Office.AppointmentForm

描述 AppointmentForm 新约会。所有属性都是可选的。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：读取

重要提示： Android 或 iOS 上的 Outlook 不支持此方法。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

示例

// 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 网页版和 Windows 上的新版 Outlook 中，此方法始终显示包含“与会者”字段的表单。如果你未将任何与会者指定为输入参数，该方法将显示为一个包含“保存”按钮的窗体。如果已指定与会者，窗体将包含与会者和“发送”按钮。

在 Windows (经典) 和 Mac 上的 Outlook 中，如果在、 optionalAttendees或resources参数中requiredAttendees指定任何与会者或资源，此方法将显示带有“发送”按钮的会议表单。如果未指定任何收件人，此方法将显示一个包含“保存并关闭”按钮的约会窗体。

如果任何参数超过指定大小限制，或者指定了未知参数名称，则会引发异常。

注意：iOS 或 Android 上的 Outlook 不支持此方法。

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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 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);

// 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 网页版和 Windows 上的新版 Outlook 中，此方法始终显示包含“与会者”字段的表单。如果你未将任何与会者指定为输入参数，该方法将显示为一个包含“保存”按钮的窗体。如果已指定与会者，窗体将包含与会者和“发送”按钮。

在 Windows (经典) 和 Mac 上的 Outlook 中，如果在、 optionalAttendees或resources参数中requiredAttendees指定任何与会者或资源，此方法将显示带有“发送”按钮的会议表单。如果未指定任何收件人，此方法将显示一个包含“保存并关闭”按钮的约会窗体。

如果任何参数超过指定大小限制，或者指定了未知参数名称，则会引发异常。

注意：iOS 或 Android 上的 Outlook 不支持此方法。

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

参数

parameters: Office.AppointmentForm

描述 AppointmentForm 新约会。所有属性都是可选的。

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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：读取

displayNewMessageForm(parameters)

显示用于创建新邮件的窗体。

此 displayNewMessageForm 方法打开一个窗体，使用户能够创建新消息。如果指定了参数，则消息窗体字段将自动填充参数的内容。

如果任何参数超过指定大小限制，或者指定了未知参数名称，则会引发异常。

displayNewMessageForm(parameters: MessageForm): void;

参数

parameters: Office.MessageForm

MessageForm包含要添加到新邮件表单的内容的对象。所有属性都是可选的。

返回

void

注解

API 集：邮箱 1.6

最低权限级别： 读取项目

适用的 Outlook 模式：读取

示例

// 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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：读取

示例

// 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

可选。当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。

返回

void

注解

最低权限级别： 读取项目

适用的 Outlook 模式：读取

getCallbackTokenAsync(options, callback)

获取一个字符串，该字符串包含用于调用 REST API 或 Exchange Web 服务 (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：确定提供的令牌是否将用于 Outlook REST API 或 Exchange Web 服务。默认值为 false。 asyncContext ：传递到异步方法的任何状态数据。

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

当该方法完成时，将使用类型 Office.AsyncResult为 . 令牌在属性中 asyncResult.value 作为字符串返回。如果出现错误，则 asyncResult.error 和 asyncResult.diagnostics 属性可能会提供其他信息。

返回

void

注解

API 集：均支持读取模式;邮箱 1.3 引入了 Compose 模式支持

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要说明：

不再支持旧版 Exchange Online 用户标识令牌和回调令牌，并在所有 Microsoft 365 租户中关闭。如果 Outlook 加载项需要委派的用户访问或用户标识，建议使用 MSAL (Microsoft 身份验证库) 和嵌套应用身份验证 (NAA) 。 Exchange 内部部署仍支持 Exchange 用户标识令牌。
Outlook REST v2.0 和 beta 终结点现已弃用。但是，在 2025 年 10 月 14 日结束对 Outlook 2019 的外延支持之前，专用发布和 AppSource 托管的加载项仍可使用 REST 服务。系统会自动识别来自这些加载项的流量以便获得豁免。此豁免也适用于 2024 年 3 月 31 日之后开发的新加载项。尽管加载项能够在 2025 年之前使用 REST 服务，但我们强烈建议你迁移加载项以使用 Microsoft Graph。有关指南，请参阅比较 Microsoft Graph 和 Outlook REST API 终结点。
若要确定 REST 或 EWS 令牌在组织中是否可用，请调用 Office.context.mailbox.diagnostics.ews.getTokenStatusAsync。该getTokenStatusAsync方法可在 Outlook 网页版和 Windows 上预览 (新的和经典的 (版本 2510、内部版本 19328.20000 以及更高版本) ) 。
如果在 Outlook.com 或 Gmail 邮箱中加载加载项，则不支持此方法。
仅在 Android 版和 iOS 版 Outlook 的读取模式下支持此方法。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
在 iOS 和 Android 上的 Outlook 中运行的加载项不支持 EWS 操作。 REST 令牌始终会在 Outlook 移动客户端 options.isRest 中返回，即使设置为 false.
在读取模式下调用该方法需要getCallbackTokenAsync读取项的最低权限级别。
在撰写模式下调用该 getCallbackTokenAsync 方法需要您已经保存该项。该 saveAsync 方法需要 读/写项目的最低权限级别。
有关代理或共享方案的指导，请参阅共享文件夹和共享邮箱一文。

REST 令牌

当) 请求 REST 令牌时，生成 (options.isRest = true 令牌将无法对 EWS 调用进行身份验证。令牌的范围将限制为对当前项目及其附件的只读访问，除非加载项已在其清单中指定了 读/写 邮箱权限。如果指定 了读/写邮箱 权限，则生成的令牌将授予对邮件、日历和联系人的读/写访问权限，包括发送邮件的功能。

在进行 REST API 调用时，外接程序应使用 restUrl 属性来确定要使用的正确 URL。

此 API 适用于以下范围。

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

EWS 令牌

(options.isRest = false) 请求 EWS 令牌时，生成的令牌将无法对 REST API 调用进行身份验证。令牌的作用域限制为访问当前项。

外接程序应使用 ewsUrl 属性来确定进行 EWS 调用时要使用的正确 URL。

可以将令牌和附件标识符或项标识符传递给外部系统。该系统使用令牌作为持有者授权令牌来调用 Exchange Web 服务 (EWS) GetAttachment 操作或 GetItem 操作来返回附件或项目。例如，可以创建远程服务以从选定项目中获取附件。

错误：

如果调用失败，请使用 asyncResult.诊断属性查看有关错误的详细信息。

GenericTokenError: An internal error has occurred.- 在 Exchange Online 环境中，当由于 Outlook 加载项的旧版 Exchange 令牌已关闭而无法检索令牌时，会发生此错误。建议使用 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 环境中，当由于 Outlook 加载项的旧版 Exchange 令牌已关闭而无法检索令牌时，会发生此错误。建议使用 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

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要说明：

不再支持旧版 Exchange Online 用户标识令牌和回调令牌，并在所有 Microsoft 365 租户中关闭。如果 Outlook 加载项需要委派的用户访问或用户标识，建议使用 MSAL (Microsoft 身份验证库) 和嵌套应用身份验证 (NAA) 。 Exchange 内部部署仍支持 Exchange 用户标识令牌。
可以将令牌和附件标识符或项标识符传递给外部系统。该系统使用令牌作为持有者授权令牌来调用 Exchange Web 服务 (EWS) GetAttachment 或 GetItem 操作来返回附件或项目。例如，可以创建远程服务以从选定项目中获取附件。
若要确定 REST 或 EWS 令牌在组织中是否可用，请调用 Office.context.mailbox.diagnostics.ews.getTokenStatusAsync。该getTokenStatusAsync方法可在 Outlook 网页版和 Windows 上预览 (新的和经典的 (版本 2510、内部版本 19328.20000 以及更高版本) ) 。
在读取模式下调用该方法需要getCallbackTokenAsync读取项的最低权限级别。
在撰写模式下调用该 getCallbackTokenAsync 方法需要您已经保存该项。该 saveAsync 方法需要 读/写项目的最低权限级别。
Android 或 iOS 上的 Outlook 不支持此方法。在移动客户端上的 Outlook 中运行的加载项不支持 EWS 操作。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
如果在 Outlook.com 或 Gmail 邮箱中加载加载项，则不支持此方法。
有关代理或共享方案的指导，请参阅共享文件夹和共享邮箱一文。

错误：

如果调用失败，请使用 asyncResult.诊断属性查看有关错误的详细信息。

GenericTokenError: An internal error has occurred.- 在 Exchange Online 环境中，当由于 Outlook 加载项的旧版 Exchange 令牌已关闭而无法检索令牌时，会发生此错误。建议使用 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 环境中，当由于 Outlook 加载项的旧版 Exchange 令牌已关闭而无法检索令牌时，会发生此错误。建议使用 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()

如果当前邮箱由 Microsoft Intune 管理，则返回 true。

getIsIdentityManaged(): boolean;

返回

boolean

如果当前邮箱由 Microsoft Intune 管理，则为 true。

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose、Read

重要提示：从版本 4.2443.0 开始，仅在 Android 版 Outlook 和 iOS 上支持此方法。若要详细了解移动设备上的 Outlook 支持的 API，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

错误：

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)

如果组织的 Intune 移动应用程序管理 (MAM) 策略允许加载项从指定位置访问数据，则返回 true。

getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;

参数

openLocation: Office.MailboxEnums.OpenLocation

加载项尝试访问数据的位置。

返回

boolean

如果组织的 Intune MAM 策略允许加载项从指定位置访问数据，则为 True。

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose、Read

重要提示：从版本 4.2443.0 开始，仅在 Android 版 Outlook 和 iOS 上支持此方法。若要详细了解移动设备上的 Outlook 支持的 API，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

错误：

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)

如果组织的 Intune 移动应用程序管理 (MAM) 策略允许加载项将数据保存到指定位置，则返回 true。

getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;

参数

saveLocation: Office.MailboxEnums.SaveLocation

加载项尝试保存数据的位置。

返回

boolean

如果组织的 Intune MAM 策略允许加载项将数据保存到指定位置，则为 True。

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose、Read

重要提示：从版本 4.2443.0 开始，仅在 Android 版 Outlook 和 iOS 上支持此方法。若要详细了解移动设备上的 Outlook 支持的 API，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

错误：

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

当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。所选消息的属性（如项目 ID 和主题）将作为属性中 asyncResult.valueSelectedItemDetails 对象的数组返回。数组中的对象按照选择消息的顺序。

返回

void

注解

API 集：邮箱 1.13

最低权限级别： 读/写邮箱

适用的 Outlook 模式：Compose、Read

重要提示：此方法仅适用于邮件。

getSelectedItemsAsync(callback)

获取加载项可激活的当前选定邮件并执行操作。加载项一次最多可以激活 100 封邮件。若要了解有关项目多选的详细信息，请参阅在多封邮件上激活 Outlook 加载项。

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

参数

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

当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。所选消息的属性（如项目 ID 和主题）将作为属性中 asyncResult.valueSelectedItemDetails 对象的数组返回。数组中的对象按照选择消息的顺序。

返回

void

注解

API 集：邮箱 1.13

最低权限级别： 读/写邮箱

适用的 Outlook 模式：Compose、Read

重要提示：此方法仅适用于邮件。

示例

// 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

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要说明：

不再支持旧版 Exchange Online 用户标识令牌和回调令牌，并在所有 Microsoft 365 租户中关闭。如果 Outlook 加载项需要委派的用户访问或用户标识，建议使用 MSAL (Microsoft 身份验证库) 和嵌套应用身份验证 (NAA) 。 Exchange 内部部署仍支持 Exchange 用户标识令牌。
该getUserIdentityTokenAsync方法返回一个令牌，可用于通过外部系统识别和验证加载项和用户。
如果在 Outlook.com 或 Gmail 邮箱中加载加载项，则不支持此方法。

错误：

如果调用失败，请使用 asyncResult.诊断属性查看有关错误的详细信息。

GenericTokenError: An internal error has occurred.- 在 Exchange Online 环境中，当由于 Outlook 加载项的旧版 Exchange 令牌已关闭而无法检索令牌时，会发生此错误。建议使用 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 环境中，当由于 Outlook 加载项的旧版 Exchange 令牌已关闭而无法检索令牌时，会发生此错误。建议使用 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 Web 服务 (EWS) ID 加载单个邮件项目。然后，获取提供所加载项目的属性和方法的对象。

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

参数

itemId: string

邮件项目的 EWS ID。

options: Office.AsyncContextOptions

包含 asyncContext 属性的对象文本。在此属性中，提供要在回调函数中访问的任何对象。

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

当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。在属性中asyncResult.value返回 A LoadedMessageCompose 或LoadedMessageRead对象。此对象提供当前加载的项目的属性。

返回

void

注解

API 集：邮箱 1.15

最低权限级别： 读/写邮箱

适用的 Outlook 模式：Compose、Read

重要说明：

此方法仅适用于消息。
实现项目多选功能时，调用 Office.context.mailbox.getSelectedItemsAsync 获取每个选定项目的项目 ID，以便一次加载一个。
在使用项多选功能实现 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 Web 服务 (EWS) ID 加载单个邮件项目。然后，获取提供所加载项目的属性和方法的对象。

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

参数

itemId: string

邮件项目的 EWS ID。

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

当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。在属性中asyncResult.value返回 A LoadedMessageCompose 或LoadedMessageRead对象。此对象提供当前加载的项目的属性。

返回

void

注解

API 集：邮箱 1.15

最低权限级别： 读/写邮箱

适用的 Outlook 模式：Compose、Read

重要说明：

此方法仅适用于消息。
实现项目多选功能时，调用 Office.context.mailbox.getSelectedItemsAsync 获取每个选定项目的项目 ID，以便一次加载一个。
在使用项多选功能实现 loadItemByIdAsync 该方法之前，请确定是否已可以使用调用访问 Office.context.mailbox.getSelectedItemsAsync 所选项目的所需属性。如果可以，则无需调用 loadItemByIdAsync。
一次只能加载一个邮件项目。实现 loadItemByIdAsync时，必须在处理项后调用 unloadAsync 。在调用 loadItemByIdAsync 另一个项目之前必须执行此操作。
只能对同一邮箱中的邮件调用此 loadItemByIdAsync 方法。

makeEwsRequestAsync(data, callback, userContext)

向托管用户邮箱的 Exchange 服务器上的 Exchange Web 服务 (EWS) 服务发出异步请求。

makeEwsRequestAsync 方法代表加载项将 EWS 请求发送到 Exchange。

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

参数

data: any

EWS 请求。

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

当该方法完成时，将使用单个参数（一个对象）asyncResultOffice.AsyncResult调用传入参数的callback函数。 EWS 请求的 XML 响应在属性中 asyncResult.value 以字符串形式提供。在 Outlook 网页版中，在版本 2303 内部版本 16225.10000) ) 开始的 Windows (新 (和经典，以及从版本 16.73 (23042601) ) 开始的 Mac (，如果响应大小超过 5 MB，则会在属性中asyncResult.error返回错误消息。在 Windows (经典) 和 Mac 上的早期版本的 Outlook 中，如果响应大小超过 1 MB，则会返回错误消息。

userContext: any

可选。传递给异步方法的任何状态数据。

返回

void

注解

最低权限级别： 读/写邮箱

适用的 Outlook 模式：Compose 或 Read

重要说明：

不再支持旧版 Exchange Online 用户标识令牌和回调令牌，并在所有 Microsoft 365 租户中关闭。如果 Outlook 加载项需要委派的用户访问或用户标识，建议使用 MSAL (Microsoft 身份验证库) 和嵌套应用身份验证 (NAA) 。 Exchange 内部部署仍支持 Exchange 用户标识令牌。
若要启用makeEwsRequestAsync发出 EWS 请求的方法，服务器管理员必须设置为OAuthAuthenticationtrue客户端访问服务器 EWS 目录。
加载项必须具有 读/写邮箱 权限才能使用此 makeEwsRequestAsync 方法。有关使用 读/写邮箱 权限以及可以使用该 makeEwsRequestAsync 方法调用的 EWS 操作的信息，请参阅指定邮件加载项访问用户邮箱的权限。
如果你的加载项需要访问文件夹关联项或其 XML 请求必须指定 UTF-8 编码 (\<?xml version="1.0" encoding="utf-8"?\>) ，则它必须改用 Microsoft Graph 或 REST API 访问用户的邮箱。
Android 或 iOS 上的 Outlook 不支持此方法。有关 Outlook 移动版中支持的 API 的详细信息，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
加载项加载到 Gmail 邮箱中时，不支持此方法。
在低于版本 15.0.4535.1004 的 Outlook 版本中运行的加载项中使用该 makeEwsRequestAsync 方法时，必须将编码值设置为 ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>) 。若要确定 Outlook 客户端的版本，请使用该 mailbox.diagnostics.hostVersion 属性。当加载项在 Outlook 网页版和新的 Outlook on 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

注解

最低权限级别： 读取项目

适用的 Outlook 模式：Compose 或 Read

重要事项：对象支持 Mailbox 以下事件。

事件	说明	最低要求集
`DragAndDropEvent`	Outlook 客户端窗口中的邮件或文件附件被拖放到加载项的任务窗格中。此事件仅在 Outlook 网页版和新版 Outlook on 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

注解