Office.Recipients interface

表示项目的收件人。仅限撰写模式。

注解

使用方

Office.AppointmentCompose： optionalAttendees， requiredAttendees
Office.LoadedMessageCompose：密件抄送、抄送、收件人
Office.MessageCompose：密件抄送、抄送、收件人

方法

addAsync(recipients, options, callback)	将收件人列表添加到约会或邮件的现有收件人中。
addAsync(recipients, callback)	将收件人列表添加到约会或邮件的现有收件人中。
getAsync(options, callback)	获取约会或邮件的收件人列表。
getAsync(callback)	获取约会或邮件的收件人列表。
setAsync(recipients, options, callback)	设置约会或邮件的收件人列表。 `setAsync` 方法将覆盖当前收件人列表。
setAsync(recipients, callback)	设置约会或邮件的收件人列表。 `setAsync` 方法将覆盖当前收件人列表。

addAsync(recipients, options, callback)

将收件人列表添加到约会或邮件的现有收件人中。

addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

recipients: Array<string | Office.EmailUser | Office.EmailAddressDetails>

要添加到收件人列表中的收件人。收件人数组可以包含 SMTP 电子邮件地址、 EmailUser 对象或 EmailAddressDetails 对象字符串。

options: Office.AsyncContextOptions

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

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

可选。当该方法完成时， callback 将使用类型 Office.AsyncResult为 . 如果添加收件人失败，asyncResult.error 属性将包含一个错误代码。

返回

void

注解

API 集：邮箱 1.1

最低权限级别： 读取/写入项目

适用的 Outlook 模式：Compose

重要说明：

使用此addAsync方法，在 Outlook 网页版、Windows (新) 和经典、Mac (经典 UI) 、Android 和 iOS 中，一次最多可以向邮件项目添加 100 个收件人。但是，请注意以下事项：

在 Windows (邮箱 1.15 及更低版本) 和 Mac 上的经典 Outlook (经典 UI) 中，目标字段中最多可以有 500 个收件人。在 Windows 上的经典 Outlook 中，支持邮箱 1.16 及更高版本的客户端最多可有 1,000 个收件人。 Outlook 网页版和新版 Outlook Windows 版中的目标字段没有收件人限制。如果需要向邮件项目添加 100 个以上的收件人，可以重复呼叫 addAsync ，但请注意该字段的收件人限制。
在 Android 和 iOS 上的 Outlook 中，从版本 4.2530.0 开始支持该 addAsync 方法。在这些移动客户端上，当用户从邮件底部的回复字段回复时，不支持此 addAsync 方法。

如果在 Outlook on Mac 中呼叫 addAsync ，则没有收件人 (新 UI) 。

当前使用该loadItemByIdAsync方法加载的消息不支持此addAsync方法。有关详细信息，请参阅在多封邮件上激活 Outlook 加载项。

所有 Outlook 客户端都使用正则表达式规则解析收件人字段中的电子邮件地址。

在 Outlook 网页版和 Windows 上的新版 Outlook 中，addAsync并将setAsync已解析和未解析的电子邮件地址添加到收件人字段。但是，在解决或成功验证项目之前，未解析的电子邮件地址会阻止发送项目。如果智能警报加载项将未解析的收件人添加到任何收件人字段，则将阻止发送操作并显示错误通知。错误通知标识了添加未解析收件人的加载项，并列出了受影响的电子邮件地址。如果在选择“ 发送”后显示“智能警报”对话框，则在关闭对话框后显示错误通知， (选择“ 仍然发送” 或“ 不发送”，或关闭对话框) 。

错误：

NumberOfRecipientsExceeded ：接收人数量超过 100 个条目。

示例

// The following example creates an array of EmailUser objects
// and adds them to the To recipients of the message.
const newRecipients = [
    {
        "displayName": "Allie Bellew",
        "emailAddress": "allieb@contoso.com"
    },
    {
        "displayName": "Alex Darrow",
        "emailAddress": "alexd@contoso.com"
    }
];

