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 (Recipients.getAsync, Recipients.setAsync oder Recipients.addAysnc) bereit, um Empfänger in einem Formular zum Verfassen eines Termins oder einer Nachricht abzurufen, festzulegen bzw. hinzuzufügen.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. Diese asynchronen Methoden sind nur in Erstellungs-Add-Ins verfügbar. Vergewissern Sie sich, dass Sie das Add-In-Manifest entsprechend für Outlook eingerichtet haben, damit das Add-In in Erstellformularen aktiviert wird, wie in Erstellen von Outlook-Add-Ins für Formulare zum Verfassen beschrieben.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. Diese Eigenschaften sind u. a. optionalAttendees und requiredAttendees für Termine sowie cc und to für Nachrichten. In Formularen zum Lesen können Sie direkt über das übergeordnete Objekt auf die Eigenschaft zugreifen: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 a read form, you can access the property directly from the parent object, such as:

item.cc

Aber weil in einem Formular zum Verfassen sowohl der Benutzer als auch Ihr Add-In gleichzeitig einen Empfänger einfügen oder ändern können, müssen Sie die asynchrone Methode getAsync verwenden, um diese Eigenschaften zu erhalten: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 für das Angeben dieser optionalen Eingabeparameter finden Sie unter Übergeben optionaler Parameter an asynchrone Methoden in 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.

So werden Empfänger abgerufenTo get 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 die item.itemType-Eigenschaft verwenden, um festzustellen, ob das Element, das gerade verfasst wird, ein Termin oder eine Nachricht ist. Im Verfassenmodus sind diese Eigenschaften von Terminen und Nachrichten Recipients-Objekte, sodass Sie die asynchrone Methode, Recipients.getAsync, anwenden können, um die einhergehenden Empfänger abzurufen.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, um Status, Ergebnisse und Fehler zu prüfen, die vom asynchronen getAsync-Abruf zurückgegeben werden. Mithilfe des optionalen asyncContext-Parameters können Sie jedes beliebige Argument für die Rückrufmethode bereitstellen. Die Rückrufmethode gibt einen asyncResult-Ausgabeparameter zurück. Sie können die status- und error-Eigenschaften des AsyncResult-Parameterobjekts verwenden, um den Status des asynchronen Abrufs sowie auf Fehlernachrichten zu prüfen, die der Abruf möglicherweise ausgegeben hat, und Sie können die value-Eigenschaft verwenden, um die tatsächlichen Empfänger abzurufen. Empfänger werden als ein Array von EmailAddressDetails-Objekten 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, dass aufgrund der Tatsache, dass die getAsync-Methode asynchron ist, Sie Ihren Code bei Folgeaktionen, die von einem erfolgreichen Abruf der Empfänger abhängen, so organisieren sollten, dass solche Aktionen nur in der zugehörigen Rückrufmethode gestartet werden, nachdem der asynchrone Abruf erfolgreich beendet 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; 
}

So werden Empfänger festgelegtTo set 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 bestehenden 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 verifiziert zunächst, ob das Element, das gerade verfasst wird, ein Termin oder eine Nachricht ist, sodass die asynchrone Methode Recipients.setAsync auf die entsprechenden 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.

Stellen Sie beim Abrufen von setAsync ein Array als Eingabeargument für den recipients-Parameter in einem der folgenden Formate bereit: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.

  • Ein Array von EmailAddressDetails-Objekten, ähnlich dem von der getAsync-Methode zurückgegebenen Objekt.An array of EmailAddressDetails objects, similar to the one returned by the getAsync method.

Alternativ können Sie eine Rückrufmethode als Eingabeargument für die setAsync-Methode bereitstellen, um sicherzustellen, dass der Code, der von der erfolgreichen Festlegung der Empfänger abhängt, nur dann ausgeführt wird, wenn dies geschieht. Sie können außerdem jedes beliebige Argument für die Rückrufmethode bereitstellen, indem Sie den optionalen asyncContext-Parameter verwenden. Wenn Sie eine Rückrufmethode verwenden, können Sie auf einen asyncResult-Ausgabeparameter zugreifen und die status- und error-Eigenschaften des AsyncResult-Parameterobjekts verwenden, um den Status des asynchronen Abrufs zu prüfen sowie um zu prüfen, ob der Abruf Fehlermeldungen hervorgebracht hat.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; 
}

So werden Empfänger hinzugefügtTo add recipients

Wenn Sie bereits bestehende 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 hinzuzufügen. addAsync funktioniert insofern ähnlich wie setAsync, als dass es ein recipients-Eingabeargument benötigt. Alternativ können Sie eine Rückrufmethode bereitstellen sowie jedes Argument für die Rückrufmethode, dass den Parameter "asyncContext" verwendet. Anschließend können Sie Status, Ergebnis und Fehlermeldungen des asynchronen addAsync-Abrufs prüfen, indem Sie den asyncResult-Ausgabeparameter der Rückrufmethode verwenden. Im folgenden Beispiel wird geprüft, ob das Element, das gerade verfasst wird, ein Termin ist, dem zwei Teilnehmer hinzugefügt werden.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