Office.AppointmentRead interface

Office.context.mailbox.item 的约会与会者模式。

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

父接口:

扩展

属性

attachments

获取项的附件作为数组。

body

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

dateTimeCreated

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

dateTimeModified

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

end

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

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

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

itemClass

获取所选约会的 Exchange Web Services 项类。

IPM.Appointment非定期约会和IPM.Appointment.Occurrence定期约会的返回值。

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

获取项目的通知邮件。

optionalAttendees

提供对事件的可选与会者的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性 optionalAttendees 返回一个数组,其中包含每个参加会议的可选与会者的 EmailAddressDetails 对象。 返回的最大与会者数因 Outlook 客户端而异。

  • Windows:500 名与会者

  • Android、经典 Mac UI、iOS:100 名与会者

  • 新 Mac UI、Web 浏览器:无限制

organizer

获取会议组织者的电子邮件属性。

requiredAttendees

提供对事件的必需与会者的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性 requiredAttendees 返回一个数组,其中包含参加会议的每个所需与会者的 EmailAddressDetails 对象。 返回的最大与会者数因 Outlook 客户端而异。

  • Windows:500 名与会者

  • Android、经典 Mac UI、iOS:100 名与会者

  • 新 Mac UI、Web 浏览器:无限制

start

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

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

subject

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

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

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

方法

displayReplyAllForm(formData)

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

displayReplyForm(formData)

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

getEntities()

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

getEntitiesByType(entityType)

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

getFilteredEntitiesByName(name)

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

getRegExMatches()

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

getRegExMatchesByName(name)

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

loadCustomPropertiesAsync(callback, userContext)

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

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

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

属性详细信息

attachments

获取项的附件作为数组。

attachments: 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;

属性值

注解

[ API set: Mailbox 1.1 ]

最低权限级别读取项

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

示例

// This example gets the body of the item as plain text.
Office.context.mailbox.item.body.getAsync(
    Office.CoercionType.Text,
    { asyncContext: "This is passed to the 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 message threads that appear below the current body)",
    "status": "succeeded",
    "asyncContext": "This is passed to the callback"
}

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}`);

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}`);

itemClass

获取所选约会的 Exchange Web Services 项类。

IPM.Appointment非定期约会和IPM.Appointment.Occurrence定期约会的返回值。

itemClass: string;

属性值

string

注解

最低权限级别读取项

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

重要说明:可以创建自定义类来扩展默认项类。 例如, IPM.Appointment.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;

属性值

注解

最低权限级别读取项

适用的 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 模式:约会与会者

示例

const location = Office.context.mailbox.item.location;
console.log("location: " + location);
// 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;

属性值

注解

[ 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);

optionalAttendees

提供对事件的可选与会者的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性 optionalAttendees 返回一个数组,其中包含每个参加会议的可选与会者的 EmailAddressDetails 对象。 返回的最大与会者数因 Outlook 客户端而异。

  • Windows:500 名与会者

  • Android、经典 Mac UI、iOS:100 名与会者

  • 新 Mac UI、Web 浏览器:无限制

optionalAttendees: EmailAddressDetails[];

属性值

注解

最低权限级别读取项

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

示例

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

const apptOptionalAttendees = Office.context.mailbox.item.optionalAttendees;
console.log("Optional attendees:");
for (let i = 0; i < apptOptionalAttendees.length; i++) {
  console.log(
    apptOptionalAttendees[i].displayName +
      " (" +
      apptOptionalAttendees[i].emailAddress +
      ") - response: " +
      apptOptionalAttendees[i].appointmentResponse
  );
}

organizer

获取会议组织者的电子邮件属性。

organizer: EmailAddressDetails;

属性值

注解

最低权限级别读取项

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

示例

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

const apptOrganizer = Office.context.mailbox.item.organizer;
console.log("Organizer: " + apptOrganizer.displayName + " (" + apptOrganizer.emailAddress + ")");

requiredAttendees

提供对事件的必需与会者的访问权限。 对象的类型和访问级别取决于当前项的模式。

属性 requiredAttendees 返回一个数组,其中包含参加会议的每个所需与会者的 EmailAddressDetails 对象。 返回的最大与会者数因 Outlook 客户端而异。

  • Windows:500 名与会者

  • Android、经典 Mac UI、iOS:100 名与会者

  • 新 Mac UI、Web 浏览器:无限制

requiredAttendees: EmailAddressDetails[];

属性值

注解

最低权限级别读取项

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

示例

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

const apptRequiredAttendees = Office.context.mailbox.item.requiredAttendees;
console.log("Required attendees:");
for (let i = 0; i < apptRequiredAttendees.length; i++) {
  console.log(
    apptRequiredAttendees[i].displayName +
      " (" +
      apptRequiredAttendees[i].emailAddress +
      ") - response: " +
      apptRequiredAttendees[i].appointmentResponse
  );
}

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}`);

方法详细信息

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>.");

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

示例

// 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 an inline image and an item attachment.<br><img src='cid:dog.jpg'>",
  attachments: [
    { type: "file", url: "https://i.imgur.com/9S36xvA.jpg", name: "dog.jpg", inLine: true },
    { type: "item", itemId: Office.context.mailbox.item.itemId, name: "test_email.msg" }
  ],
  callback: (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
      console.error(`Action failed with message ${result.error.message}`);
      return;
    }

    console.log("Created reply with attachments.");
  }
});

getEntities()

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

getEntities(): 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 String 受限

返回

如果在 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 规则元素的名称。

返回

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

注解

[ API set: Mailbox 1.1 ]

最低权限级别读取项

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

重要说明

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

  • 此方法与 Outlook 加载项激活规则功能一起使用,Microsoft 365 的统一清单不支持此功能。

  • 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/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"));

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"));

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 模式:约会与会者

示例

// 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((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`loadCustomPropertiesAsync failed with message ${result.error.message}`);
    return;
  }

  customProps = result.value;
  console.log("Loaded the CustomProperties object.");
});