Hinzufügen und Entfernen von Anhängen bei einem Element in einem Verfasserformular in OutlookAdd and remove attachments to an item in a compose form in Outlook

Sie können die Methoden addFileAttachmentAsync und addItemAttachmentAsync verwenden, um Dateien und Outlook-Elemente an ein Element anzufügen, das der Benutzer gerade verfasst. Beide sind asynchrone Methoden. Das heißt: Sie können ausgeführt werden, ohne dass zunächst die Aktion abgeschlossen werden müsste. Je nach dem ursprünglichen Speicherort und der ursprünglichen Größe der hinzuzufügenden Anlage kann es eine Weile dauern, bis der asynchrone Aufruf abgeschlossen wird.You can use the addFileAttachmentAsync and addItemAttachmentAsync methods to attach a file and an Outlook item respectively to the item that the user is composing. Both are asynchronous methods, which means execution can go on without waiting for the action to complete. Depending on the original location and size of the attachment being added, the asynchronous call may take a while to complete.

Wenn es Aufgaben gibt, die von der zu erledigenden Aktion abhängen, sollten Sie diese Aufgaben in einer Callback-Methode ausführen. Diese Callback-Methode ist optional und wird aufgerufen, wenn das Hochladen der Anlage abgeschlossen ist. Die Callback-Methode nimmt ein AsyncResult Objekt als Ausgabeparameter, das jeden Status, Fehler und zurückgegebenen Wert aus dem Hinzufügen der Anlage liefert. Wenn der Rückruf zusätzliche Parameter erfordert, können Sie diese im optionalen Parameter options.aysncContext angeben. options.asyncContext kann von jeder Art sein, die Ihre Callback-Methode erwartet.If there are tasks that depend on the action to complete, you should carry out those tasks in a callback method. This callback method is optional and is invoked when the uploading of the attachment is complete. The callback method takes an AsyncResult object as an output parameter that provides any status, error, and returned value from adding the attachment. If the callback requires any extra parameters, you can specify them in the optional options.aysncContext parameter. options.asyncContext can be of any type that your callback method expects.

Beispiel: Sie legen options.asyncContext als JSON-Objekt fest, das mindestens ein Schlüsselwertpaar enthält. Weitere Beispiele zur Übergabe von optionalen Parametern an asynchrone Methoden finden Sie auf der Office-Add-Ins Plattform in Asynchrone Programmierung in Office-Add-Ins. Im folgenden Beispiel sehen Sie, wie Sie den asyncContext -Parameter zum Übergeben von zwei Argumenten an eine Rückrufmethode verwenden:For example, you can define options.asyncContext as a JSON object that contains one or more key-value pairs. You can find more examples about passing optional parameters to asynchronous methods in the Office Add-ins platform in Asynchronous programming in Office Add-ins. The following example shows how to use the asyncContext parameter to pass 2 arguments to a callback method:

var options = { asyncContext: { var1: 1, var2: 2} };

Office.context.mailbox.item.addFileAttachmentAsync('https://contoso.com/rtm/icon.png', 'icon.png', options, callback);

Sie können den Erfolg oder Fehler eines asynchronen Methodenaufrufs in der Callback-Methode mit den Eigenschaften status und error des Objekts AsyncResult überprüfen. Wenn der Anhang erfolgreich abgeschlossen wurde, können Sie die Eigenschaft AsyncResult.value verwenden, um die Anlagen-ID zu erhalten. Die Anlagen-ID ist eine ganze Zahl, mit der Sie die Anlage anschließend entfernen können.You can check for success or error of an asynchronous method call in the callback method using the status and error properties of the AsyncResult object. If the attaching completes successfully, you can use the AsyncResult.value property to get the attachment ID. The attachment ID is an integer which you can subsequently use to remove the attachment.

Hinweis

Als Best Practice sollten Sie die Anlagen-ID verwenden, um eine Anlage nur dann zu entfernen, wenn das gleiche Add-In diese Anlage in derselben Sitzung hinzugefügt hat. In Outlook im Web und OWA for Devices ist die Anlagen-ID nur innerhalb derselben Sitzung gültig. Eine Sitzung ist beendet, wenn der Benutzer das Add-In schließt, oder wenn der Benutzer anfängt, in einer Inline-Form zu komponieren und anschließend die Inline-Form ausklappt, um in einem separaten Fenster fortzufahren.As a best practice, you should use the attachment ID to remove an attachment only if the same add-in has added that attachment in the same session. In Outlook on the web and OWA for Devices, the attachment ID is valid only within the same session. A session is over when the user closes the add-in, or if the user starts composing in an inline form and subsequently pops out the inline form to continue in a separate window.