Office.context.mailbox.item.to.addAsync(newRecipients, function(result) {
    if (result.error) {
        console.log(result.error);
    } else {
        console.log("Recipients added");
    }
});

addAsync(recipients, callback)

将收件人列表添加到约会或邮件的现有收件人中。

addAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

recipients: Array<string | Office.EmailUser | Office.EmailAddressDetails>

要添加到收件人列表中的收件人。收件人数组可以包含 SMTP 电子邮件地址、 EmailUser 对象或 EmailAddressDetails 对象字符串。

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

可选。当该方法完成时， callback 将使用类型 Office.AsyncResult为 . 如果添加收件人失败，asyncResult.error 属性将包含一个错误代码。

返回

void

注解

API 集：邮箱 1.1

最低权限级别： 读取/写入项目

适用的 Outlook 模式：Compose

重要说明：

使用此addAsync方法，在 Outlook 网页版、Windows (新) 和经典、Mac (经典 UI) 、Android 和 iOS 中，一次最多可以向邮件项目添加 100 个收件人。但是，请注意以下事项：

在 Windows (邮箱 1.15 及更低版本) 和 Mac 上的经典 Outlook (经典 UI) 中，目标字段中最多可以有 500 个收件人。在 Windows 上的经典 Outlook 中，支持邮箱 1.16 及更高版本的客户端最多可有 1,000 个收件人。 Outlook 网页版和新版 Outlook Windows 版中的目标字段没有收件人限制。如果需要向邮件项目添加 100 个以上的收件人，可以重复呼叫 addAsync ，但请注意该字段的收件人限制。
在 Android 和 iOS 上的 Outlook 中，从版本 4.2530.0 开始支持该 addAsync 方法。在这些移动客户端上，当用户从邮件底部的回复字段回复时，不支持此 addAsync 方法。

如果在 Outlook on Mac 中呼叫 addAsync ，则没有收件人 (新 UI) 。

当前使用该loadItemByIdAsync方法加载的消息不支持此addAsync方法。有关详细信息，请参阅在多封邮件上激活 Outlook 加载项。

所有 Outlook 客户端都使用正则表达式规则解析收件人字段中的电子邮件地址。

在 Outlook 网页版和 Windows 上的新版 Outlook 中，addAsync并将setAsync已解析和未解析的电子邮件地址添加到收件人字段。但是，在解决或成功验证项目之前，未解析的电子邮件地址会阻止发送项目。如果智能警报加载项将未解析的收件人添加到任何收件人字段，则将阻止发送操作并显示错误通知。错误通知标识了添加未解析收件人的加载项，并列出了受影响的电子邮件地址。如果在选择“ 发送”后显示“智能警报”对话框，则在关闭对话框后显示错误通知， (选择“ 仍然发送” 或“ 不发送”，或关闭对话框) 。

错误：

NumberOfRecipientsExceeded ：接收人数量超过 100 个条目。

getAsync(options, callback)

获取约会或邮件的收件人列表。

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

参数

options: Office.AsyncContextOptions

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

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

当该方法完成时，将使用类型Office.AsyncResult为 . 的单个参数调用asyncResult传入参数的callback函数。 asyncResult.value结果的属性是 EmailAddressDetails 对象的数组。

返回

void

注解

API 集：邮箱 1.1

最低权限级别： 读取项目

适用的 Outlook 模式：Compose

重要说明：

此方法返回的最大收件人数因 Outlook 客户端而异。

Windows (经典 - 邮箱 1.15 及更低版本) 、Mac (经典 UI) ：500 个收件人
Web、Windows (新版、经典版 - 邮箱 1.16 及更高版本) ：1,000 个收件人
Android、iOS：100 个收件人
Mac (新的 UI) ：无限制

在 Windows 上的经典 Outlook 中，创建新约会或编辑现有约会时，约会组织者包含在方法返回 getAsync 的对象中。在 Outlook 网页版和新的 Outlook on Windows 中，只有在编辑现有约会时，组织者才会包含在返回的对象中。

