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 pour gérer les pièces jointes d’un élément lorsque l’utilisateur compose un message ou un rendez-vous.

Joindre un fichier ou un élément Outlook

Joignez 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. Pour plus d’exemples sur la transmission de paramètres facultatifs à des méthodes asynchrones dans la plateforme des compléments Office, voir 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);

Pour case activée pour le résultat d’un appel de méthode asynchrone dans la fonction de rappel, utilisez les status propriétés et error de l’objet AsyncResult . Si l’attachement se termine correctement, utilisez 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, d’un serveur web au message ou au 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.

// 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: { var1: 1, var2: 2 } },
    (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.error(asyncResult.error.message);
            return;
        }

        // Get the ID of the attached file.
        const attachmentID = asyncResult.value;
        console.log(`ID of added attachment: ${attachmentID}`);
    }
);

Pour ajouter une image encodée en Base64 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 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.Failed) {
        console.error(bodyResult.error.message);
        return;
    }

    // Insert the Base64-encoded image at the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
        if (attachResult.status === Office.AsyncResultStatus.Failed) {
            console.error(attachResult.error.message);
            return;
        }

        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.Failed) {
                console.error(setResult.error.message);
                return;
            }

            console.log("Inline Base64 image added to the body.");
        });
    });
});

Joindre un élément Outlook

Pour 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, spécifiez l’ID des services web Exchange (EWS) de l’élément et utilisez la addItemAttachmentAsync méthode . Pour obtenir l’ID EWS de l’élément, utilisez la propriété item.itemId .

La fonction JavaScript suivante, addItemAttachment, étend un exemple précédent 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 l’ID EWS de l’élément à attacher en tant qu’argument. Si l’attachement réussit, il obtient l’ID de pièce jointe pour un traitement ultérieur.

// 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: { var1: 1, var2: 2 } },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

            const attachmentID = asyncResult.value;
            console.log(`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 suivantes pour obtenir les pièces jointes en mode composition sont disponibles à partir de l’ensemble de conditions requises 1.8.

Utilisez 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, utilisez 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.
  }
}

Conseil

Si le client Outlook dans lequel votre complément s’exécute ne prend pas en charge l’ensemble de conditions requises de boîte aux lettres 1.8, vous pouvez toujours obtenir une pièce jointe et son contenu à partir d’un élément composé à l’aide de Microsoft Graph ou d’EWS. Pour plus d’informations, consultez Obtenir les pièces jointes d’un élément Outlook à partir d’Exchange.

Supprimer une pièce jointe

Pour supprimer un fichier ou un élément en pièce jointe d’un message ou d’un élément de rendez-vous dans un formulaire de composition, spécifiez l’ID de pièce jointe correspondant dans 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 },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

            console.log(`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