Office.MessageRead interface

  • 参考
包:
outlook

Office.context.mailbox.item 的邮件读取模式。

重要说明：这是一个内部 Outlook 对象，不会通过现有接口直接公开。 应将其视为 的 Office.context.mailbox.item模式。 有关详细信息，请参阅 “对象模型 ”页。

父接口：

Extends
Office.Message

属性

attachments

获取项的附件作为数组。
body

获取一个提供用于处理项目正文的方法的对象。
categories

获取一个 对象，该对象提供用于管理项类别的方法。
cc

提供对邮件的抄送 (Cc) 收件人的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性cc返回一个数组，该数组包含邮件抄送行中列出的每个收件人的 EmailAddressDetails 对象。 返回的最大收件人数因 Outlook 客户端而异。

  • Windows：500 个收件人

  • Android、经典 Mac UI、iOS：100 个收件人

  • Web 浏览器：20 个收件人

  • 新 Mac UI：无限制
conversationId

获取包含特定消息的电子邮件会话的标识符。

如果在阅读窗体或撰写窗体的回复中激活邮件应用程序，则此属性可以获得一个整数值。 如果用户随后更改了回复邮件的主题（若发送回复），则该邮件的对话 ID 将改变且之前获取的值将不适用。

对于撰写窗体的新项目，此属性获得一个 null 值。 如果用户设置一个主题并保存该项目，conversationId 属性将返回一个值。
dateTimeCreated

获取项目创建的日期和时间。
dateTimeModified

获取项目最近一次修改的日期和时间。
display

获取一个 对象，用于临时设置在阅读模式下消息的正文或主题中显示的内容。
end

获取约会结束的日期和时间。

属性 end 是表示 Date 为协调世界时 (UTC) 日期和时间值的对象。 可以使用 convertToLocalClientTime 方法将 end 属性值转换为客户端的本地日期和时间。

使用 Time.setAsync 方法设置结束时间时，应使用 convertToUtcClientTime 方法将客户端的本地时间转换为服务器的 UTC。
from

获取邮件发件人的电子邮件地址。

from 和 sender 属性表示同一个人，邮件由代理人发送的除外。 在这种情况下， from 属性表示委托器，属性 sender 表示委托。

注意：属性recipientTypeEmailAddressDetails中 from 对象的属性未定义。

属性 from 返回 对象 EmailAddressDetails 。
internetMessageId

获取电子邮件的 Internet 消息标识符。

重要提示：在 “已发送邮件” 文件夹中， internetMessageId 最近发送的项目可能尚不可用。 在这种情况下，请考虑使用 Exchange Web Services从服务器获取此属性。
itemClass

获取所选邮件的 Exchange Web Services 项类。
itemId

获取当前 项的 Exchange Web Services 项标识符 。

itemId 属性在撰写模式下不可用。 如果需要项目标识符，saveAsync 方法可用于将项目保存到存储，这将在回调函数的 asyncResult.value 参数中返回项目标识符。

注意：属性返回的 itemId 标识符与 Exchange Web Services 项标识符相同。 itemId 属性与 Outlook 条目 ID 或 Outlook REST API 使用的 ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。 有关详细信息，请参阅 使用 Outlook 外接程序中的 Outlook REST API。
itemType

获取实例表示的项的类型。

属性 itemType 返回枚举值之 ItemType 一，指示项目对象实例是消息还是约会。
location

获取会议请求的位置。

location 属性返回一个包含约会位置的字符串。
normalizedSubject

获取项目的主题，删除所有前缀 (包括 RE： 和 FWD：) 。

属性 normalizedSubject 获取项目的主题，其中包含电子邮件程序添加的任何标准前缀 (如 RE： 和 FW：) 。 若要获取包含完整前缀的项目主题，请使用 subject 属性。
notificationMessages

获取项目的通知邮件。
recurrence

获取约会的重复模式。 获取会议请求的重复模式。 约会项目的读取和撰写模式。 会议请求项的读取模式。

如果项目是系列Recurrence或系列中的实例，则 recurrence 属性返回定期约会或会议请求的对象。 null 返回单个约会和单个约会的会议请求。 undefined 对于非会议请求的消息，返回 。

注意：会议请求的 itemClass 值为 IPM.Schedule.Meeting.Request。

注意：如果 recurrence 对象为 null，则表示对象是单个约会或会议请求，而不是序列的一部分。
sender

获取电子邮件发件人的电子邮件地址。

from 和 sender 属性表示同一个人，邮件由代理人发送的除外。 在这种情况下， from 属性表示委托器，属性 sender 表示委托。

注意：属性recipientTypeEmailAddressDetails中 sender 对象的属性未定义。
seriesId

获取实例所属的序列的 ID。

在 Outlook 网页版 和桌面客户端中， seriesId 返回此项所属的父 (系列) 项的 Exchange Web Services (EWS) ID。 但是，在 iOS 和 Android 上， seriesId 返回父项的 REST ID。

注意：属性返回的 seriesId 标识符与 Exchange Web Services 项标识符相同。 属性 seriesId 与 Outlook REST API 使用的 Outlook ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。 有关详细信息，请参阅 使用 Outlook 外接程序中的 Outlook REST API。

对于没有父项（如单个约会、系列项目或会议请求）的项目，属性seriesIdnull返回 ，对于不是会议请求的任何其他项目，则返回 undefined 。
start

获取约会开始的日期和时间。

属性 start 是表示 Date 为协调世界时 (UTC) 日期和时间值的对象。 可以使用 convertToLocalClientTime 方法将值转换为客户端的本地日期和时间。
subject

获取在项的主题字段中显示的说明。

subject 属性获取或设置由电子邮件服务器发送项目时的整个主题。

subject 属性返回一个字符串。 normalizedSubject使用 属性获取主题减去任何前导前缀，例如 RE： 和 FW：。
to

提供对邮件的“收件人”行上的收件人的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性to返回一个数组，该数组包含邮件的“收件人”行中列出的每个收件人的 EmailAddressDetails 对象。 返回的最大收件人数因 Outlook 客户端而异。

  • Windows：500 个收件人

  • Android、经典 Mac UI、iOS：100 个收件人

  • Web 浏览器：20 个收件人

  • 新 Mac UI：无限制

方法

addHandlerAsync(eventType, handler, options, callback)

添加支持事件的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。
addHandlerAsync(eventType, handler, callback)

添加支持事件的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。
displayReplyAllForm(formData)

显示一个答复表单，其中包括所选邮件的发件人和所有收件人或组织者以及所选约会的所有与会者。
displayReplyAllFormAsync(formData, options, callback)

显示一个答复表单，其中包括所选邮件的发件人和所有收件人或组织者以及所选约会的所有与会者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyAllFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

注意：iOS 或 Android 版 Outlook 不支持此方法。
displayReplyAllFormAsync(formData, callback)

显示一个答复表单，其中包括所选邮件的发件人和所有收件人或组织者以及所选约会的所有与会者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyAllFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

注意：iOS 或 Android 版 Outlook 不支持此方法。
displayReplyForm(formData)

显示答复窗体，其中仅包括所选邮件的发件人或所选约会的组织者。
displayReplyFormAsync(formData, options, callback)

显示答复窗体，其中仅包括所选邮件的发件人或所选约会的组织者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

注意：iOS 或 Android 版 Outlook 不支持此方法。
displayReplyFormAsync(formData, callback)

显示答复窗体，其中仅包括所选邮件的发件人或所选约会的组织者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

注意：iOS 或 Android 版 Outlook 不支持此方法。
getAllInternetHeadersAsync(options, callback)

以字符串的形式获取消息的所有 Internet 标头。