该 getAsync 方法仅返回 Outlook 客户端解析的收件人。已解决的收件人具有以下特征。

如果收件人的发件人通讯簿中有一个已保存的条目，则 Outlook 会将该电子邮件地址解析为收件人已保存的显示名称。
Teams 会议状态图标显示在收件人的姓名或电子邮件地址前面。
收件人的姓名或电子邮件地址后面出现一个分号。
收件人的姓名或电子邮件地址带有下划线或包含在框中。

若要在将电子邮件地址添加到邮件项后解析该电子邮件地址，发件人必须使用 Tab 键或从自动完成列表中选择建议的联系人或电子邮件地址。

在 Outlook 网页版和 Windows (新的和经典) 中，如果用户通过从其联系人或配置文件卡激活联系人的电子邮件地址链接来创建新邮件，则加载项的调用将Recipients.getAsync返回关联的 EmailAddressDetails 对象属性中displayName联系人的电子邮件地址，而不是联系人的已保存名称。有关更多详细信息，请参阅相关的 GitHub 问题。

撰写邮件项目时，当切换到与之前选定的发件人帐户位于不同域的发件人帐户时，现有收件人的属性值 recipientType 不会更新，仍将基于之前选定帐户的域。若要在切换帐户后获得正确的收件人类型，必须先删除现有收件人，然后将其添加回邮件项目。

在 Android 和 iOS 上的 Outlook 中，当用户从邮件底部的回复字段回复时，仅支持此 getAsync 方法。

getAsync(callback)

获取约会或邮件的收件人列表。

getAsync(callback: (asyncResult: Office.AsyncResult<EmailAddressDetails[]>) => void): void;

参数

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

当该方法完成时，将使用类型Office.AsyncResult为 . 的单个参数调用asyncResult传入参数的callback函数。 asyncResult.value结果的属性是 EmailAddressDetails 对象的数组。

返回

void

注解

API 集：邮箱 1.1

最低权限级别： 读取项目

适用的 Outlook 模式：Compose

重要说明：

此方法返回的最大收件人数因 Outlook 客户端而异。

Windows (经典 - 邮箱 1.15 及更低版本) 、Mac (经典 UI) ：500 个收件人
Web、Windows (新版、经典版 - 邮箱 1.16 及更高版本) ：1,000 个收件人
Android、iOS：100 个收件人
Mac (新的 UI) ：无限制

该 getAsync 方法仅返回 Outlook 客户端解析的收件人。已解决的收件人具有以下特征。

如果收件人的发件人通讯簿中有一个已保存的条目，则 Outlook 会将该电子邮件地址解析为收件人已保存的显示名称。
Teams 会议状态图标显示在收件人的姓名或电子邮件地址前面。
收件人的姓名或电子邮件地址后面出现一个分号。
收件人的姓名或电子邮件地址带有下划线或包含在框中。

若要在将电子邮件地址添加到邮件项后解析该电子邮件地址，发件人必须使用 Tab 键或从自动完成列表中选择建议的联系人或电子邮件地址。

在 Outlook 网页版和 Windows (新的和经典) 中，如果用户通过从其联系人或配置文件卡激活联系人的电子邮件地址链接来创建新邮件，则加载项的调用将Recipients.getAsync返回关联的 EmailAddressDetails 对象属性中displayName联系人的电子邮件地址，而不是联系人的已保存名称。有关更多详细信息，请参阅相关的 GitHub 问题。

撰写邮件项目时，当切换到与之前选定的发件人帐户位于不同域的发件人帐户时，现有收件人的属性值 recipientType 不会更新，仍将基于之前选定帐户的域。若要在切换帐户后获得正确的收件人类型，必须先删除现有收件人，然后将其添加回邮件项目。

在 Android 和 iOS 上的 Outlook 中，当用户从邮件底部的回复字段回复时，仅支持此 getAsync 方法。

