Partager via

Gérer les pièces jointes d’un élément dans un formulaire de composition dans Outlook

  • Article

L’API JavaScript Office fournit plusieurs API que vous pouvez utiliser pour gérer les pièces jointes d’un élément lorsque l’utilisateur compose.

Joindre un fichier ou un élément Outlook

Vous pouvez joindre un fichier ou un élément Outlook à un formulaire de composition à l’aide de la méthode appropriée pour le type de pièce jointe.

Il s’agit de méthodes asynchrones, ce qui signifie que l’exécution peut se poursuivre sans attendre que l’action se termine. Selon l’emplacement d’origine et la taille de la pièce jointe ajoutée, l’appel asynchrone peut prendre un certain temps.

S’il existe des tâches qui dépendent de l’action à effectuer, vous devez effectuer ces tâches dans une fonction de rappel. Cette fonction de rappel est facultative et est appelée une fois le chargement de la pièce jointe terminé. La fonction de rappel prend un objet AsyncResult comme paramètre de sortie qui fournit toute status, erreur et valeur retournée à partir de l’ajout de la pièce jointe. Si le rappel requiert des paramètres supplémentaires, vous pouvez les spécifier dans le paramètre facultatif options.asyncContext. options.asyncContext peut être de n’importe quel type attendu par votre fonction de rappel.

Par exemple, vous pouvez définir options.asyncContext comme un objet JSON qui contient une ou plusieurs paires clé-valeur. Vous trouverez plus d’exemples sur le passage de paramètres facultatifs à des méthodes asynchrones dans la plateforme compléments Office dans programmation asynchrone dans les compléments Office. L’exemple suivant montre comment utiliser le asyncContext paramètre pour passer deux arguments à une fonction de rappel.

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

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

Vous pouvez case activée de réussite ou d’erreur d’un appel de méthode asynchrone dans la fonction de rappel à l’aide status des propriétés et error de l’objet AsyncResult . Si l’attachement se termine correctement, vous pouvez utiliser la AsyncResult.value propriété pour obtenir l’ID de pièce jointe. Il s’agit d’un nombre entier que vous pouvez ensuite utiliser pour supprimer la pièce jointe.

Remarque

L’ID de pièce jointe est valide uniquement dans la même session et n’est pas garanti pour être mappé à la même pièce jointe entre les sessions. Il peut s’agir, par exemple, de la fin d’une session lorsque l’utilisateur ferme le complément, ou si l’utilisateur commence à composer dans un formulaire inline et sort par la suite le formulaire inline pour continuer dans une fenêtre distincte.

Conseil

Il existe des limites aux fichiers ou éléments Outlook que vous pouvez joindre à un élément de courrier, comme le nombre de pièces jointes et leur taille. Pour plus d’informations, consultez Limites de l’API JavaScript.

Joindre un fichier

Vous pouvez joindre un fichier à un message ou un rendez-vous dans un formulaire de composition en utilisant la addFileAttachmentAsync méthode et en spécifiant l’URI du fichier. Vous pouvez également utiliser la addFileAttachmentFromBase64Async méthode , en spécifiant la chaîne encodée en Base64 comme entrée. Si le fichier est protégé, vous pouvez inclure une identité appropriée ou un jeton d’authentification comme paramètre de chaîne de requête d’URI. Exchange effectuera un appel à l’URI pour obtenir la pièce jointe, et le service web qui protège le fichier devra utiliser le jeton comme moyen d’authentification.

Remarque

L’URI du fichier à joindre doit prendre en charge la mise en cache en production. Le serveur hébergeant l’image ne doit pas retourner d’en-tête Cache-Control qui spécifie no-cache, no-storeou des options similaires dans la réponse HTTP. Toutefois, lorsque vous développez le complément et apportez des modifications aux fichiers, la mise en cache peut vous empêcher de voir vos modifications. Nous vous recommandons d’utiliser Cache-Control des en-têtes pendant le développement.

L’exemple JavaScript suivant est un complément de composition qui joint un fichier, picture.png, à partir d’un serveur web au message ou rendez-vous en cours de composition. La fonction de rappel prend asyncResult comme paramètre, vérifie le résultat status et obtient l’ID de pièce jointe si la méthode réussit.

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

Pour ajouter une image en base64 inline au corps d’un message ou d’un rendez-vous en cours de composition, vous devez d’abord obtenir le corps de l’élément actuel à l’aide de la Office.context.mailbox.item.body.getAsync méthode avant d’insérer l’image à l’aide de la addFileAttachmentFromBase64Async méthode . Sinon, l’image ne s’affichera pas dans le corps une fois qu’elle est insérée. Pour obtenir de l’aide, consultez l’exemple JavaScript suivant, qui ajoute une image en Base64 inline au début d’un corps d’élément.

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