Datei anhängenAttaching a file

Sie können einer Nachricht oder einem Termin in einer Entwurfsvorlage eine Anlage mit der addFileAttachmentAsync Methode hinzufügen und den Datei-URI dabei angeben. Ist die Datei geschützt, können Sie ein entsprechendes Identitäts- oder Authentifizierungstoken als Parameter der URI-Abfragezeichenfolge mit einschließen. Exchange ruft den URI auf, um die Anlage abzurufen, und der Webdienst, der die Datei schützt, verwendet das Token als Authentifizierung.You can attach a file to a message or appointment in a compose form by using the addFileAttachmentAsync method and specifying the URI of the file. If the file is protected, you can include an appropriate identity or authentication token as a URI query string parameter. Exchange will make a call to the URI to get the attachment, and the web service which protects the file will need to use the token as a means of authentication.

Das folgende JavaScript-Beispiel ist ein Verfasser-Zusatz, der eine Datei, picture.png, von einem Webserver an die zu erstellende Nachricht oder den Termin anhängt. Die Callback-Methode nimmt asyncResult als Parameter, prüft den Ergebnisstatus und erhält die Anlagen-ID, wenn die Methode erfolgreich ist.The following JavaScript example is a compose add-in that attaches a file, picture.png, from a web server to the message or appointment being composed. The callback method takes asyncResult as a parameter, checks for the result status, and gets the attachment ID if the method succeeds.

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Add the specified file attachment to the item
        // being composed.
        // When the attachment finishes uploading, the
        // callback method is invoked and gets the attachment ID. 
        // You can optionally pass any object that you would  
        // access in the callback method as an argument to  
        // the asyncContext parameter.
        Office.context.mailbox.item.addFileAttachmentAsync(
            `https://webserver/picture.png`,
            'picture.png',
            { asyncContext: null },
            function (asyncResult) {
                if (asyncResult.status == Office.AsyncResultStatus.Failed){
                    write(asyncResult.error.message);
                }
                else {
                    // Get the ID of the attached file.
                    var attachmentID = asyncResult.value;
                    write('ID of added attachment: ' + attachmentID);
                }
            });
    });
}

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

Outlook-Element anhängenAttaching an Outlook item

Sie können ein Outlook-Element (wie E-Mail, Kalender oder Kontakte) an eine Nachricht oder einen Termin in einer Entwurfsvorlage anhängen, indem Sie die EWS-ID (Exchange Web Services) des Elements angeben und die addItemAttachmentAsync-Methode verwenden. Die EWS-ID eines E-Mail-, Kalender-, Kontakt- oder Aufgabenelements können Sie aus dem Benutzerpostfach mit der mailbox.makeEwsRequestAsync-Methode abrufen, indem Sie auf den EWS-Vorgang FindItem zugreifen. Die item.itemId-Eigenschaft liefert Ihnen auch die EWS-ID eines vorhandenen Elements in einem Leseformular.You can attach an Outlook item (for example, email, calendar, or contact item) to a message or appointment in a compose form by specifying the Exchange Web Services (EWS) ID of the item and using the addItemAttachmentAsync method. You can get the EWS ID of an email, calendar, contact or task item in the user's mailbox by using the mailbox.makeEwsRequestAsync method and accessing the EWS operation FindItem. The item.itemId property also provides the EWS ID of an existing item in a read form.

Die folgende JavaScript-Funktion addItemAttachment erweitert das erste Beispiel oben und fügt ein Element als Anhang zu der E-Mail oder dem Termin hinzu, der gerade erstellt wird. Die Funktion nimmt als Argument die EWS-ID des Elements, das angehängt werden soll. Wenn die Anlage erfolgreich ist, erhält sie die Anlagen-ID zur weiteren Verarbeitung, einschließlich des Entfernens dieser Anlage in derselben Sitzung.The following JavaScript function, addItemAttachment, extends the first example above, and adds an item as an attachment to the email or appointment that is being composed. The function takes as an argument the EWS ID of the item that is to be attached. If the attaching succeeds, it gets the attachment ID for further processing, including removing that attachment in the same session.

