Abrufen, Festlegen oder Hinzufügen von Empfängern beim Erstellen eines Termins oder einer Nachricht in OutlookGet, set, or add recipients when composing an appointment or message in Outlook

Die JavaScript-API für Office stellt asynchrone Methoden bereit (Recipients.getAsync, Recipients.setAsync oder Recipients.addAysnc) um Empfänger in einem Formular zum Verfassen für einen Termin oder eine Nachricht abzurufen, festzulegen oder hinzuzufügen. Diese asynchronen Methoden sind ausschließlich für Verfassen-Add-Ins verfügbar. Um diese Methoden verwenden zu können, müssen Sie sicherstellen, dass Sie das Add-In-Manifest richtig eingerichtet haben, sodass Outlook das Add-In in Formularen zum Verfassen aktiviert, wie in Erstellen von Outlook-Add-Ins für Formulare zum Verfassen beschrieben.The JavaScript API for Office provides asynchronous methods (Recipients.getAsync, Recipients.setAsync, or Recipients.addAysnc) to respectively get, set, or add recipients in a compose form of an appointment or message. These asynchronous methods are available to only compose add-ins. To use these methods, make sure you have set up the add-in manifest appropriately for Outlook to activate the add-in in compose forms, as described in Create Outlook add-ins for compose forms.

Einige der Eigenschaften, die Empfänger in einem Termin oder einer Nachricht darstellen, sind für den Lesezugriff in einem Formular zum Verfassen und in einem Formular zum Lesen verfügbar. Zu diesen Eigenschaften gehören optionalAttendees und requiredAttendees für Termine sowie cc und to für Nachrichten.Some of the properties that represent recipients in an appointment or message are available for read access in a compose form and in a read form. These properties include optionalAttendees and requiredAttendees for appointments, and cc, and to for messages.

In einem Formular zum Lesen können Sie direkt über das übergeordnete Objekt auf die Eigenschaft zugreifen. Beispiel:In a read form, you can access the property directly from the parent object, such as:

item.cc

Da in einem Formular zum Verfassen jedoch sowohl der Benutzer als auch Ihr Add-In gleichzeitig einen Empfänger einfügen oder ändern können, müssen Sie hier die asynchrone Methode getAsync verwenden, um diese Eigenschaften abzurufen, wie im folgenden Beispiel:But in a compose form, because both the user and your add-in can be inserting or changing a recipient at the same time, you must use the asynchronous method getAsync to get these properties, as in the following example:

item.cc.getAsync

Diese Eigenschaften sind nur für den Schreibzugriff in Formularen zum Verfassen und zum Lesen verfügbar.These properties are available for write access in only compose forms and not read forms.

Wie die meisten asynchronen Methoden in der JavaScript-API für Office verwenden getAsync, setAsync und addAsync optionale Eingabeparameter. Weitere Informationen zur Festlegung dieser optionalen Eingabeparameter finden Sie im Abschnitt Übergeben optionaler Parameter an asynchrone Methoden im Artikel Asynchrone Programmierung in Office-Add-Ins.As with most asynchronous methods in the JavaScript API for Office, getAsync, setAsync, and addAsync take optional input parameters. For more information about specifying these optional input parameters, see passing optional parameters to asynchronous methods in Asynchronous programming in Office Add-ins.

Abrufen von EmpfängernGet recipients

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. Das Codebeispiel setzt eine Regel im Add-in-Manifest voraus, die das Add-In in einem Formular zum Verfassen für einen Termin oder eine Nachricht aktiviert:This section shows a code sample that gets the recipients of the appointment or message that is being composed, and displays the email addresses of the recipients. The code sample assumes a rule in the add-in manifest that activates the add-in in a compose form for an appointment or message, as shown below.

<Rule xsi:type="RuleCollection" Mode="Or">
  <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit"/>
  <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
</Rule>

Weil sich die Eigenschaften, die die Empfänger eines Termins darstellen (optionalAttendees und requiredAttendees) von den Eigenschaften einer Nachricht (bcc, cc und to) unterscheiden, sollten Sie in der JavaScript-API für Office zunächst mithilfe der Eigenschaft item.itemType festlegen, ob es sich bei dem Element, das gerade verfasst wird, um einen Termin oder eine Nachricht handelt. Im Verfassenmodus sind alle diese Eigenschaften von Terminen und Nachrichten Objekte des Typs Recipients, sodass Sie zum Abrufen der zugehörigen Empfänger die asynchrone Methode Recipients.getAsync verwenden können.In the JavaScript API for Office, because the properties that represent the recipients of an appointment ( optionalAttendees and requiredAttendees) are different from those of a message (bcc, cc, and to), you should first use the item.itemType property to identify whether the item being composed is an appointment or message. In compose mode, all these properties of appointments and messages are Recipients objects, so you can then apply the asynchronous method, Recipients.getAsync, to get the corresponding recipients.