Joindre un élément Outlook

Vous pouvez joindre un élément Outlook (par exemple, un e-mail, un calendrier ou un élément contact) à un message ou un rendez-vous dans un formulaire de composition en spécifiant l’ID des services Web Exchange (EWS) de l’élément et en utilisant la addItemAttachmentAsync méthode . Vous pouvez obtenir l’ID EWS d’un e-mail, d’un calendrier, d’un contact ou d’un élément de tâche dans la boîte aux lettres de l’utilisateur en utilisant la méthode mailbox.makeEwsRequestAsync et en accédant à l’opération EWS FindItem. La propriété item.itemId fournit également l’ID EWS d’un élément existant dans un formulaire de lecture.

La fonction JavaScript suivante, addItemAttachment, étend le premier exemple ci-dessus et ajoute un élément en tant que pièce jointe à l’e-mail ou au rendez-vous en cours de composition. La fonction prend comme argument l’ID EWS de l’élément qui doit être joint. Si l’attachement réussit, il obtient l’ID de pièce jointe pour un traitement ultérieur, y compris la suppression de cette pièce jointe dans la même 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 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);
            }
        });
}

Remarque

Vous pouvez utiliser un complément de composition pour joindre un instance d’un rendez-vous périodique dans Outlook sur le web, sur des appareils mobiles ou dans un nouvel Outlook sur Windows. Toutefois, dans un client Outlook de prise en charge sur Windows ou sur Mac, une tentative d’attachement d’un instance entraînerait l’attachement de la série périodique (rendez-vous parent).

Obtention de pièces jointes

Les API permettant d’obtenir des pièces jointes en mode composition sont disponibles à partir de l’ensemble de conditions requises 1.8.

Vous pouvez utiliser la méthode getAttachmentsAsync pour obtenir les pièces jointes du message ou du rendez-vous en cours de composition.

Pour obtenir le contenu d’une pièce jointe, vous pouvez utiliser la méthode getAttachmentContentAsync . Les formats pris en charge sont répertoriés dans l’énumération AttachmentContentFormat .

Vous devez fournir une fonction de rappel pour case activée pour le status et toute erreur à l’aide de l’objet AsyncResult de paramètre de sortie. Vous pouvez également passer des paramètres supplémentaires à la fonction de rappel à l’aide du paramètre facultatif asyncContext .

L’exemple JavaScript suivant obtient les pièces jointes et vous permet de configurer une gestion distincte pour chaque format de pièce jointe pris en charge.

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

Supprimer une pièce jointe

Vous pouvez supprimer un fichier ou une pièce jointe d’un élément de message ou de rendez-vous dans un formulaire de composition en spécifiant l’ID de pièce jointe correspondant lors de l’utilisation de la méthode removeAttachmentAsync .

Importante

Si vous utilisez l’ensemble de conditions requises 1.7 ou une version antérieure, vous devez uniquement supprimer les pièces jointes que le même complément a ajoutées dans la même session.

À l’instar des addFileAttachmentAsyncméthodes , addItemAttachmentAsyncet getAttachmentsAsync , removeAttachmentAsync est une méthode asynchrone. Vous devez fournir une fonction de rappel pour case activée pour le status et toute erreur à l’aide de l’objet AsyncResult de paramètre de sortie. Vous pouvez également passer des paramètres supplémentaires à la fonction de rappel à l’aide du paramètre facultatif asyncContext .

La fonction JavaScript suivante, removeAttachment, continue d’étendre les exemples ci-dessus et supprime la pièce jointe spécifiée de l’e-mail ou du rendez-vous en cours de composition. La fonction prend comme argument l’ID de la pièce jointe à supprimer. Vous pouvez obtenir l’ID d’une pièce jointe après un appel de méthode , ou réussiaddFileAttachmentAsync, et l’utiliser dans un appel de méthode suivantremoveAttachmentAsync.addItemAttachmentAsyncaddFileAttachmentFromBase64Async Vous pouvez également appeler getAttachmentsAsync (introduit dans l’ensemble de conditions requises 1.8) pour obtenir les pièces jointes et leurs ID pour cette session de complément.

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

Conseil

La removeAttachmentAsync méthode ne supprime pas les pièces jointes inline d’un élément de courrier. Pour supprimer une pièce jointe inline, commencez par obtenir le corps de l’élément, puis supprimez toutes les références de la pièce jointe de son contenu. Utilisez les API Office.Body pour obtenir et définir le corps d’un élément.

Voir aussi