Share via

Abrufen, Festlegen oder Hinzufügen von Empfängern beim Erstellen eines Termins oder einer Nachricht in Outlook

  • Artikel

Die Office JavaScript-API stellt asynchrone Methoden (Recipients.getAsync, Recipients.setAsync oder Recipients.addAsync) bereit, um Empfänger zu einem Verfassenformular eines Termins oder einer Nachricht abzurufen, festzulegen oder hinzuzufügen. Diese asynchronen Methoden sind nur zum Verfassen von Add-Ins verfügbar. Um diese Methoden zu verwenden, stellen Sie sicher, dass Sie das Add-In-Manifest entsprechend für Outlook eingerichtet haben, um das Add-In in Verfassenformularen zu aktivieren, wie unter Erstellen von Outlook-Add-Ins für Verfassenformulare beschrieben.

Einige der Eigenschaften, die Empfänger in einem Termin oder einer Nachricht darstellen, sind für den Lesezugriff in einem Verfassenformular und in einem Leseformular verfügbar. Zu diesen Eigenschaften gehören optionalAttendees und requiredAttendees für Termine sowie cc und to für Nachrichten.

In einem Formular zum Lesen können Sie direkt über das übergeordnete Objekt auf die Eigenschaft zugreifen. Beispiel:

Office.context.mailbox.item.cc;

Da der Benutzer und ihr Add-In jedoch gleichzeitig einen Empfänger einfügen oder ändern können, müssen Sie die asynchrone Methode getAsync verwenden, um diese Eigenschaften abzurufen, wie im folgenden Beispiel gezeigt.

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

Diese Eigenschaften sind nur für den Schreibzugriff in Formularen zum Verfassen und nicht für Leseformulare verfügbar.

Wie bei den meisten asynchronen Methoden in der JavaScript-API für Office verwenden , getAsyncsetAsyncund addAsync optionale Eingabeparameter. Weitere Informationen zum Angeben dieser optionalen Eingabeparameter finden Sie unter "Übergeben optionaler Parameter an asynchrone Methoden" unter Asynchrone Programmierung in Office-Add-Ins.

Abrufen von Empfängern

In diesem Abschnitt wird ein Codebeispiel beschrieben, über das die Empfänger eines Termins oder einer Nachricht, der/die verfasst wird, abgerufen und die E-Mail-Adressen der Empfänger angezeigt werden.

Da sich in der Office JavaScript-API die Eigenschaften, die die Empfänger eines Termins (optionalAttendees und requiredAttendees) darstellen, von denen einer Nachricht (bcc, und to) unterscheiden, ccsollten Sie zuerst die item.itemType-Eigenschaft verwenden, um zu ermitteln, ob es sich bei dem zusammengestellten Element um einen Termin oder eine Nachricht handelt. Im Verfassenmodus sind alle diese Eigenschaften von Terminen und Nachrichten Recipients-Objekte , sodass Sie dann die asynchrone Methode aufrufen können, Recipients.getAsyncum die entsprechenden Empfänger abzurufen.

Um zu verwendengetAsync, stellen Sie eine Rückruffunktion bereit, um die status, Ergebnisse und alle fehler, die vom asynchronen getAsync Aufruf zurückgegeben werden, zu überprüfen. Die Rückruffunktion gibt einen asyncResult-Ausgabeparameter zurück. Verwenden Sie die status Eigenschaften und error , um nach dem status und allen Fehlermeldungen des asynchronen Aufrufs zu suchen, und deren value Eigenschaft, um die tatsächlichen Empfänger abzurufen. Empfänger werden als ein Array von EmailAddressDetails-Objekten dargestellt. Sie können auch zusätzliche Informationen für die Rückruffunktion bereitstellen, indem Sie den optionalen asyncContext Parameter im getAsync Aufruf verwenden.

Beachten Sie, dass Sie ihren Code so organisieren sollten, dass solche Aktionen nur in der entsprechenden Rückruffunktion gestartet werden, wenn es nachfolgende Aktionen gibt, die vom erfolgreichen Abrufen der Empfänger abhängen, da getAsync die Methode asynchron ist.

Wichtig