若要了解详细信息，请参阅在 Outlook 外接程序中获取和设置邮件的 Internet 标头。
getAllInternetHeadersAsync(callback)

以字符串的形式获取消息的所有 Internet 标头。

若要了解详细信息，请参阅在 Outlook 外接程序中获取和设置邮件的 Internet 标头。
getAsFileAsync(options, callback)

获取以 Base64 编码的 EML 格式的当前消息。
getAsFileAsync(callback)

获取以 Base64 编码的 EML 格式的当前消息。
getAttachmentContentAsync(attachmentId, options, callback)

从邮件或约会中获取附件，并将其作为 AttachmentContent 对象返回。

方法 getAttachmentContentAsync 从项中获取具有指定标识符的附件。 最佳做法是，应从 item.attachments 调用获取附件的标识符，然后在同一会话中使用该标识符来检索附件。 在 Outlook 网页版和移动设备上，附件标识符只在同一个会话中才有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。
getAttachmentContentAsync(attachmentId, callback)

从邮件或约会中获取附件，并将其作为 AttachmentContent 对象返回。

方法 getAttachmentContentAsync 从项中获取具有指定标识符的附件。 最佳做法是，应从 item.attachments 调用获取附件的标识符，然后在同一会话中使用该标识符来检索附件。 在 Outlook 网页版和移动设备上，附件标识符只在同一个会话中才有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。
getEntities()

获取在所选项目的正文中找到的实体。
getEntitiesByType(entityType)

获取所选项目的正文中找到的指定实体类型的所有实体的数组。
getFilteredEntitiesByName(name)

返回所选项中传递 XML 清单文件中定义的命名筛选器的已知实体。
getInitializationContextAsync(options, callback)

获取当 加载项被可操作消息激活时传递的初始化数据。
getInitializationContextAsync(callback)

获取当 加载项被可操作消息激活时传递的初始化数据。
getRegExMatches()

返回所选项中与 XML 清单文件中定义的正则表达式匹配的字符串值。
getRegExMatchesByName(name)

返回所选项中与 XML 清单文件中定义的命名正则表达式匹配的字符串值。
getSelectedEntities()

获取在用户已选择的突出显示匹配项中找到的实体。 突出显示的匹配项适用于上下文外接程序。

注意：此方法与 Outlook 外接程序的激活规则功能一起使用，Office 外接程序的 Teams 清单不支持此功能， (预览版) 。

注意：iOS 或 Android 版 Outlook 不支持此方法。
getSelectedRegExMatches()

返回与 XML 清单文件中定义的正则表达式匹配的突出显示匹配项中的字符串值。 突出显示的匹配项适用于上下文外接程序。
getSharedPropertiesAsync(options, callback)

获取共享文件夹或共享邮箱中约会或邮件的属性。

有关使用此 API 的详细信息，请参阅 在 Outlook 外接程序中启用共享文件夹和共享邮箱方案。
getSharedPropertiesAsync(callback)

获取共享文件夹或共享邮箱中约会或邮件的属性， (现在以预览) 。

有关使用此 API 的详细信息，请参阅 在 Outlook 外接程序中启用共享文件夹和共享邮箱方案。
loadCustomPropertiesAsync(callback, userContext)

异步加载所选项目上此外接程序的自定义属性。

自定义属性以键值对的形式存储在每个应用、每个项目的基础上。 此方法在回调中返回 CustomProperties 对象，该对象提供访问特定于当前项和当前加载项的自定义属性的方法。 自定义属性不会对项进行加密，因此不应将其用作安全存储。

自定义属性作为 asyncResult.value 属性中的 CustomProperties 对象提供。 此对象可用于从邮件项获取、设置、保存和删除自定义属性。
removeHandlerAsync(eventType, options, callback)

删除受支持事件类型的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。
removeHandlerAsync(eventType, callback)

删除受支持事件类型的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

属性详细信息

attachments

获取项的附件作为数组。

attachments: AttachmentDetails[];

属性值

Office.AttachmentDetails[]

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

注意：某些类型的文件由于潜在的安全问题而被 Outlook 阻止，因此不会返回。 有关详细信息，请参阅 Outlook 中阻止的附件。

示例

// The following code builds an HTML string with details of all attachments on the current item.
const item = Office.context.mailbox.item;
let outputString = "";

if (item.attachments.length > 0) {
    for (let i = 0 ; i < item.attachments.length ; i++) {
        const attachment = item.attachments[i];
        outputString += "<BR>" + i + ". Name: ";
        outputString += attachment.name;
        outputString += "<BR>ID: " + attachment.id;
        outputString += "<BR>contentType: " + attachment.contentType;
        outputString += "<BR>size: " + attachment.size;
        outputString += "<BR>attachmentType: " + attachment.attachmentType;
        outputString += "<BR>isInline: " + attachment.isInline;
    }
}

console.log(outputString);

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/get-attachments-read.yaml

const attachments = Office.context.mailbox.item.attachments;
console.log(attachments);

body

获取一个提供用于处理项目正文的方法的对象。

body: Body;

属性值

Office.Body

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// This example gets the body of the item as plain text.
Office.context.mailbox.item.body.getAsync(
    "text",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
        // Do something with the result.
    });

// The following is an example of the result parameter passed to the callback function.
{
    "value": "TEXT of whole body (including threads below)",
    "status": "succeeded",
    "asyncContext": "This is passed to the callback"
}

categories

获取一个 对象，该对象提供用于管理项类别的方法。

categories: Categories;

属性值

Office.Categories

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Categories assigned to this item:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

