Freigeben über

Verwalten der Anlagen eines Elements in einem Verfassenformular in Outlook

  • Artikel

Die Office JavaScript-API stellt mehrere APIs bereit, mit deren Hilfe Sie die Anlagen eines Elements beim Verfassen des Benutzers verwalten können.

Anfügen einer Datei oder eines Outlook-Elements

Sie können eine Datei oder ein Outlook-Element an ein Formular zum Verfassen anfügen, indem Sie die Methode verwenden, die für den Anlagetyp geeignet ist.

Dies sind asynchrone Methoden, was bedeutet, dass die Ausführung weitergehen kann, ohne auf den Abschluss der Aktion zu warten. Abhängig vom ursprünglichen Speicherort und der Größe der hinzugefügten Anlage kann es eine Weile dauern, bis der asynchrone Aufruf abgeschlossen ist.

Wenn Es Aufgaben gibt, die von der auszuführenden Aktion abhängen, sollten Sie diese Aufgaben in einer Rückruffunktion ausführen. Diese Rückruffunktion ist optional und wird aufgerufen, wenn der Upload der Anlage abgeschlossen ist. Die Rückruffunktion verwendet ein AsyncResult-Objekt als Ausgabeparameter, der alle status, Fehler und zurückgegebenen Werte beim Hinzufügen der Anlage bereitstellt. Wenn der Rückruf zusätzliche Parameter erfordert, können Sie diese im optionalen Parameter options.asyncContext angeben. options.asyncContext kann einen beliebigen Typ aufweisen, den Ihre Rückruffunktion erwartet.

Sie können beispielsweise als JSON-Objekt definieren options.asyncContext , das mindestens ein Schlüssel-Wert-Paar enthält. Weitere Beispiele zum Übergeben optionaler Parameter an asynchrone Methoden finden Sie auf der Office-Add-Ins-Plattform unter Asynchrone Programmierung in Office-Add-Ins. Das folgende Beispiel zeigt, wie sie den asyncContext -Parameter verwenden, um zwei Argumente an eine Rückruffunktion zu übergeben.

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

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

Sie können mithilfe status der Eigenschaften AsyncResult und error des Objekts in der Rückruffunktion überprüfen, ob ein asynchroner Methodenaufruf erfolgreich oder fehlerhaft ist. Wenn das Anfügen erfolgreich abgeschlossen wurde, können Sie die AsyncResult.value -Eigenschaft verwenden, um die Anlagen-ID abzurufen. Die Anlage-ID ist eine Ganzzahl, die Sie später zum Entfernen der Anlage benötigen.

Hinweis

Die Anlagen-ID ist nur innerhalb derselben Sitzung gültig und wird nicht garantiert, dass sie sitzungsübergreifend derselben Anlage zugeordnet wird. Beispiele für den Ablauf einer Sitzung sind, wenn der Benutzer das Add-In schließt oder wenn der Benutzer mit dem Verfassen in einem Inlineformular beginnt und anschließend das Inlineformular ausgibt, um in einem separaten Fenster fortzufahren.

Tipp

Es gibt Grenzwerte für die Dateien oder Outlook-Elemente, die Sie an ein E-Mail-Element anfügen können, z. B. die Anzahl von Anlagen und deren Größe. Weitere Anleitungen finden Sie unter Grenzwerte für die JavaScript-API.

Anfügen einer Datei

Sie können eine Datei an eine Nachricht oder einen Termin in einem Verfassenformular anfügen, indem Sie die addFileAttachmentAsync -Methode verwenden und den URI der Datei angeben. Sie können auch die addFileAttachmentFromBase64Async -Methode verwenden und die Base64-codierte Zeichenfolge als Eingabe 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.

Hinweis

Der URI der datei, die angefügt werden soll, muss die Zwischenspeicherung in der Produktion unterstützen. Der Server, auf dem das Image gehostet wird, sollte keinen Header zurückgebenCache-Control, der , no-storeoder ähnliche Optionen in der HTTP-Antwort angibtno-cache. Wenn Sie jedoch das Add-In entwickeln und Änderungen an Dateien vornehmen, kann das Zwischenspeichern verhindern, dass Sie Ihre Änderungen sehen. Es wird empfohlen, Header während der Entwicklung zu verwenden Cache-Control .