Die getAsync -Methode gibt nur Empfänger zurück, die vom Outlook-Client aufgelöst wurden. Ein aufgelöster Empfänger weist die folgenden Merkmale auf.

  • Wenn der Empfänger über einen gespeicherten Eintrag im Adressbuch des Absenders verfügt, löst Outlook die E-Mail-Adresse in den gespeicherten Anzeigenamen des Empfängers auf.
  • Vor dem Namen oder der E-Mail-Adresse des Empfängers wird ein Symbol für eine Teams-Besprechung status angezeigt.
  • Hinter dem Namen oder der E-Mail-Adresse des Empfängers wird ein Semikolon angezeigt.
  • Der Name oder die E-Mail-Adresse des Empfängers wird unterstrichen oder in ein Feld eingeschlossen.

Um eine E-Mail-Adresse aufzulösen, nachdem sie einem E-Mail-Element hinzugefügt wurde, muss der Absender die TAB-TASTE verwenden oder einen vorgeschlagenen Kontakt oder eine E-Mail-Adresse aus der Liste der automatischen Vervollständigung auswählen.

Wenn ein Benutzer in Outlook im Web und unter Windows (klassisch und neu (Vorschau)) eine neue Nachricht erstellt, indem er den E-Mail-Adresslink eines Kontakts aus einem Kontakt oder Profil Karte auswählt, muss er zuerst die E-Mail-Adresse auflösen, damit sie in die Ergebnisse des getAsync Anrufs aufgenommen werden kann.

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

Festlegen von Empfängern

In diesem Abschnitt wird ein Codebeispiel beschrieben, das die Empfänger eines Termins oder einer Nachricht festlegt, der/die gerade vom Benutzer verfasst wird. Durch das Festlegen von Empfängern werden alle bereits bestehenden Empfänger überschrieben. In diesem Beispiel wird zunächst überprüft, ob es sich bei dem E-Mail-Element um einen Termin oder eine Nachricht handelt, sodass es die asynchrone Methode ( Recipients.setAsync) für die entsprechenden Eigenschaften aufrufen kann, die Empfänger des Termins oder der Nachricht darstellen.

Geben Sie beim Aufrufen setAsyncvon ein Array als Eingabeargument für den recipients Parameter in einem der folgenden Formate an.

  • Ein Array von Zeichenfolgen, die SMTP-Adressen sind.
  • Ein Array von Wörterbüchern, die jeweils einen Anzeigenamen und eine E-Mail-Adresse enthalten, wie im folgenden Beispiel dargestellt.
  • Ein Array von EmailAddressDetails -Objekten, das dem von der getAsync -Methode zurückgegebenen -Objekt ähnelt.

Optional können Sie eine Rückruffunktion als Eingabeargument für die setAsync Methode bereitstellen, um sicherzustellen, dass code, der von einer erfolgreichen Festlegung der Empfänger abhängt, nur in diesem Fall ausgeführt wird. Wenn Sie eine Rückruffunktion implementieren, verwenden Sie die status Eigenschaften und error des asyncResult Ausgabeparameters, um die status und alle Fehlermeldungen des asynchronen Aufrufs zu überprüfen. Verwenden Sie den optionalen asyncContext Parameter im Aufruf, um zusätzliche Informationen für die setAsync Rückruffunktion bereitzustellen.

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

Hinzufügen von Empfängern

Wenn Sie keine vorhandenen Empfänger in einem Termin oder einer Nachricht überschreiben möchten, verwenden Sie Recipients.addAsync anstelle von Recipients.setAsyncdie asynchrone Methode, um Empfänger anzufügen. addAsync funktioniert auf ähnliche Weise, als setAsync dass ein recipients Eingabeargument erforderlich ist. Sie können optional eine Rückruffunktion und alle Argumente für den Rückruf mithilfe des asyncContext -Parameters bereitstellen. Überprüfen Sie dann die status, das Ergebnis und alle Fehler des asynchronen addAsync Aufrufs mithilfe des asyncResult Ausgabeparameters der Rückruffunktion. Im folgenden Beispiel wird überprüft, ob es sich bei dem zu zusammengestellten Element um einen Termin handelt, und dann werden zwei erforderliche Teilnehmer an diesen angefügt.

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

Siehe auch