示例

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

Office.context.mailbox.item.bcc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgBcc = asyncResult.value;
    console.log("Message being blind-copied to:");
    for (let i = 0; i < msgBcc.length; i++) {
      console.log(msgBcc[i].displayName + " (" + msgBcc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.cc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgCc = asyncResult.value;
    console.log("Message being copied to:");
    for (let i = 0; i < msgCc.length; i++) {
      console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.optionalAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const apptOptionalAttendees = asyncResult.value;
    for (let i = 0; i < apptOptionalAttendees.length; i++) {
      console.log(
        "Optional attendees: " +
          apptOptionalAttendees[i].displayName +
          " (" +
          apptOptionalAttendees[i].emailAddress +
          ") - response: " +
          apptOptionalAttendees[i].appointmentResponse
      );
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.requiredAttendees.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const apptRequiredAttendees = asyncResult.value;
    for (let i = 0; i < apptRequiredAttendees.length; i++) {
      console.log(
        "Required attendees: " +
          apptRequiredAttendees[i].displayName +
          " (" +
          apptRequiredAttendees[i].emailAddress +
          ") - response: " +
          apptRequiredAttendees[i].appointmentResponse
      );
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.to.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgTo = asyncResult.value;
    console.log("Message being sent to:");
    for (let i = 0; i < msgTo.length; i++) {
      console.log(msgTo[i].displayName + " (" + msgTo[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

setAsync(recipients, options, callback)

设置约会或邮件的收件人列表。

setAsync 方法将覆盖当前收件人列表。

setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

recipients: Array<string | Office.EmailUser | Office.EmailAddressDetails>

要添加到收件人列表中的收件人。收件人数组可以包含 SMTP 电子邮件地址、 EmailUser 对象或 EmailAddressDetails 对象字符串。

options: Office.AsyncContextOptions

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

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

当该方法完成时， callback 将使用类型 Office.AsyncResult为 . 如果设置收件人失败，asyncResult.error 属性将包含一个代码，表示在添加数据时出现的所有错误。

返回

void

注解

API 集：邮箱 1.1

最低权限级别： 读取/写入项目

适用的 Outlook 模式：Compose

重要说明：

使用此setAsync方法，在 Outlook 网页版、Windows (新) 、Mac (经典 UI) 、Android 和 iOS 中，一次最多可以设置 100 个收件人。但是，请注意以下事项：

在 Windows (邮箱 1.15 及更低版本) 和 Mac 上的经典 Outlook (经典 UI) 中，目标字段中最多可以有 500 个收件人。在 Windows 上的经典 Outlook 中，支持邮箱 1.16 及更高版本的客户端最多可有 1,000 个收件人。 Outlook 网页版和新版 Outlook Windows 版中的目标字段没有收件人限制。如果需要向邮件项目添加 100 个以上的收件人，可以重复呼叫 addAsync ，但请注意该字段的收件人限制。
在 Android 和 iOS 上的 Outlook 中，从版本 4.2530.0 开始支持该 setAsync 方法。在这些移动客户端上，当用户从邮件底部的回复字段回复时，不支持此 setAsync 方法。

如果在 Outlook on Mac 中呼叫 setAsync ，则没有收件人 (新 UI) 。

当前使用该loadItemByIdAsync方法加载的消息不支持此setAsync方法。有关详细信息，请参阅在多封邮件上激活 Outlook 加载项。

所有 Outlook 客户端都使用正则表达式规则解析收件人字段中的电子邮件地址。

在 Outlook 网页版和 Windows 上的新版 Outlook 中，addAsync并将setAsync已解析和未解析的电子邮件地址添加到收件人字段。但是，在解决或成功验证项目之前，未解析的电子邮件地址会阻止发送项目。如果智能警报加载项将未解析的收件人添加到任何收件人字段，则将阻止发送操作并显示错误通知。错误通知标识了添加未解析收件人的加载项，并列出了受影响的电子邮件地址。如果在选择“ 发送”后显示“智能警报”对话框，则在关闭对话框后显示错误通知， (选择“ 仍然发送” 或“ 不发送”，或关闭对话框) 。

错误：

NumberOfRecipientsExceeded ：接收人数量超过 100 个条目。

setAsync(recipients, callback)

设置约会或邮件的收件人列表。

setAsync 方法将覆盖当前收件人列表。

setAsync(recipients: Array<string | EmailUser | EmailAddressDetails>, callback: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

recipients: Array<string | Office.EmailUser | Office.EmailAddressDetails>

要添加到收件人列表中的收件人。收件人数组可以包含 SMTP 电子邮件地址、 EmailUser 对象或 EmailAddressDetails 对象字符串。

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

当该方法完成时， callback 将使用类型 Office.AsyncResult为 . 如果设置收件人失败，asyncResult.error 属性将包含一个代码，表示在添加数据时出现的所有错误。

返回

void

注解

API 集：邮箱 1.1

最低权限级别： 读取/写入项目

适用的 Outlook 模式：Compose

重要说明：

使用此setAsync方法，在 Outlook 网页版、Windows (新) 、Mac (经典 UI) 、Android 和 iOS 中，一次最多可以设置 100 个收件人。但是，请注意以下事项：

在 Windows (邮箱 1.15 及更低版本) 和 Mac 上的经典 Outlook (经典 UI) 中，目标字段中最多可以有 500 个收件人。在 Windows 上的经典 Outlook 中，支持邮箱 1.16 及更高版本的客户端最多可有 1,000 个收件人。 Outlook 网页版和新版 Outlook Windows 版中的目标字段没有收件人限制。如果需要向邮件项目添加 100 个以上的收件人，可以重复呼叫 addAsync ，但请注意该字段的收件人限制。
在 Android 和 iOS 上的 Outlook 中，从版本 4.2530.0 开始支持该 setAsync 方法。在这些移动客户端上，当用户从邮件底部的回复字段回复时，不支持此 setAsync 方法。

如果在 Outlook on Mac 中呼叫 setAsync ，则没有收件人 (新 UI) 。

当前使用该loadItemByIdAsync方法加载的消息不支持此setAsync方法。有关详细信息，请参阅在多封邮件上激活 Outlook 加载项。

所有 Outlook 客户端都使用正则表达式规则解析收件人字段中的电子邮件地址。

在 Outlook 网页版和 Windows 上的新版 Outlook 中，addAsync并将setAsync已解析和未解析的电子邮件地址添加到收件人字段。但是，在解决或成功验证项目之前，未解析的电子邮件地址会阻止发送项目。如果智能警报加载项将未解析的收件人添加到任何收件人字段，则将阻止发送操作并显示错误通知。错误通知标识了添加未解析收件人的加载项，并列出了受影响的电子邮件地址。如果在选择“ 发送”后显示“智能警报”对话框，则在关闭对话框后显示错误通知， (选择“ 仍然发送” 或“ 不发送”，或关闭对话框) 。

错误：

NumberOfRecipientsExceeded ：接收人数量超过 100 个条目。

示例

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

const email = (document.getElementById("emailBcc") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.bcc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Bcc field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = (document.getElementById("emailCc") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.cc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Cc field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = (document.getElementById("emailOptional") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.optionalAttendees.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting optional attendees field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = (document.getElementById("emailRequired") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.requiredAttendees.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting required attendees field.");
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = (document.getElementById("emailTo") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.to.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting To field.");
  } else {
    console.error(asyncResult.error);
  }
});

注解

使用方

方法

方法详细信息

addAsync(recipients, options, callback)

参数

返回

注解

示例

addAsync(recipients, callback)

参数

返回

注解

getAsync(options, callback)

参数

返回

注解

getAsync(callback)

参数

返回

注解

示例

setAsync(recipients, options, callback)

参数

返回

注解

setAsync(recipients, callback)

参数

返回

注解

示例

反馈