Das folgende JavaScript-Beispiel ist ein Verfassen-Add-In, das eine Datei picture.png von einem Webserver an die Nachricht oder den Termin anfügt, die erstellt wird. Die Rückruffunktion verwendet asyncResult als Parameter, überprüft das Ergebnis status und ruft die Anlagen-ID ab, wenn die Methode erfolgreich ist.

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(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 function is invoked and gets the attachment ID.
        // You can optionally pass any object that you would
        // access in the callback function 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.
                    const 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;
}

Um ein Base64-Inlinebild zum Textkörper einer Nachricht oder eines Termins hinzuzufügen, müssen Sie zuerst den aktuellen Elementtext mithilfe der Office.context.mailbox.item.body.getAsync -Methode abrufen, bevor Sie das Bild mithilfe der addFileAttachmentFromBase64Async -Methode einfügen. Andernfalls wird das Bild nicht im Text gerendert, nachdem es eingefügt wurde. Eine Anleitung finden Sie im folgenden JavaScript-Beispiel, das am Anfang eines Elementtexts ein Base64-Inlinebild hinzufügt.

const mailItem = Office.context.mailbox.item;
const base64String =
  "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";

// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
  if (bodyResult.status === Office.AsyncResultStatus.Succeeded) {
    // Insert the Base64 image to the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
      if (attachResult.status === Office.AsyncResultStatus.Succeeded) {
        let body = attachResult.asyncContext;
        body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);
        mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
          if (setResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log("Inline Base64 image added to the body.");
          } else {
            console.log(setResult.error.message);
          }
        });
      } else {
        console.log(attachResult.error.message);
      }
    });
  } else {
    console.log(bodyResult.error.message);
  }
});

Anfügen eines Outlook-Elements

Sie können ein Outlook-Element (z. B. E-Mail, Kalender oder Kontaktelement) an eine Nachricht oder einen Termin in einem Verfassenformular anfügen, indem Sie die EXCHANGE-Webdienst-ID (EWS) des Elements angeben und die addItemAttachmentAsync -Methode verwenden. Sie können die EWS-ID eines E-Mail-, Kalender-, Kontakt- oder Aufgabenelements im Postfach des Benutzers abrufen, indem Sie die mailbox.makeEwsRequestAsync-Methode verwenden und auf den EWS-Vorgang FindItem zugreifen. Die item.itemId-Eigenschaft liefert Ihnen auch die EWS-ID eines vorhandenen Elements in einem Leseformular.

Die folgende JavaScript-Funktion addItemAttachment, , erweitert das erste Beispiel oben und fügt ein Element als Anlage zu der E-Mail oder dem Termin hinzu, die erstellt wird. Die Funktion verwendet als Argument die EWS-ID des Elements, das angefügt werden soll. Wenn das Anfügen erfolgreich ist, wird die Anlagen-ID für die weitere Verarbeitung abgerufen, einschließlich des Entfernens dieser Anlage in derselben Sitzung.

// 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 function is invoked. Here, the callback
    // function 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 function 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 {
                const attachmentID = asyncResult.value;
                write('ID of added attachment: ' + attachmentID);
            }
        });
}

Hinweis

Sie können ein Verfassen-Add-In verwenden, um eine instance einer Terminserie in Outlook im Web, auf mobilen Geräten oder im neuen Outlook unter Windows anzufügen. In einem unterstützenden Outlook-Client unter Windows oder macos würde der Versuch, eine instance anzufügen, jedoch dazu führen, dass die serie (der übergeordnete Termin) angefügt wird.

Abrufen von Anlagen

APIs zum Abrufen von Anlagen im Verfassenmodus sind über anforderungssatz 1.8 verfügbar.