Um getAsync verwenden zu können, müssen Sie eine Rückrufmethode bereitstellen, die auf den Status, die Ergebnisse und etwaige Fehler prüft, die vom asynchronen Aufruf getAsync zurückgegeben werden. Mithilfe des optionalen Parameters asyncContext können Sie beliebige Argumente an die Rückrufmethode übergeben. Die Rückrufmethode gibt einen Ausgabeparameter des Typs asyncResult zurück. Die Eigenschaften status und error des Parameterobjekts AsyncResult geben Aufschluss über den Status des asynchronen Aufrufs sowie etwaige Fehlermeldungen. Die Eigenschaft value enthält die tatsächlichen Empfänger. Die Empfänger werden als ein Array von Objekten des Typs EmailAddressDetails dargestellt.To use getAsync, provide a callback method to check for the status, results, and any error returned by the asynchronous getAsync call. You can provide any arguments to the callback method using the optional asyncContext parameter. The callback method returns an asyncResult output parameter. You can use the status and error properties of the AsyncResult parameter object to check for status and any error messages of the asynchronous call, and the value property to get the actual recipients. Recipients are represented as an array of EmailAddressDetails objects.

Beachten Sie: Die Methode getAsync ist asynchron. Wenn Folgeaktionen von einem erfolgreichen Abruf der Empfänger abhängen, sollten Sie Ihren Code so organisieren, dass solche Aktionen nur in der zugehörigen Rückrufmethode gestartet werden, nachdem der asynchrone Aufruf erfolgreich abgeschlossen wurde.Note that because the getAsync method is asynchronous, if there are subsequent actions that depend on successfully getting the recipients, you should organize your code to start such actions only in the corresponding callback method when the asynchronous call has successfully completed.

var item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get all the recipients of the composed item.
        getAllRecipients();
    });
}

// Get the email addresses of all the recipients of the composed item.
function getAllRecipients() {
    // Local objects to point to recipients of either
    // the appointment or message that is being composed.
    // bccRecipients applies to only messages, not appointments.
    var toRecipients, ccRecipients, bccRecipients;
    // Verify if the composed 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;
    }

    // Use asynchronous method getAsync to get each type of recipients
    // of the composed item. Each time, this example passes an anonymous 
    // callback function that doesn't take any parameters.
    toRecipients.getAsync(function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed){
            write(asyncResult.error.message);
        }
        else {
            // Async call to get to-recipients of the item completed.
            // Display the email addresses of the to-recipients. 
            write ('To-recipients of the item:');
            displayAddresses(asyncResult);
        }    
    }); // End getAsync for to-recipients.

    // Get any cc-recipients.
    ccRecipients.getAsync(function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed){
            write(asyncResult.error.message);
        }
        else {
            // Async call to get cc-recipients of the item completed.
            // Display the email addresses of the cc-recipients.
            write ('Cc-recipients of the item:');
            displayAddresses(asyncResult);
        }
    }); // End getAsync for cc-recipients.

    // If the item has the bcc field, i.e., item is message,
    // get any bcc-recipients.
    if (bccRecipients) {
        bccRecipients.getAsync(function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed){
            write(asyncResult.error.message);
        }
        else {
            // Async call to get bcc-recipients of the item completed.
            // Display the email addresses of the bcc-recipients.
            write ('Bcc-recipients of the item:');
            displayAddresses(asyncResult);
        }

        }); // End getAsync for bcc-recipients.
     }
}

// Recipients are in an array of EmailAddressDetails
// objects passed in asyncResult.value.
function displayAddresses (asyncResult) {
    for (var i=0; i<asyncResult.value.length; i++)
        write (asyncResult.value[i].emailAddress);
}

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

Festlegen von EmpfängernSet recipients

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 vorhandenen Empfänger überschrieben. Ähnlich wie im vorherigen Beispiel, in dem Empfänger in einem Formular zum Verfassen abgerufen werden, setzt dieses Beispiel voraus, dass das Add-In in Formularen zum Verfassen für Termine oder Nachrichten aktiviert wird. Dieses Beispiel überprüft zunächst, ob das Element, das gerade verfasst wird, ein Termin oder eine Nachricht ist, damit die asynchrone Methode Recipients.setAsync auf die richtigen Eigenschaften angewendet wird, die die Empfänger des Termins oder der Nachricht darstellen.This section shows a code sample that sets the recipients of the appointment or message that is being composed by the user. Setting recipients overwrites any existing recipients. Similar to the previous example that gets recipients in a compose form, this example assumes that the add-in is activated in compose forms for appointments and messages. This example first verifies if the composed item is an appointment or message, so to apply the asynchronous method, Recipients.setAsync, on the appropriate properties that represent recipients of the appointment or message.