// Note: In order for you to successfully add a category,
// it must be in the mailbox categories master list.

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const masterCategories = asyncResult.value;
    if (masterCategories && masterCategories.length > 0) {
      // Grab the first category from the master list.
      const categoryToAdd = [masterCategories[0].displayName];
      Office.context.mailbox.item.categories.addAsync(categoryToAdd, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully assigned category '${categoryToAdd}' to item.`);
        } else {
          console.log("categories.addAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories in the master list on this mailbox. You can add categories using Office.context.mailbox.masterCategories.addAsync.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      // Grab the first category assigned to this item.
      const categoryToRemove = [categories[0].displayName];
      Office.context.mailbox.item.categories.removeAsync(categoryToRemove, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully unassigned category '${categoryToRemove}' from this item.`);
        } else {
          console.log("categories.removeAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

cc

提供对邮件的抄送 (Cc) 收件人的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性cc返回一个数组，该数组包含邮件抄送行中列出的每个收件人的 EmailAddressDetails 对象。 返回的最大收件人数因 Outlook 客户端而异。

  • Windows：500 个收件人

  • Android、经典 Mac UI、iOS：100 个收件人

  • Web 浏览器：20 个收件人

  • 新 Mac UI：无限制

cc: EmailAddressDetails[];

属性值

Office.EmailAddressDetails[]

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-cc-message-read.yaml

const msgCc = Office.context.mailbox.item.cc;
console.log("Message copied to:");
for (let i = 0; i < msgCc.length; i++) {
  console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
}

conversationId

获取包含特定消息的电子邮件会话的标识符。

如果在阅读窗体或撰写窗体的回复中激活邮件应用程序，则此属性可以获得一个整数值。 如果用户随后更改了回复邮件的主题（若发送回复），则该邮件的对话 ID 将改变且之前获取的值将不适用。

对于撰写窗体的新项目，此属性获得一个 null 值。 如果用户设置一个主题并保存该项目，conversationId 属性将返回一个值。

conversationId: string;

属性值

string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Conversation ID: ${Office.context.mailbox.item.conversationId}`);

dateTimeCreated

获取项目创建的日期和时间。

dateTimeCreated: Date;

属性值

Date

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Creation date and time: ${Office.context.mailbox.item.dateTimeCreated}`);

dateTimeModified

获取项目最近一次修改的日期和时间。

dateTimeModified: Date;

属性值

Date

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：约会与会者

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

示例

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

console.log(`Date and time item last modified: ${Office.context.mailbox.item.dateTimeModified}`);

display

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

获取一个 对象，用于临时设置在阅读模式下消息的正文或主题中显示的内容。

display: Display;

属性值

Office.Display

注解

[ API 集：邮箱预览 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/99-preview-apis/set-displayed-body-subject.yaml

// This snippet temporarily sets the content displayed in the body of a message in read mode.
// The set content will remain visible until the user switches to a different message in the Reading Pane or closes the window of the current message.
const bodyText = $("#body-text-field")
  .val()
  .toString();
Office.context.mailbox.item.display.body.setAsync(bodyText, (asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(`Action failed with error: ${asyncResult.error.message}`);
    return;
  }

  console.log("Temporarily set the content displayed in the body.");
});

end

获取约会结束的日期和时间。

属性 end 是表示 Date 为协调世界时 (UTC) 日期和时间值的对象。 可以使用 convertToLocalClientTime 方法将 end 属性值转换为客户端的本地日期和时间。

使用 Time.setAsync 方法设置结束时间时，应使用 convertToUtcClientTime 方法将客户端的本地时间转换为服务器的 UTC。

end: Date;

属性值

Date

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Appointment ends: ${Office.context.mailbox.item.end}`);

from

获取邮件发件人的电子邮件地址。

from 和 sender 属性表示同一个人，邮件由代理人发送的除外。 在这种情况下， from 属性表示委托器，属性 sender 表示委托。

注意：属性recipientTypeEmailAddressDetails中 from 对象的属性未定义。

属性 from 返回 对象 EmailAddressDetails 。

from: EmailAddressDetails;

属性值

Office.EmailAddressDetails

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-from-message-read.yaml

const msgFrom = Office.context.mailbox.item.from;
console.log("Message received from: " + msgFrom.displayName + " (" + msgFrom.emailAddress + ")");

internetMessageId

获取电子邮件的 Internet 消息标识符。

重要提示：在 “已发送邮件” 文件夹中， internetMessageId 最近发送的项目可能尚不可用。 在这种情况下，请考虑使用 Exchange Web Services从服务器获取此属性。

internetMessageId: string;

属性值

string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Internet message ID: ${Office.context.mailbox.item.internetMessageId}`);

itemClass

获取所选邮件的 Exchange Web Services 项类。

itemClass: string;

属性值

string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

重要说明：

下表列出了邮件的默认项类。

Item 类 说明
Ipm。注意 新邮件和邮件答复
IPM.Schedule.Meeting.Request 会议请求
IPM.Schedule.Meeting.Canceled 会议取消
Ipm。Schedule.Meeting.Resp.Neg 响应以拒绝会议要求
Ipm。Schedule.Meeting.Resp.Pos 接受会议请求的响应
Ipm。Schedule.Meeting.Resp.Tent 响应以暂时接受会议要求

可以创建扩展默认项类的自定义类。 例如， IPM.Note.Contoso。

示例

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

console.log(`Item class: ${Office.context.mailbox.item.itemClass}`);

itemId

获取当前 项的 Exchange Web Services 项标识符 。

itemId 属性在撰写模式下不可用。 如果需要项目标识符，saveAsync 方法可用于将项目保存到存储，这将在回调函数的 asyncResult.value 参数中返回项目标识符。

注意：属性返回的 itemId 标识符与 Exchange Web Services 项标识符相同。 itemId 属性与 Outlook 条目 ID 或 Outlook REST API 使用的 ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。 有关详细信息，请参阅 使用 Outlook 外接程序中的 Outlook REST API。

itemId: string;

属性值

string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// The following code checks for the presence of an item
// identifier. If the `itemId` property returns `null` or
// `undefined`, it saves the item to the store and gets the
// item identifier from the asynchronous result.
// **Important**: `saveAsync` was introduced with requirement set 1.3
// so you can't get the `itemId` in Compose mode in earlier sets.
let itemId = Office.context.mailbox.item.itemId;
if (itemId === null || itemId == undefined) {
    Office.context.mailbox.item.saveAsync(function(result) {
        itemId = result.value;
    });
}

itemType

获取实例表示的项的类型。

属性 itemType 返回枚举值之 ItemType 一，指示项目对象实例是消息还是约会。

itemType: MailboxEnums.ItemType | string;

属性值

Office.MailboxEnums.ItemType | string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

const itemType = Office.context.mailbox.item.itemType;
switch (itemType) {
    case Office.MailboxEnums.ItemType.Appointment:
        console.log(`Current item is an ${itemType}.`);
        break;
    case Office.MailboxEnums.ItemType.Message:
        console.log(`Current item is a ${itemType}. A message could be an email, meeting request, meeting response, or meeting cancellation.`);
        break;
}

location

获取会议请求的位置。

location 属性返回一个包含约会位置的字符串。

location: string;

属性值

string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Appointment location: ${Office.context.mailbox.item.location}`);

normalizedSubject

获取项目的主题，删除所有前缀 (包括 RE： 和 FWD：) 。

属性 normalizedSubject 获取项目的主题，其中包含电子邮件程序添加的任何标准前缀 (如 RE： 和 FW：) 。 若要获取包含完整前缀的项目主题，请使用 subject 属性。

normalizedSubject: string;

属性值

string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Normalized subject: ${Office.context.mailbox.item.normalizedSubject}`);

notificationMessages

获取项目的通知邮件。

notificationMessages: NotificationMessages;

属性值

Office.NotificationMessages

注解

[ API 集：邮箱 1.3 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml

// Adds a progress indicator to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
    message: "Progress indicator with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds an informational notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Non-persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: false
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds a persistent information notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: true
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Gets all the notification messages and their keys for the current mail item.
Office.context.mailbox.item.notificationMessages.getAllAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

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

...

// Replaces a notification message of a given key with another message.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.replaceAsync(
  id,
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Notification message with id = " + id + " has been replaced with an informational message.",
    icon: "icon2",
    persistent: false
  },
  handleResult);

...

// Removes a notification message from the current mail item.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);

recurrence

获取约会的重复模式。 获取会议请求的重复模式。 约会项目的读取和撰写模式。 会议请求项的读取模式。

如果项目是系列Recurrence或系列中的实例，则 recurrence 属性返回定期约会或会议请求的对象。 null 返回单个约会和单个约会的会议请求。 undefined 对于非会议请求的消息，返回 。

注意：会议请求的 itemClass 值为 IPM.Schedule.Meeting.Request。

注意：如果 recurrence 对象为 null，则表示对象是单个约会或会议请求，而不是序列的一部分。

recurrence: Recurrence;

属性值

Office.Recurrence

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-recurrence-read.yaml

const recurrence = Office.context.mailbox.item.recurrence;

if (recurrence === undefined) {
  console.log("This item is a message but not a meeting request.");
} else if (recurrence === null) {
  console.log("This is a single appointment.");
} else {
  console.log(JSON.stringify(recurrence));
}

sender

获取电子邮件发件人的电子邮件地址。

from 和 sender 属性表示同一个人，邮件由代理人发送的除外。 在这种情况下， from 属性表示委托器，属性 sender 表示委托。

注意：属性recipientTypeEmailAddressDetails中 sender 对象的属性未定义。

sender: EmailAddressDetails;

属性值

