在 Outlook 中撰写约会或邮件时获取、设置或添加收件人

项目
02/29/2024

Office JavaScript API 提供异步方法 (Recipients.getAsync、 Recipients.setAsync 或 Recipients.addAsync) 分别获取、设置或添加收件人到约会或邮件的撰写形式。这些异步方法仅可用于撰写加载项。若要使用这些方法，请确保已适当地为 Outlook 设置外接程序清单，以便在撰写窗体中激活加载项，如为撰写窗体创建 Outlook 外接程序中所述。

部分表示约会或邮件中的收件人的属性在撰写窗体和阅读窗体中可以进行阅读访问。这些属性包括约会的 optionalAttendees 和 requiredAttendees，以及邮件的 cc 和 to。

在阅读窗体中，您可以直接从父对象访问属性，例如：

Office.context.mailbox.item.cc;

但在撰写窗体中，由于用户和加载项可以同时插入或更改收件人，因此必须使用异步方法来 getAsync 获取这些属性，如以下示例所示。

Office.context.mailbox.item.cc.getAsync(callback);

这些属性仅可用于撰写窗体中的写入访问，而不适用于读取窗体。

与适用于 Office 的 JavaScript API 中的大多数异步方法一样， getAsyncsetAsync和 addAsync 采用可选的输入参数。有关如何指定这些可选输入参数的详细信息，请参阅 Office 外接程序中的异步编程中的“将可选参数传递给异步方法”。

获取收件人

此部分显示的代码示例用于获取正在撰写的约会或邮件的收件人，并显示收件人的电子邮件地址。

在 Office JavaScript API 中，由于表示约会 (optionalAttendees 和 requiredAttendees) 收件人的属性与邮件 (密件抄送的属性不同， cc并且 to) ，因此应首先使用 item.itemType 属性来标识正在撰写的项目是约会还是邮件。在撰写模式下，约会和邮件的所有这些属性都是 Recipients 对象，因此你可以调用异步方法 Recipients.getAsync，以获取相应的收件人。

若要使用 getAsync，请提供回调函数来检查异步 getAsync 调用返回的状态、结果和任何错误。回调函数返回 asyncResult 输出参数。使用其 status 和 error 属性检查异步调用的状态和任何错误消息，并使用其 value 属性获取实际收件人。收件人以 EmailAddressDetails 对象数组的形式表示。还可以在调用中使用getAsync可选asyncContext参数向回调函数提供其他信息。

请注意，由于 getAsync 该方法是异步的，因此如果后续操作依赖于成功获取收件人，则应将代码组织为仅在异步调用成功完成时在相应的回调函数中启动此类操作。

重要

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

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

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

在 Outlook 网页版和 Windows (新的和经典) 中，如果用户通过从联系人或个人资料卡片中选择联系人的电子邮件地址链接创建新邮件，则必须首先解析电子邮件地址，以便该电子邮件地址可以包含在通话结果 getAsync 中。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getAllRecipients();
    }
});

// Gets the email addresses of all the recipients of the item being composed.
function getAllRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Get the recipients from the To or Required field of the item being composed.
    toRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the To or Required field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Cc or Optional field of the item being composed.
    ccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the Cc or Optional field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Bcc field of the message being composed, if applicable.
    if (bccRecipients.length > 0) {
        bccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients.
        write(`Recipients in the Bcc field: ${displayAddresses(asyncResult.value)}`);
        });
    } else {
        write("Recipients in the Bcc field: None");
    }
}

// Displays the email address of each recipient.
function displayAddresses (recipients) {
    for (let i = 0; i < recipients.length; i++) {
        write(recipients[i].emailAddress);
    }
}

// Writes to a div with id="message" on the page.
function write(message) {
    document.getElementById("message").innerText += message;
}

设置收件人

此部分显示的代码示例会设置用户正在撰写的约会或邮件的收件人。设置收件人将覆盖现有的全部收件人。此示例首先验证邮件项目是约会还是邮件，以便它可以对表示约会或邮件收件人的相应属性调用异步方法 Recipients.setAsync。

调用 setAsync时，请提供数组作为参数的 recipients 输入参数，采用以下格式之一。

为 SMTP 地址的字符串数组。
字典的数组，每个字典都包含显示名称和电子邮件地址，如下面的代码示例中所示。
对象的数组 EmailAddressDetails ，类似于方法返回的对象 getAsync 。

可以选择将回调函数作为输入参数提供给 setAsync 方法，以确保依赖于成功设置收件人的任何代码仅在发生这种情况时才执行。如果实现回调函数，请使用status输出参数的 asyncResult 和 error 属性检查异步调用的状态和任何错误消息。若要向回调函数提供其他信息，请在调用中使用setAsync可选asyncContext参数。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setRecipients();
    }
});

// Sets the recipients of the item being composed.
function setRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Set the recipients in the To or Required field of the item being composed.
    toRecipients.setAsync(
        [{
            "displayName": "Graham Durkin", 
            "emailAddress": "graham@contoso.com"
         },
         {
            "displayName": "Donnie Weinberg",
            "emailAddress": "donnie@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the To or Required field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Cc or Optional field of the item being composed.
    ccRecipients.setAsync(
        [{
            "displayName": "Perry Horning", 
            "emailAddress": "perry@contoso.com"
         },
         {
            "displayName": "Guy Montenegro",
            "emailAddress": "guy@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the Cc or Optional field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Bcc field of the message being composed.
    if (bccRecipients) {
        bccRecipients.setAsync(
            [{
                "displayName": "Lewis Cate", 
                "emailAddress": "lewis@contoso.com"
            },
            {
                "displayName": "Francisco Stitt",
                "emailAddress": "francisco@contoso.com"
            }],
            (asyncResult) => {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    console.log(asyncResult.error.message);
                    return;
                }
    
                console.log("Successfully set the recipients in the Bcc field.");
                // Run additional operations appropriate to your scenario.
        });
    }
}

添加收件人

如果不想覆盖约会或邮件中的任何现有收件人，请使用异步方法来追加收件人，而不是使用 Recipients.setAsyncRecipients.addAsync 。 addAsync 其工作原理 setAsync 与此类似，因为它需要 recipients 输入参数。可以选择使用参数为回调提供回调 asyncContext 函数和任何参数。然后，使用asyncResult回调函数的输出参数检查异步addAsync调用的状态、结果和任何错误。以下示例检查正在撰写的项目是否为约会，然后向其追加两个必需的与会者。

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        addAttendees();
    }
});

// Adds the specified recipients as required attendees of the appointment.
function addAttendees() {
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        item.requiredAttendees.addAsync(
        [{
            "displayName": "Kristie Jensen",
            "emailAddress": "kristie@contoso.com"
         },
         {
            "displayName": "Pansy Valenzuela",
            "emailAddress": "pansy@contoso.com"
          }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully added the required attendees.");
            // Run additional operations appropriate to your scenario.
        });
    }
}

通过

在 Outlook 中撰写约会或邮件时获取、设置或添加收件人

获取收件人

设置收件人

添加收件人

另请参阅

其他资源