Office.Recipients interface

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

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

可选。方法完成后，使用类型的Office.AsyncResult单个参数调用在参数中callback传递的函数。如果添加收件人失败，asyncResult.error 属性将包含一个错误代码。

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：Compose

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

在 Outlook 网页版中，在 Windows (新的和经典) ，在 Mac (经典 UI) 上，目标字段中最多可以有 500 个收件人。如果需要向邮件项目添加 100 个以上的收件人，可以重复调用 addAsync ，但请注意字段的收件人限制。
在 Outlook on Android 和 iOS 中，addAsync消息Compose模式不支持方法。仅支持约会组织者模式。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

如果在 Outlook on Mac 中调用 addAsync (新 UI) ，则没有收件人限制。

错误：

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

可选。方法完成后，使用类型的Office.AsyncResult单个参数调用在参数中callback传递的函数。如果添加收件人失败，asyncResult.error 属性将包含一个错误代码。

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：Compose

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

在 Outlook 网页版、Windows 和 Mac (经典 UI) 中，目标字段中最多可以有 500 个收件人。如果需要向邮件项目添加 100 个以上的收件人，可以重复调用 addAsync ，但请注意字段的收件人限制。
在 Outlook on Android 和 iOS 中，addAsync消息Compose模式不支持方法。仅支持约会组织者模式。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

如果在 Outlook on Mac 中调用 addAsync (新 UI) ，则没有收件人限制。

错误：

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

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

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 set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：Compose

重要说明：

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

Windows (新的和经典) 、Web 浏览器、Mac (经典 UI) ：500 个收件人
Android、iOS：100 个收件人
Mac (新 UI) ：无限制

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

如果收件人的通讯簿中具有已保存的条目，Outlook 会将电子邮件地址解析为收件人保存的显示名称。
Teams 会议状态图标显示在收件人的姓名或电子邮件地址之前。
收件人姓名或电子邮件地址后会显示分号。
收件人的姓名或电子邮件地址带有下划线或括在框中。

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

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

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

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

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

参数

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

方法完成后，使用类型的Office.AsyncResult单个参数 asyncResult调用在参数中callback传递的函数。 asyncResult.value结果的属性是 EmailAddressDetails 对象的数组。

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：Compose

重要说明：

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

Windows (新的和经典) 、Web 浏览器、Mac (经典 UI) ：500 个收件人
Android、iOS：100 个收件人
Mac (新 UI) ：无限制

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

如果收件人的通讯簿中具有已保存的条目，Outlook 会将电子邮件地址解析为收件人保存的显示名称。
Teams 会议状态图标显示在收件人的姓名或电子邮件地址之前。
收件人姓名或电子邮件地址后会显示分号。
收件人的姓名或电子邮件地址带有下划线或括在框中。

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

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

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

示例

// 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 方法将覆盖当前收件人列表。

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

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

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：Compose

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

在 Outlook 网页版中，在 Windows (新的和经典) ，在 Mac (经典 UI) 上，目标字段中最多可以有 500 个收件人。如果需要设置超过 100 个收件人，可以重复调用 setAsync ，但请注意字段的收件人限制。
在 Android 版 Outlook 和 iOS 版中，setAsync“邮件Compose”模式不支持该方法。仅支持约会组织者模式。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

如果在 Outlook on Mac 中调用 setAsync (新 UI) ，则没有收件人限制。

错误：

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

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

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

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

返回

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：Compose

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

在 Outlook 网页版中，在 Windows (新的和经典) ，在 Mac (经典 UI) 上，目标字段中最多可以有 500 个收件人。如果需要设置超过 100 个收件人，可以重复调用 setAsync ，但请注意字段的收件人限制。
在 Android 版 Outlook 和 iOS 版中，setAsync“邮件Compose”模式不支持该方法。仅支持约会组织者模式。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

如果在 Outlook on Mac 中调用 setAsync (新 UI) ，则没有收件人限制。

错误：

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

示例

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

Office.context.mailbox.item.cc.setAsync(newRecipients, function(result) {
    if (result.error) {
        console.log(result.error);
    } else {
        console.log("Recipients overwritten");
    }
});

// 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 = $("#emailBcc")
  .val()
  .toString();
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 = $("#emailCc")
  .val()
  .toString();
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 = $("#emailOptional")
  .val()
  .toString();
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 = $("#emailRequired")
  .val()
  .toString();
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 = $("#emailTo")
  .val()
  .toString();
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)

参数

返回

注解

示例

其他资源