Office.EmailAddressDetails

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-sender-message-read.yaml

const msgSender = Office.context.mailbox.item.sender;
console.log("Sender: " + msgSender.displayName + " (" + msgSender.emailAddress + ")");

seriesId

获取实例所属的序列的 ID。

在 Outlook 网页版 和桌面客户端中， seriesId 返回此项所属的父 (系列) 项的 Exchange Web Services (EWS) ID。 但是，在 iOS 和 Android 上， seriesId 返回父项的 REST ID。

注意：属性返回的 seriesId 标识符与 Exchange Web Services 项标识符相同。 属性 seriesId 与 Outlook REST API 使用的 Outlook ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。 有关详细信息，请参阅 使用 Outlook 外接程序中的 Outlook REST API。

对于没有父项（如单个约会、系列项目或会议请求）的项目，属性seriesIdnull返回 ，对于不是会议请求的任何其他项目，则返回 undefined 。

seriesId: string;

属性值

string

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-series-id.yaml

const seriesId = Office.context.mailbox.item.seriesId;

if (seriesId === undefined) {
  console.log("This is a message that's not a meeting request.");
} else if (seriesId === null) {
  console.log("This is a single appointment, a parent series, or a meeting request for a series or single meeting.");
} else {
  console.log("This is an instance belonging to series with ID " + seriesId);
}

start

获取约会开始的日期和时间。

属性 start 是表示 Date 为协调世界时 (UTC) 日期和时间值的对象。 可以使用 convertToLocalClientTime 方法将值转换为客户端的本地日期和时间。

start: Date;

属性值