// Adds the specified item as an attachment to the composed item.
// ID is the EWS ID of the item to be attached.
function addItemAttachment(itemId) {
    // When the attachment finishes uploading, the
    // callback method is invoked. Here, the callback
    // method uses only asyncResult as a parameter,
    // and if the attaching succeeds, gets the attachment ID.
    // You can optionally pass any other object you wish to 
    // access in the callback method as an argument to 
    // the asyncContext parameter.
    Office.context.mailbox.item.addItemAttachmentAsync(
        itemId,
        'Welcome email',
        { asyncContext: null },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                var attachmentID = asyncResult.value;
                write('ID of added attachment: ' + attachmentID);
            }
        });
}

Hinweis

Sie können ein Verfasser-Add-In verwenden, um eine Instanz eines wiederkehrenden Termins in Outlook im Web oder OWA for Devices anzuhängen. In einem unterstützenden Outlook Rich Client würde der Versuch, eine Instanz anzuhängen, jedoch dazu führen, dass die wiederkehrende Serie (der Mastertermin) angehängt wird.You can use a compose add-in to attach an instance of a recurring appointment in Outlook on the web or OWA for Devices. However, in a supporting Outlook rich client, attempting to attach an instance would result in attaching the recurring series (the master appointment).

Eine Anlage entfernenRemoving an attachment

Sie können eine Datei- oder Element-Anlage aus einer Nachricht oder einem Terminobjekt in einer verfassten Form entfernen, indem Sie die entsprechende Anlagen-ID angeben und die Methode removeAttachmentAsync verwenden. Sie sollten nur Anhänge entfernen, die das gleiche Add-In in derselben Sitzung hinzugefügt hat. Sie sollten sicherstellen, dass die Anlagen-ID einer gültigen Anlage entspricht, sonst gibt die Methode einen Fehler zurück. Ähnlich wie bei den Methoden addFileAttachmentAsync und addItemAttachmentAsync ist removeAttachmentAsync ein asynchrones Verfahren. Sie sollten eine Callback-Methode bereitstellen, um den Status und eventuelle Fehler zu überprüfen, indem Sie das Ausgabe-Parameter-Objekt AsyncResult verwenden. Sie können auch alle weiteren Parameter an die Callback-Methode übergeben, indem Sie den optionalen Parameter asyncContext verwenden.You can remove a file or item attachment from a message or appointment item in a compose form by specifying the corresponding attachment ID and using the removeAttachmentAsync method. You should remove only attachments that the same add-in has added in the same session. You should make sure the attachment ID corresponds to a valid attachment, or the method will return an error. Similar to the addFileAttachmentAsync and addItemAttachmentAsync methods, removeAttachmentAsync is an asynchronous method. You should provide a callback method to check for the status and any error by using the AsyncResult output parameter object. You can also pass any additional parameters to the callback method by using the optional asyncContext parameter.

Die folgende JavaScript-Funktion, removeAttachment, erweitert das obige Beispiel und entfernt die angegebene Anlage aus der E-Mail oder dem Termin, die/der gerade erstellt wird. Diese Funktion hat die ID der zu entfernenden Anlage als Argument. Sie rufen die Anlage-ID nach einem erfolgreichen addFileAttachmentAsync oder addItemAttachmentAsync-Methodenaufruf ab und speichern sie für einen späteren removeAttachmentAsync Methodenaufruf.The following JavaScript function, removeAttachment, continues to extend the examples above, and removes the specified attachment from the email or appointment that is being composed. The function takes as an argument the ID of the attachment to be removed. You can obtain the ID of an attachment after a successful addFileAttachmentAsync or addItemAttachmentAsync method call, and store it for a subsequent removeAttachmentAsync method call.

// Removes the specified attachment from the composed item.
// ID is the Exchange identifier of the attachment to be 
// removed. 
function removeAttachment(attachmentId) {
    // When the attachment is removed, the
    // callback method is invoked. Here, the callback
    // method uses an asyncResult parameter and gets
    // the ID of the removed attachment if the removal
    // succeeds.
    // You can optionally pass any object you wish to 
    // access in the callback method as an argument to 
    // the asyncContext parameter.
    Office.context.mailbox.item.removeAttachmentAsync(
        attachmentId,
        { asyncContext: null },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                write('Removed attachment with the ID: ' + asyncResult.value);
            }
        });
}

Siehe auchSee also