Sie können die getAttachmentsAsync-Methode verwenden, um die Anlagen der Nachricht oder des Termins abzurufen, die erstellt wird.

Um den Inhalt einer Anlage abzurufen, können Sie die getAttachmentContentAsync-Methode verwenden. Die unterstützten Formate sind in der AttachmentContentFormat-Enumeration aufgeführt.

Sie sollten eine Rückruffunktion bereitstellen, um mithilfe des Ausgabeparameterobjekts auf die AsyncResult status und jeden Fehler zu überprüfen. Sie können auch alle zusätzlichen Parameter an die Rückruffunktion übergeben, indem Sie den optionalen asyncContext Parameter verwenden.

Im folgenden JavaScript-Beispiel werden die Anlagen abgerufen, und Sie können eine unterschiedliche Behandlung für jedes unterstützte Anlagenformat einrichten.

const item = Office.context.mailbox.item;
const options = {asyncContext: {currentItem: item}};
item.getAttachmentsAsync(options, callback);

function callback(result) {
  if (result.value.length > 0) {
    for (let i = 0 ; i < result.value.length ; i++) {
      result.asyncContext.currentItem.getAttachmentContentAsync(result.value[i].id, handleAttachmentsCallback);
    }
  }
}

function handleAttachmentsCallback(result) {
  // Parse string to be a url, an .eml file, a Base64-encoded string, or an .icalendar file.
  switch (result.value.format) {
    case Office.MailboxEnums.AttachmentContentFormat.Base64:
      // Handle file attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.Eml:
      // Handle email item attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.ICalendar:
      // Handle .icalender attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.Url:
      // Handle cloud attachment.
      break;
    default:
      // Handle attachment formats that are not supported.
  }
}

Entfernen einer Anlage

Sie können eine Datei- oder Elementanlage aus einer Nachricht oder einem Terminelement in einem Verfassenformular entfernen, indem Sie die entsprechende Anlagen-ID angeben, wenn Sie die removeAttachmentAsync-Methode verwenden.

Wichtig

Wenn Sie den Anforderungssatz 1.7 oder früher verwenden, sollten Sie nur Anlagen entfernen, die dasselbe Add-In in derselben Sitzung hinzugefügt hat.

Ähnlich wie die addFileAttachmentAsyncMethoden removeAttachmentAsync , addItemAttachmentAsyncund getAttachmentsAsync ist eine asynchrone Methode. Sie sollten eine Rückruffunktion bereitstellen, um mithilfe des Ausgabeparameterobjekts auf die AsyncResult status und jeden Fehler zu überprüfen. Sie können auch alle zusätzlichen Parameter an die Rückruffunktion übergeben, indem Sie den optionalen asyncContext Parameter verwenden.

Die folgende JavaScript-Funktion erweitert removeAttachmentdie obigen Beispiele und entfernt die angegebene Anlage aus der E-Mail oder dem Termin, die gerade erstellt wird. Die Funktion verwendet als Argument die ID der zu entfernenden Anlage. Sie können die ID einer Anlage nach einem erfolgreichen addFileAttachmentAsync- oder addFileAttachmentFromBase64Async- addItemAttachmentAsync Methodenaufruf abrufen und in einem nachfolgenden removeAttachmentAsync Methodenaufruf verwenden. Sie können auch aufrufen getAttachmentsAsync (eingeführt in Anforderungssatz 1.8), um die Anlagen und ihre IDs für diese Add-In-Sitzung abzurufen.

// Removes the specified attachment from the composed item.
function removeAttachment(attachmentId) {
    // When the attachment is removed, the callback function is invoked.
    // Here, the callback function 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 function 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);
            }
        });
}

Tipp

Die removeAttachmentAsync -Methode entfernt keine Inlineanlagen aus einem E-Mail-Element. Um eine Inlineanlage zu entfernen, rufen Sie zuerst den Text des Elements ab, und entfernen Sie dann alle Verweise der Anlage aus ihrem Inhalt. Verwenden Sie die Office.Body-APIs , um den Text eines Elements abzurufen und festzulegen.

Siehe auch