Date

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Appointment starts: ${Office.context.mailbox.item.start}`);

subject

获取在项的主题字段中显示的说明。

subject 属性获取或设置由电子邮件服务器发送项目时的整个主题。

subject 属性返回一个字符串。 normalizedSubject使用 属性获取主题减去任何前导前缀，例如 RE： 和 FW：。

subject: string;

属性值

string

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

console.log(`Subject: ${Office.context.mailbox.item.subject}`);

to

提供对邮件的“收件人”行上的收件人的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性to返回一个数组，该数组包含邮件的“收件人”行中列出的每个收件人的 EmailAddressDetails 对象。 返回的最大收件人数因 Outlook 客户端而异。

  • Windows：500 个收件人

  • Android、经典 Mac UI、iOS：100 个收件人

  • Web 浏览器：20 个收件人

  • 新 Mac UI：无限制

to: EmailAddressDetails[];

属性值

Office.EmailAddressDetails[]

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-to-message-read.yaml

const msgTo = Office.context.mailbox.item.to;
const distributionLists = [];
const externalRecipients = [];
const internalRecipients = [];
const otherRecipients = [];
for (let i = 0; i < msgTo.length; i++) {
    switch (msgTo[i].recipientType) {
    case Office.MailboxEnums.RecipientType.DistributionList:
        distributionLists.push(msgTo[i]);
        break;
    case Office.MailboxEnums.RecipientType.ExternalUser:
        externalRecipients.push(msgTo[i]);
        break;
    case Office.MailboxEnums.RecipientType.User:
        internalRecipients.push(msgTo[i]);
        break;
    case Office.MailboxEnums.RecipientType.Other:
        otherRecipients.push(msgTo[i]);
    }
}

if (distributionLists.length > 0) {
    console.log("Distribution Lists:");
    distributionLists.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

if (externalRecipients.length > 0) {
    console.log("External Recipients:");
    externalRecipients.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

if (internalRecipients.length > 0) {
    console.log("Internal Recipients:");
    internalRecipients.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

if (otherRecipients.length > 0) {
    console.log("Other Recipients:");
    otherRecipients.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

方法详细信息

addHandlerAsync(eventType, handler, options, callback)

添加支持事件的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

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

参数

eventType

Office.EventType | string

应调用处理程序的事件。

handler

any

用于处理事件的函数。 此函数必须接受一个参数，即对象文本。 参数type上的 属性将与传递给 的 addHandlerAsynceventType parameter 匹配。

options
Office.AsyncContextOptions

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

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

function myHandlerFunction(eventarg) {
    if (eventarg.attachmentStatus === Office.MailboxEnums.AttachmentStatus.Added) {
        const attachment = eventarg.attachmentDetails;
        console.log("Event Fired and Attachment Added!");
        getAttachmentContentAsync(attachment.id, options, callback);
    }
}

Office.context.mailbox.item.addHandlerAsync(Office.EventType.AttachmentsChanged, myHandlerFunction, myCallback);

addHandlerAsync(eventType, handler, callback)

添加支持事件的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

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

参数

eventType

Office.EventType | string

应调用处理程序的事件。

handler

any

用于处理事件的函数。 此函数必须接受一个参数，即对象文本。 参数type上的 属性将与传递给 的 addHandlerAsynceventType parameter 匹配。

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

displayReplyAllForm(formData)

显示一个答复表单，其中包括所选邮件的发件人和所有收件人或组织者以及所选约会的所有与会者。

displayReplyAllForm(formData: string | ReplyFormData): void;

参数

formData

string | Office.ReplyFormData

一个包含文本和 HTML 且表示答复窗体的正文的字符串。 字符串限制为 32 KB 或包含正文或附件数据和回调函数的 ReplyFormData 对象。

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：约会与会者

重要说明：

  • 在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

  • 如果任意字符串参数超出其限制，displayReplyForm 将引发异常。

  • 在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

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

示例

// The following code passes a string to the `displayReplyAllForm` method.
Office.context.mailbox.item.displayReplyAllForm('hello there');
Office.context.mailbox.item.displayReplyAllForm('<b>hello there</b>');

// Reply with an empty body.
Office.context.mailbox.item.displayReplyAllForm({});

// Reply with just a body.
Office.context.mailbox.item.displayReplyAllForm(
{
'htmlBody' : 'hi'
});

// Reply with a body and a file attachment.
Office.context.mailbox.item.displayReplyAllForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
        'type' : Office.MailboxEnums.AttachmentType.File,
        'name' : 'squirrel.png',
        'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        }
    ]
});

// Reply with a body and an item attachment.
Office.context.mailbox.item.displayReplyAllForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
        'type' : 'item',
        'name' : 'rand',
        'itemId' : Office.context.mailbox.item.itemId
        }
    ]
});

// Reply with a body, file attachment, item attachment, and a callback.
Office.context.mailbox.item.displayReplyAllForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : Office.MailboxEnums.AttachmentType.File,
            'name' : 'squirrel.png',
            'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        },
        {
            'type' : 'item',
            'name' : 'rand',
            'itemId' : Office.context.mailbox.item.itemId
        }
    ],
    'callback' : function(asyncResult)
    {
        console.log(asyncResult.value);
    }
});

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

Office.context.mailbox.item.displayReplyAllForm("This is a reply ALL with <b>some bold text</b>.");

displayReplyAllFormAsync(formData, options, callback)

显示一个答复表单，其中包括所选邮件的发件人和所有收件人或组织者以及所选约会的所有与会者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyAllFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

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

displayReplyAllFormAsync(formData: string | ReplyFormData, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

formData

string | Office.ReplyFormData

一个包含文本和 HTML 且表示答复窗体的正文的字符串。 字符串限制为 32 KB 或包含正文或附件数据和回调函数的 ReplyFormData 对象。

options
Office.AsyncContextOptions

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

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.9 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

Office.context.mailbox.item.displayReplyAllFormAsync("This is a reply ALL with <b>some bold text</b>.", function(
  asyncResult
) {
  console.log(JSON.stringify(asyncResult));
});

displayReplyAllFormAsync(formData, callback)

显示一个答复表单，其中包括所选邮件的发件人和所有收件人或组织者以及所选约会的所有与会者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyAllFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

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

displayReplyAllFormAsync(formData: string | ReplyFormData, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

formData

string | Office.ReplyFormData

一个包含文本和 HTML 且表示答复窗体的正文的字符串。 字符串限制为 32 KB 或包含正文或附件数据和回调函数的 ReplyFormData 对象。

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.9 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

displayReplyForm(formData)

显示答复窗体，其中仅包括所选邮件的发件人或所选约会的组织者。

displayReplyForm(formData: string | ReplyFormData): void;

参数

formData

string | Office.ReplyFormData

一个包含文本和 HTML 且表示答复窗体的正文的字符串。 字符串限制为 32 KB 或包含正文或附件数据和回调函数的 ReplyFormData 对象。

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

重要说明：

  • 在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

  • 如果任意字符串参数超出其限制，displayReplyForm 将引发异常。

  • 在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

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

示例

// The following code passes a string to the `displayReplyForm` method.
Office.context.mailbox.item.displayReplyForm('hello there');
Office.context.mailbox.item.displayReplyForm('<b>hello there</b>');

// Reply with an empty body.
Office.context.mailbox.item.displayReplyForm({});

// Reply with just a body.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi'
});

// Reply with a body and a file attachment.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : Office.MailboxEnums.AttachmentType.File,
            'name' : 'squirrel.png',
            'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        }
    ]
});

// Reply with a body and an item attachment.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : 'item',
            'name' : 'rand',
            'itemId' : Office.context.mailbox.item.itemId
        }
    ]
});

// Reply with a body, file attachment, item attachment, and a callback.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : Office.MailboxEnums.AttachmentType.File,
            'name' : 'squirrel.png',
            'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        },
        {
            'type' : 'item',
            'name' : 'rand',
            'itemId' : Office.context.mailbox.item.itemId
        }
    ],
    'callback' : function(asyncResult)
    {
        console.log(asyncResult.value);
    }
});

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

Office.context.mailbox.item.displayReplyForm("This is a reply with <i>some text in italics</i>.");

...

Office.context.mailbox.item.displayReplyForm({
  htmlBody: "This is a reply with a couple of attachments - an inline image and an item<br><img src='cid:dog.jpg'>",
  attachments: [
    { type: "file", url: "http://i.imgur.com/9S36xvA.jpg", name: "dog.jpg", isInline: true },
    { type: "item", itemId: Office.context.mailbox.item.itemId, name: "test_email.msg" }
  ],
  options: { asyncContext: null },
  callback: function(result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
      console.error(`Action failed with message ${result.error.message}`);
    }
  }
});

displayReplyFormAsync(formData, options, callback)

显示答复窗体，其中仅包括所选邮件的发件人或所选约会的组织者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

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

displayReplyFormAsync(formData: string | ReplyFormData, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

formData

string | Office.ReplyFormData

一个包含文本和 HTML 且表示答复窗体的正文的字符串。 字符串限制为 32 KB 或包含正文或附件数据和回调函数的 ReplyFormData 对象。

options
Office.AsyncContextOptions

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

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.9 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

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

Office.context.mailbox.item.displayReplyFormAsync("This is a reply with <i>some text in italics</i>.", function(
  asyncResult
) {
  console.log(JSON.stringify(asyncResult));
});

...

// 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.item.displayReplyFormAsync(
  {
    htmlBody: "This is a reply with a couple of attachments - an inline image and an item<br><img src='cid:dog.jpg'>",
    attachments: [
      { type: "file", url: "http://i.imgur.com/9S36xvA.jpg", name: "dog.jpg", isInline: true },
      { type: "item", itemId: Office.context.mailbox.item.itemId, name: "test_email.msg" }
    ]
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayReplyFormAsync(formData, callback)

显示答复窗体，其中仅包括所选邮件的发件人或所选约会的组织者。

在Outlook 网页版中，答复窗体在 3 列视图中显示为弹出窗体，在 2 列或 1 列视图中显示为弹出窗体。

如果任意字符串参数超出其限制，displayReplyFormAsync 将引发异常。

在 参数中 formData.attachments 指定附件时，Outlook 会尝试下载所有附件并将其附加到答复表单。 如果无法添加任何附件，则在窗体 UI 中显示错误。 如果这不可能，则不引发错误消息。

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

displayReplyFormAsync(formData: string | ReplyFormData, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

formData

string | Office.ReplyFormData

一个包含文本和 HTML 且表示答复窗体的正文的字符串。 字符串限制为 32 KB 或包含正文或附件数据和回调函数的 ReplyFormData 对象。

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.9 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

getAllInternetHeadersAsync(options, callback)

以字符串的形式获取消息的所有 Internet 标头。

若要了解详细信息，请参阅在 Outlook 外接程序中获取和设置邮件的 Internet 标头。

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

参数

options
Office.AsyncContextOptions

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

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 成功后，Internet 标头数据将在 属性中 asyncResult.value 以字符串的形式提供。 有关返回的字符串值的格式设置信息，请参阅 RFC 2183 。 如果调用失败，属性 asyncResult.error 将包含错误代码，其中包含失败的原因。

返回

void

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/70-mime-headers/get-internet-headers-message-read.yaml

Office.context.mailbox.item.getAllInternetHeadersAsync(function (asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Internet headers received successfully");
    if (asyncResult.value.match(/preferred-fruit:.*/gim)) {
      console.log("Sender's preferred fruit: " + asyncResult.value.match(/preferred-fruit:.*/gim)[0].slice(17));
    } else {
      console.log("Didn't receive header with sender's preferred fruit");
    }
    if (asyncResult.value.match(/preferred-vegetable:.*/gim)) {
      console.log(
        "Sender's preferred vegetable: " + asyncResult.value.match(/preferred-vegetable:.*/gim)[0].slice(21)
      );
    } else {
      console.log("Didn't receive header with sender's preferred vegetable");
    }
  } else {
    console.log("Error getting internet headers: " + JSON.stringify(asyncResult.error));
  }
});

getAllInternetHeadersAsync(callback)

以字符串的形式获取消息的所有 Internet 标头。

若要了解详细信息，请参阅在 Outlook 外接程序中获取和设置邮件的 Internet 标头。

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

参数

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 成功后，Internet 标头数据将在 属性中 asyncResult.value 以字符串的形式提供。 有关返回的字符串值的格式设置信息，请参阅 RFC 2183 。 如果调用失败，属性 asyncResult.error 将包含错误代码，其中包含失败的原因。

返回

void

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

getAsFileAsync(options, callback)

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

获取以 Base64 编码的 EML 格式的当前消息。

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

参数

options
Office.AsyncContextOptions

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

callback

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

方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在回调参数中传递的函数。 属性中 asyncResult.value 返回消息的 Base64 编码 EML 格式。 遇到的任何错误都会在 属性中 asyncResult.error 返回。

返回

void

注解

[ API 集：邮箱预览 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

getAsFileAsync(callback)

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

获取以 Base64 编码的 EML 格式的当前消息。

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

参数

callback

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

方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在回调参数中传递的函数。 属性中 asyncResult.value 返回消息的 Base64 编码 EML 格式。 遇到的任何错误都会在 属性中 asyncResult.error 返回。

返回

void

注解

[ API 集：邮箱预览 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/99-preview-apis/get-eml-format.yaml

Office.context.mailbox.item.getAsFileAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(`Error encountered during processing: ${asyncResult.error.message}`);
    return;
  }

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

getAttachmentContentAsync(attachmentId, options, callback)

从邮件或约会中获取附件，并将其作为 AttachmentContent 对象返回。

方法 getAttachmentContentAsync 从项中获取具有指定标识符的附件。 最佳做法是，应从 item.attachments 调用获取附件的标识符，然后在同一会话中使用该标识符来检索附件。 在 Outlook 网页版和移动设备上，附件标识符只在同一个会话中才有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。

getAttachmentContentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

参数

attachmentId

string

要获取的附件的标识符。

options
Office.AsyncContextOptions

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

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 如果调用失败，属性 asyncResult.error 将包含错误代码，其中包含失败的原因。

返回

void

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

错误：

  • AttachmentTypeNotSupported：不支持附件类型。 不支持的类型包括 RTF 格式的嵌入图像，或者电子邮件或日历项目以外的项目附件类型 (，例如联系人或任务项) 。

  • InvalidAttachmentId：附件标识符不存在。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/get-attachment-content.yaml

// Gets the attachments of the current message or appointment in read mode.
// The item.attachments call can only be used in read mode.
const attachments = item.attachments;
if (attachments.length <= 0) {
  console.log("Mail item has no attachments.");
  return;
}

for (let i = 0; i < attachments.length; i++) {
  // Log the attachment type and its contents to the console.
  item.getAttachmentContentAsync(attachments[i].id, handleAttachmentsCallback);
}

getAttachmentContentAsync(attachmentId, callback)

从邮件或约会中获取附件，并将其作为 AttachmentContent 对象返回。

方法 getAttachmentContentAsync 从项中获取具有指定标识符的附件。 最佳做法是，应从 item.attachments 调用获取附件的标识符，然后在同一会话中使用该标识符来检索附件。 在 Outlook 网页版和移动设备上，附件标识符只在同一个会话中才有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。

getAttachmentContentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

参数

attachmentId

string

要获取的附件的标识符。

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 如果调用失败，属性 asyncResult.error 将包含错误代码，其中包含失败的原因。

返回

void

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

错误：

  • AttachmentTypeNotSupported：不支持附件类型。 不支持的类型包括 RTF 格式的嵌入图像，或者电子邮件或日历项目以外的项目附件类型 (，例如联系人或任务项) 。

  • InvalidAttachmentId：附件标识符不存在。

getEntities()

获取在所选项目的正文中找到的实体。

getEntities(): Entities;

返回

Office.Entities

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：约会与会者

重要说明：

  • 基于实体的上下文 Outlook 加载项（包括 getEntities 方法）将在 2024 年第 2 季度停用。 停用此方法的工作将于 5 月开始，并持续到 6 月底。 6 月之后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。 基于实体的上下文加载项停用后，将继续支持正则表达式规则。 建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。 有关如何实现这些规则的指南，请参阅 使用正则表达式激活规则显示 Outlook 加载项。 若要详细了解基于实体的上下文 Outlook 加载项的停用，请参阅 基于实体的上下文 Outlook 加载项的停用。

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

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/basic-entities.yaml

const entities = Office.context.mailbox.item.getEntities();
let entityTypesFound = 0;
if (entities.addresses.length > 0) {
    console.warn("physical addresses: ");
    console.log(entities.addresses);
    entityTypesFound++;
}
if (entities.contacts.length > 0) {
    console.warn("contacts: ");
    entities.contacts.forEach(function (contact) { console.log(contact.personName); })
    entityTypesFound++;
}
if (entities.emailAddresses.length > 0) {
    console.warn("email addresses: ");
    console.log(entities.emailAddresses);
    entityTypesFound++;
}
if (entities.meetingSuggestions.length > 0) {
    console.warn("meetings suggestions: ");
    entities.meetingSuggestions.forEach(function (meetingSuggestion) { console.log(meetingSuggestion.meetingString); })
    entityTypesFound++;
}
if (entities.phoneNumbers.length > 0) {
    console.warn("phone numbers: ");
    entities.phoneNumbers.forEach(function (phoneNumber) { console.log(phoneNumber.originalPhoneString); })
    entityTypesFound++;
}
if (entities.taskSuggestions.length > 0) {
    console.warn("task suggestions: ");
    entities.taskSuggestions.forEach(function (taskSuggestion) { console.log(taskSuggestion.taskString); })
    entityTypesFound++;
}
if (entities.urls.length > 0) {
    console.warn("URLs: ");
    console.log(entities.urls);
    entityTypesFound++;
}
if (entityTypesFound == 0)
{
    console.log("No entities found on this item.");
}

getEntitiesByType(entityType)

获取所选项目的正文中找到的指定实体类型的所有实体的数组。

getEntitiesByType(entityType: MailboxEnums.EntityType | string): Array<string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion>;

参数

entityType

Office.MailboxEnums.EntityType | string

枚举值之 EntityType 一。

虽然限制使用此方法的最低权限 级别，但某些实体类型需要 读取项 才能访问，如下表所指定。

entityType 的值 返回的数组中对象的类型 所需权限级别
地址 String 受限
联系人 联系人 ReadItem
EmailAddress String ReadItem
MeetingSuggestion MeetingSuggestion ReadItem
PhoneNumber PhoneNumber 受限
TaskSuggestion TaskSuggestion ReadItem
URL 字符串 受限

返回

Array<string | Office.Contact | Office.MeetingSuggestion | Office.PhoneNumber | Office.TaskSuggestion>

如果 传入 entityType 的值不是枚举的有效成员 EntityType ，则 该方法返回 null。 如果指定类型的任何实体都不存在于该项目的正文中，该方法将返回空数组。 否则，返回的数组中对象的类型取决于 entityType 参数中请求实体的类型。

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 受限

适用的 Outlook 模式：邮件读取

重要说明：

  • 基于实体的上下文 Outlook 加载项（包括 getEntitiesByType 方法）将在 2024 年第 2 季度停用。 停用此方法的工作将于 5 月开始，并持续到 6 月底。 6 月之后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。 基于实体的上下文加载项停用后，将继续支持正则表达式规则。 建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。 有关如何实现这些规则的指南，请参阅 使用正则表达式激活规则显示 Outlook 加载项。 若要详细了解基于实体的上下文 Outlook 加载项的停用，请参阅 基于实体的上下文 Outlook 加载项的停用。

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

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/basic-entities.yaml

console.log(Office.context.mailbox.item.getEntitiesByType(Office.MailboxEnums.EntityType.Address));

getFilteredEntitiesByName(name)

返回所选项中传递 XML 清单文件中定义的命名筛选器的已知实体。

getFilteredEntitiesByName(name: string): Array<string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion>;

参数

name

string

定义筛选器匹配的 ItemHasKnownEntity 规则元素的名称。

返回

Array<string | Office.Contact | Office.MeetingSuggestion | Office.PhoneNumber | Office.TaskSuggestion>

与清单 XML 文件中的规则元素中 ItemHasKnownEntity 定义的正则表达式（具有指定 FilterName 元素值）相匹配的实体。 如果清单中没有 ItemHasKnownEntity 元素，其 FilterName 元素值与 参数匹配 name ，则 该方法返回 null。 name如果 参数与清单中的元素匹配ItemHasKnownEntity，但当前项中没有匹配的实体，则 该方法将返回一个空数组。

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：约会与会者

重要说明：

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/contextual.yaml

// This API would only work when you click on highlighted physical address that has the word "Way" in it.
console.log(Office.context.mailbox.item.getFilteredEntitiesByName("sampleFilterName"));

getInitializationContextAsync(options, callback)

获取当 加载项被可操作消息激活时传递的初始化数据。

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

参数

options
Office.AsyncContextOptions

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

callback

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

方法完成后，使用类型的Office.AsyncResult单个参数调用在 参数中callback传递的函数。 成功时，初始化上下文数据以字符串 (或空字符串的形式提供（如果 属性中 asyncResult.value 没有初始化上下文) ）。

返回

void

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        if (asyncResult.value.length > 0) {
            // The value is a string, parse to an object.
            const context = JSON.parse(asyncResult.value);
            // Do something with context.
        } else {
            // Empty context, treat as no context.
        }
    } else {
        // Handle the error.
    }
});

getInitializationContextAsync(callback)

获取当 加载项被可操作消息激活时传递的初始化数据。

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

参数

callback

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

方法完成后，使用类型的Office.AsyncResult单个参数调用在 参数中callback传递的函数。 成功时，初始化上下文数据以字符串 (或空字符串的形式提供（如果 属性中 asyncResult.value 没有初始化上下文) ）。

返回

void

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

getRegExMatches()

返回所选项中与 XML 清单文件中定义的正则表达式匹配的字符串值。

getRegExMatches(): any;

返回

any

一个包含匹配在清单 XML 文件中定义的正则表达式的字符串数组的对象。 每个数组的名称等于匹配规则的 RegExName 属性或FilterName匹配ItemHasRegularExpressionMatchItemHasKnownEntity规则的 属性的相应值。 对于 ItemHasRegularExpressionMatch 规则，匹配字符串必须发生在该规则指定的项目的属性中。 简单类型定义支持的属性。

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：约会与会者

重要说明：

  • 基于实体的上下文 Outlook 加载项将在 2024 年第 2 季度停用。 停用后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。 基于实体的上下文加载项停用后，将继续支持正则表达式规则。 建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。 有关如何实现这些规则的指南，请参阅 使用正则表达式激活规则显示 Outlook 加载项。 若要详细了解基于实体的上下文加载项的停用，请参阅 基于实体的上下文 Outlook 加载项的停用。

  • 此方法与 Outlook 外接程序的激活规则功能一起使用，Microsoft 365 (预览版的统一清单) 不支持此功能。

  • 如果在项的 body 属性上指定 ItemHasRegularExpressionMatch 规则，则正则表达式应进一步筛选正文，并且不应尝试返回项的整个正文。 使用等 .* 正则表达式获取项的整个正文并不总是返回预期结果。 而是使用 Body.getAsync 方法检索整个正文。

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

示例

// Consider an add-in manifest has the following `Rule` element:
//<Rule xsi:type="RuleCollection" Mode="And">
//  <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message" />
//  <Rule xsi:type="RuleCollection" Mode="Or">
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="veggies" RegExValue="tomato|onion|spinach|broccoli" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//  </Rule>
//</Rule>

// The object returned from `getRegExMatches` would have two properties: `fruits` and `veggies`.
//{
//'fruits': ['apple','banana','Banana','coconut'],
//'veggies': ['tomato','onion','spinach','broccoli']
//}

// The following example shows how to access the array of
// matches for the regular expression rule elements `fruits`
// and `veggies`, which are specified in the manifest.
const allMatches = Office.context.mailbox.item.getRegExMatches();
const fruits = allMatches.fruits;
const veggies = allMatches.veggies;

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/contextual.yaml

// This API would only work when you click on highlighted word "ScriptLab".
console.log(Office.context.mailbox.item.getRegExMatches());

getRegExMatchesByName(name)

返回所选项中与 XML 清单文件中定义的命名正则表达式匹配的字符串值。

getRegExMatchesByName(name: string): string[];

参数

name

string

定义筛选器匹配的 ItemHasRegularExpressionMatch 规则元素的名称。

返回

string[]

一个数组，其中包含与清单 XML 文件中的规则元素中 ItemHasRegularExpressionMatch 定义的正则表达式匹配的字符串，以及指定的 RegExName 元素值。

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：约会与会者

重要说明：

  • 基于实体的上下文 Outlook 加载项将在 2024 年第 2 季度停用。 停用后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。 基于实体的上下文加载项停用后，将继续支持正则表达式规则。 建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。 有关如何实现这些规则的指南，请参阅 使用正则表达式激活规则显示 Outlook 加载项。 若要详细了解基于实体的上下文加载项的停用，请参阅 基于实体的上下文 Outlook 加载项的停用。

  • 此方法与 Outlook 外接程序的激活规则功能一起使用，Microsoft 365 (预览版的统一清单) 不支持此功能。

  • 如果在项的 body 属性上指定 ItemHasRegularExpressionMatch 规则，则正则表达式应进一步筛选正文，并且不应尝试返回项的整个正文。 使用等 .* 正则表达式获取项的整个正文并不总是返回预期结果。 而是使用 Body.getAsync 方法检索整个正文。

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

示例

// Consider an add-in manifest has the following `Rule` element:
//<Rule xsi:type="RuleCollection" Mode="And">
//  <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message" />
//  <Rule xsi:type="RuleCollection" Mode="Or">
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="veggies" RegExValue="tomato|onion|spinach|broccoli" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//  </Rule>
//</Rule>

// The object returned from `getRegExMatches` would have two properties: `fruits` and `veggies`.
//{
//'fruits': ['apple','banana','Banana','coconut'],
//'veggies': ['tomato','onion','spinach','broccoli']
//}

const fruits = Office.context.mailbox.item.getRegExMatchesByName("fruits");
const veggies = Office.context.mailbox.item.getRegExMatchesByName("veggies");

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/contextual.yaml

// This API would only work when you click on highlighted word "ScriptLab".
console.log(Office.context.mailbox.item.getRegExMatchesByName("sampleRegexName"));

getSelectedEntities()

获取在用户已选择的突出显示匹配项中找到的实体。 突出显示的匹配项适用于上下文外接程序。

注意：此方法与 Outlook 外接程序的激活规则功能一起使用，Office 外接程序的 Teams 清单不支持此功能， (预览版) 。

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

getSelectedEntities(): Entities;

返回

Office.Entities

注解

[ API set： Mailbox 1.6 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

重要说明：

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/selected.yaml

const entities = Office.context.mailbox.item.getSelectedEntities();
let entityTypesFound = 0;
if (entities.addresses.length > 0) {
    console.warn("physical addresses: ");
    console.log(entities.addresses);
    entityTypesFound++;
}
if (entities.contacts.length > 0) {
    console.warn("contacts: ");
    entities.contacts.forEach(function (contact) { console.log(contact.personName); })
    entityTypesFound++;
}
if (entities.emailAddresses.length > 0) {
    console.warn("email addresses: ");
    console.log(entities.emailAddresses);
    entityTypesFound++;
}
if (entities.meetingSuggestions.length > 0) {
    console.warn("meetings suggestions: ");
    entities.meetingSuggestions.forEach(function (meetingSuggestion) { console.log(meetingSuggestion.meetingString); })
    entityTypesFound++;
}
if (entities.phoneNumbers.length > 0) {
    console.warn("phone numbers: ");
    entities.phoneNumbers.forEach(function (phoneNumber) { console.log(phoneNumber.originalPhoneString); })
    entityTypesFound++;
}
if (entities.taskSuggestions.length > 0) {
    console.warn("task suggestions: ");
    entities.taskSuggestions.forEach(function (taskSuggestion) { console.log(taskSuggestion.taskString); })
    entityTypesFound++;
}
if (entities.urls.length > 0) {
    console.warn("URLs: ");
    console.log(entities.urls);
    entityTypesFound++;
}
if (entityTypesFound == 0)
{
    console.error("Open add-in by clicking on a highlighted entity, for this API to return something useful.");
}

getSelectedRegExMatches()

返回与 XML 清单文件中定义的正则表达式匹配的突出显示匹配项中的字符串值。 突出显示的匹配项适用于上下文外接程序。

getSelectedRegExMatches(): any;

返回

any

一个包含匹配在清单 XML 文件中定义的正则表达式的字符串数组的对象。 每个数组的名称等于匹配 RegExName 规则的 ItemHasRegularExpressionMatch 属性或匹配 FilterName 规则的 ItemHasKnownEntity 属性的相应值。 对于 ItemHasRegularExpressionMatch 规则，匹配字符串必须发生在该规则指定的项目的属性中。 简单类型定义支持的属性。

注解

[ API set： Mailbox 1.6 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

重要说明：

  • 基于实体的上下文 Outlook 加载项将在 2024 年第 2 季度停用。 停用后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。 基于实体的上下文加载项停用后，将继续支持正则表达式规则。 建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。 有关如何实现这些规则的指南，请参阅 使用正则表达式激活规则显示 Outlook 加载项。 若要详细了解基于实体的上下文加载项的停用，请参阅 基于实体的上下文 Outlook 加载项的停用。

  • 此方法与 Outlook 外接程序的激活规则功能一起使用，Microsoft 365 (预览版的统一清单) 不支持此功能。

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

  • 如果在项的 body 属性上指定 ItemHasRegularExpressionMatch 规则，则正则表达式应进一步筛选正文，并且不应尝试返回项的整个正文。 使用 .* 等正则表达式获取项的整个正文并不总是返回预期结果。 而是使用 Body.getAsync 方法检索整个正文。

示例

// Consider an add-in manifest has the following `Rule` element:
//<Rule xsi:type="RuleCollection" Mode="And">
//  <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message" />
//  <Rule xsi:type="RuleCollection" Mode="Or">
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="veggies" RegExValue="tomato|onion|spinach|broccoli" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//  </Rule>
//</Rule>

// The object returned from `getRegExMatches` would have two properties: `fruits` and `veggies`.
//{
//'fruits': ['apple','banana','Banana','coconut'],
//'veggies': ['tomato','onion','spinach','broccoli']
//}

// The following example shows how to access the array of matches for the
// regular expression rule elements `fruits` and `veggies`, which are
// specified in the manifest.
const selectedMatches = Office.context.mailbox.item.getSelectedRegExMatches();
const fruits = selectedMatches.fruits;
const veggies = selectedMatches.veggies;

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/selected.yaml

const matches = Office.context.mailbox.item.getSelectedRegExMatches();
if (matches) {
    console.log(matches);
}
else {
    console.error("Open add-in by clicking on a highlighted regex match, for this API to return something useful.");
}

getSharedPropertiesAsync(options, callback)

获取共享文件夹或共享邮箱中约会或邮件的属性。

有关使用此 API 的详细信息，请参阅 在 Outlook 外接程序中启用共享文件夹和共享邮箱方案。

getSharedPropertiesAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SharedProperties>) => void): void;

参数

options
Office.AsyncContextOptions

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

callback

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

方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 属性 asyncResult.value 提供共享项的属性。

返回

void

注解

[ API set： Mailbox 1.8 for shared folder support， Mailbox 1.13 for shared mailbox support ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

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

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/65-delegates-and-shared-folders/get-shared-properties.yaml

if (!Office.context.mailbox.item.getSharedPropertiesAsync) {
  console.error("Try this sample on a message from a shared folder.");
  return;
}

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function(result) {
  if (result.status === Office.AsyncResultStatus.Succeeded && result.value !== "") {
    Office.context.mailbox.item.getSharedPropertiesAsync(
      {
        // Pass auth token along.
        asyncContext: result.value
      },
      function(result2) {
        let sharedProperties = result2.value;
        let delegatePermissions = sharedProperties.delegatePermissions;

        // Determine if user has the appropriate permission to do the operation.
        if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Read) != 0) {
          const ewsId = Office.context.mailbox.item.itemId;
          const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
          let rest_url =
            sharedProperties.targetRestUrl + "/v2.0/users/" + sharedProperties.targetMailbox + "/messages/" + restId;

          $.ajax({
            url: rest_url,
            dataType: "json",
            headers: { Authorization: "Bearer " + result2.asyncContext }
          })
            .done(function(response) {
              console.log(response);
            })
            .fail(function(error) {
              console.error(error);
            });
        }
      }
    );
  }
});

getSharedPropertiesAsync(callback)

获取共享文件夹或共享邮箱中约会或邮件的属性， (现在以预览) 。

有关使用此 API 的详细信息，请参阅 在 Outlook 外接程序中启用共享文件夹和共享邮箱方案。

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

参数

callback

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

方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。 属性 asyncResult.value 提供共享项的属性。

返回

void

注解

[ API set： Mailbox 1.8 for shared folder support， Mailbox 1.13 for shared mailbox support ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

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

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/65-delegates-and-shared-folders/get-shared-properties.yaml

if (!Office.context.mailbox.item.getSharedPropertiesAsync) {
  console.error("Try this sample on an item from a shared folder.");
  return;
}

Office.context.mailbox.item.getSharedPropertiesAsync(function(result) {
  console.log(result.value);
});

loadCustomPropertiesAsync(callback, userContext)

异步加载所选项目上此外接程序的自定义属性。

自定义属性以键值对的形式存储在每个应用、每个项目的基础上。 此方法在回调中返回 CustomProperties 对象，该对象提供访问特定于当前项和当前加载项的自定义属性的方法。 自定义属性不会对项进行加密，因此不应将其用作安全存储。

自定义属性作为 asyncResult.value 属性中的 CustomProperties 对象提供。 此对象可用于从邮件项获取、设置、保存和删除自定义属性。

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

参数

callback

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

方法完成后，使用类型的Office.AsyncResult单个参数调用在 参数中callback传递的函数。

userContext

any

可选。 开发人员可以提供他们想要在回调函数中访问的任何对象。 此对象可以通过回调函数中的 asyncResult.asyncContext 属性进行访问。

返回

void

注解

[ API set： Mailbox 1.1 ]

若要了解有关自定义属性的详细信息，请参阅 获取和设置 Outlook 外接程序的外接程序元数据。

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

示例

// The following example shows how to use the loadCustomPropertiesAsync method
// to asynchronously load custom properties that are specific to the current item.
// The example also shows how to use the saveAsync method to save these properties
// back to the server. After loading the custom properties, the example uses the
// get method to read the custom property myProp, the set method to write the
// custom property otherProp, and then finally calls the saveAsync method to save
// the custom properties.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        const mailbox = Office.context.mailbox;
        mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
    });
};

function customPropsCallback(asyncResult) {
    const customProps = asyncResult.value;
    const myProp = customProps.get("myProp");

    customProps.set("otherProp", "value");
    customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

Office.context.mailbox.item.loadCustomPropertiesAsync(function (result) {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Loaded following custom properties:");
    customProps = result.value;
    const dataKey = Object.keys(customProps)[0];
    const data = customProps[dataKey];
    for (let propertyName in data)
    {
      let propertyValue = data[propertyName];
      console.log(`${propertyName}: ${propertyValue}`);
    }              
  }
  else {
    console.error(`loadCustomPropertiesAsync failed with message ${result.error.message}`);
  }
});

removeHandlerAsync(eventType, options, callback)

删除受支持事件类型的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

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

参数

eventType

Office.EventType | string

应撤销处理程序的事件。

options
Office.AsyncContextOptions

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

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取

removeHandlerAsync(eventType, callback)

删除受支持事件类型的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

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

参数

eventType

Office.EventType | string

应撤销处理程序的事件。

callback

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

可选。 方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件读取