Geben Sie beim Aufrufen von setAsync ein Array als Eingabeargument für den Parameter recipients an, und zwar in einem der folgenden Formate:When calling setAsync, provide an array as input argument for the recipients parameter, in one of the following formats:

  • Ein Array von Zeichenfolgen, die SMTP-Adressen sind.An array of strings that are SMTP addresses.

  • Ein Array von Wörterbüchern, die jeweils einen Anzeigenamen und eine E-Mail-Adresse enthalten, wie im folgenden Beispiel dargestellt.An array of dictionaries, each containing a display name and email address, as shown in the following code sample.

  • Als Array von Objekten des Typs EmailAddressDetails, ähnlich dem von der Methode getAsync zurückgegebenen ArrayAn array of EmailAddressDetails objects, similar to the one returned by the getAsync method.

Optional können Sie eine Rückrufmethode als Eingabeargument an die Methode setAsync übergeben, um sicherzustellen, dass jedweder Code, der von der erfolgreichen Festlegung der Empfänger abhängt, nur dann ausgeführt wird, wenn dies auch der Fall ist. Außerdem können Sie im optionalen Parameter asyncContext beliebige Argumente an die Rückrufmethode übergeben. Wenn Sie eine Rückrufmethode verwenden, können Sie auf einen Ausgabeparameter asyncResult zugreifen und die Eigenschaften status und error des Parameterobjekts AsyncResult verwenden, um den Status des asynchronen Aufrufs zu überprüfen und etwaige Fehlermeldungen abzurufen.You can optionally provide a callback method as an input argument to the setAsync method, to make sure any code that depends on successfully setting the recipients would execute only when that happens. You can also provide any arguments for the callback method using the optional asyncContext parameter. If you use a callback method, you can access an asyncResult output parameter, and use the status and error properties of the AsyncResult parameter object to check for status and any error messages of the asynchronous call.

var item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Set recipients of the composed item.
        setRecipients();
    });
}

// Set the display name and email addresses of the recipients of 
// the composed item.
function setRecipients() {
    // Local objects to point to recipients of either
    // the appointment or message that is being composed.
    // bccRecipients applies to only messages, not appointments.
    var toRecipients, ccRecipients, bccRecipients;

    // Verify if the composed 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;
    }

    // Use asynchronous method setAsync to set each type of recipients
    // of the composed item. Each time, this example passes a set of
    // names and email addresses to set, and an anonymous 
    // callback function that doesn't take any parameters. 
    toRecipients.setAsync(
        [{
            "displayName":"Graham Durkin", 
            "emailAddress":"graham@contoso.com"
         },
         {
            "displayName" : "Donnie Weinberg",
            "emailAddress" : "donnie@contoso.com"
         }],
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Async call to set to-recipients of the item completed.

            }    
    }); // End to setAsync.


    // Set any cc-recipients.
    ccRecipients.setAsync(
        [{
             "displayName":"Perry Horning", 
             "emailAddress":"perry@contoso.com"
         },
         {
             "displayName" : "Guy Montenegro",
             "emailAddress" : "guy@contoso.com"
         }],
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Async call to set cc-recipients of the item completed.
            }
    }); // End cc setAsync.


    // If the item has the bcc field, i.e., item is message,
    // set bcc-recipients.
    if (bccRecipients) {
        bccRecipients.setAsync(
            [{
                 "displayName":"Lewis Cate", 
                 "emailAddress":"lewis@contoso.com"
             },
             {
                 "displayName" : "Francisco Stitt",
                 "emailAddress" : "francisco@contoso.com"
             }],
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    write(asyncResult.error.message);
                }
                else {
                    // Async call to set bcc-recipients of the item completed.
                    // Do whatever appropriate for your scenario.
                }
        }); // End bcc setAsync.
    }
}

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

Hinzufügen von EmpfängernAdd recipients

Wenn Sie bereits vorhandene Empfänger in einem Termin oder einer Nachricht nicht überschreiben möchten, können Sie anstelle von Recipients.setAsync die asynchrone Methode Recipients.addAsync verwenden, um Empfänger anzufügen. addAsync funktioniert insofern ähnlich wie setAsync, als dass sie ein Eingabeargument recipients benötigt. Optional können Sie eine Rückrufmethode definieren und Argumente für den Rückruf im Parameter „asyncContext“ definieren. Anschließend können Sie den Status, das Ergebnis und etwaige Fehler des asynchronen Aufrufs addAsync im Ausgabeparameter asyncResult der Rückrufmethode überprüfen. Im folgenden Beispiel wird überprüft, ob das Element, das gerade verfasst wird, ein Termin ist. Anschließend werden dem Termin zwei erforderliche Teilnehmer angefügt.If you do not want to overwrite any existing recipients in an appointment or message, instead of using Recipients.setAsync, you can use the Recipients.addAsync asynchronous method to append recipients. addAsync works similarly as setAsync in that it requires a recipients input argument. You can optionally provide a callback method, and any arguments for the callback using the asyncContext parameter. You can then check the status, result, and any error of the asynchronous addAsync call by using the asyncResult output parameter of the callback method. The following example checks if the item being composed is an appointment, and appends two required attendees to the appointment.

// Add specified recipients as required attendees of
// the composed 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"
          }],
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Async call to add attendees completed.
                // Do whatever appropriate for your scenario.
            }
        }); // End addAsync.
    }
}

Siehe auchSee also