Partager via

Obtenir, définir ou ajouter des destinataires lors de la composition d’un rendez-vous ou d’un message dans Outlook

  • Article

L’API JavaScript Office fournit des méthodes asynchrones (Recipients.getAsync, Recipients.setAsync ou Recipients.addAsync) pour obtenir, définir ou ajouter des destinataires à une forme de composition d’un rendez-vous ou d’un message. Ces méthodes asynchrones sont disponibles uniquement pour composer des compléments. Pour utiliser ces méthodes, vérifiez que vous avez configuré le manifeste de complément de manière appropriée pour qu’Outlook active le complément dans les formulaires de composition, comme décrit dans Créer des compléments Outlook pour les formulaires de composition.

Certaines des propriétés qui représentent les destinataires dans un rendez-vous ou un message sont disponibles pour l’accès en lecture dans un formulaire de composition et de lecture. Ces propriétés sont optionalAttendees et requiredAttendees pour les rendez-vous et cc et to pour les messages.

Dans un formulaire de lecture, vous pouvez accéder à la propriété directement dans l’objet parent, comme dans l’exemple suivant :

Office.context.mailbox.item.cc;

Toutefois, dans un formulaire de composition, étant donné que l’utilisateur et votre complément peuvent insérer ou modifier un destinataire en même temps, vous devez utiliser la méthode getAsync asynchrone pour obtenir ces propriétés, comme dans l’exemple suivant.

Office.context.mailbox.item.cc.getAsync(callback);

Ces propriétés sont disponibles pour l’accès en écriture uniquement dans les formulaires de composition, et non dans les formulaires de lecture.

Comme avec la plupart des méthodes asynchrones dans l’API JavaScript pour Office, getAsync, setAsyncet prennent des addAsync paramètres d’entrée facultatifs. Pour plus d’informations sur la façon de spécifier ces paramètres d’entrée facultatifs, consultez « Passage de paramètres facultatifs à des méthodes asynchrones » dans Programmation asynchrone dans les compléments Office.

Pour obtenir les destinataires

Cette section présente un exemple de code qui obtient les destinataires d’un rendez-vous ou d’un message dont la composition est en cours et affiche les adresses de messagerie des destinataires.

Dans l’API JavaScript Office, étant donné que les propriétés qui représentent les destinataires d’un rendez-vous (optionalAttendees et requiredAttendees) sont différentes de celles d’un message (cci, ccet to), vous devez d’abord utiliser la propriété item.itemType pour identifier si l’élément en cours de composition est un rendez-vous ou un message. En mode composition, toutes ces propriétés de rendez-vous et de messages sont des objets Recipients . Vous pouvez donc appeler la méthode asynchrone, Recipients.getAsync, pour obtenir les destinataires correspondants.

Pour utiliser getAsync, fournissez une fonction de rappel pour vérifier l’état, les résultats et toute erreur retournée par l’appel asynchrone getAsync . La fonction de rappel retourne un paramètre de sortie asyncResult . Utilisez ses status propriétés et error pour vérifier l’état et les éventuels messages d’erreur de l’appel asynchrone, ainsi que sa value propriété pour obtenir les destinataires réels. Les destinataires sont représentés dans un tableau d’objets EmailAddressDetails. Vous pouvez également fournir des informations supplémentaires à la fonction de rappel à l’aide du paramètre facultatif asyncContext dans l’appel getAsync .

Notez que étant donné que la getAsync méthode est asynchrone, si des actions suivantes dépendent de la réussite de l’obtention des destinataires, vous devez organiser votre code pour démarrer ces actions uniquement dans la fonction de rappel correspondante lorsque l’appel asynchrone s’est correctement terminé.

Importante

La getAsync méthode retourne uniquement les destinataires résolus par le client Outlook. Un destinataire résolu présente les caractéristiques suivantes.

  • Si le destinataire a une entrée enregistrée dans le carnet d’adresses de l’expéditeur, Outlook résout l’adresse e-mail en nom complet enregistré du destinataire.
  • Une icône d’état de réunion Teams s’affiche avant le nom ou l’adresse e-mail du destinataire.
  • Un point-virgule apparaît après le nom ou l’adresse e-mail du destinataire.
  • Le nom ou l’adresse e-mail du destinataire est souligné ou placé dans une zone.

Pour résoudre une adresse e-mail une fois qu’elle est ajoutée à un élément de courrier, l’expéditeur doit utiliser la touche Tab ou sélectionner un contact ou une adresse e-mail suggéré dans la liste de saisie semi-automatique.

Dans Outlook sur le web et sur Windows (nouveau et classique), si un utilisateur crée un message en sélectionnant le lien d’adresse e-mail d’un contact à partir d’un contact ou d’une carte de profil, il doit d’abord résoudre l’adresse e-mail afin qu’elle puisse être incluse dans les résultats de l’appel getAsync .

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getAllRecipients();
    }
});

// Gets the email addresses of all the recipients of the item being composed.
function getAllRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail 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;
    }

    // Get the recipients from the To or Required field of the item being composed.
    toRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the To or Required field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Cc or Optional field of the item being composed.
    ccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the Cc or Optional field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Bcc field of the message being composed, if applicable.
    if (bccRecipients.length > 0) {
        bccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients.
        write(`Recipients in the Bcc field: ${displayAddresses(asyncResult.value)}`);
        });
    } else {
        write("Recipients in the Bcc field: None");
    }
}

// Displays the email address of each recipient.
function displayAddresses (recipients) {
    for (let i = 0; i < recipients.length; i++) {
        write(recipients[i].emailAddress);
    }
}

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

Définir les destinataires

Cette section présente un exemple de code qui définit les destinataires du rendez-vous ou du message que l’utilisateur compose. Le fait de définir des destinataires remplace tous les destinataires existants. Cet exemple vérifie d’abord si l’élément de courrier est un rendez-vous ou un message, afin qu’il puisse appeler la méthode asynchrone, Recipients.setAsync, sur les propriétés appropriées qui représentent les destinataires du rendez-vous ou du message.

Lors de l’appel setAsyncde , fournissez un tableau comme argument d’entrée pour le recipients paramètre, dans l’un des formats suivants.

  • Un tableau de chaînes représentant des adresses SMTP.
  • Un tableau de dictionnaires, chacun contenant un nom d’affichage et une adresse de messagerie, comme indiqué dans l’exemple de code suivant.
  • Tableau d’objets EmailAddressDetails , similaire à celui retourné par la getAsync méthode .

Vous pouvez éventuellement fournir une fonction de rappel en tant qu’argument d’entrée à la setAsync méthode, pour vous assurer que tout code qui dépend de la définition réussie des destinataires s’exécute uniquement lorsque cela se produit. Si vous implémentez une fonction de rappel, utilisez les status propriétés et error du asyncResult paramètre de sortie pour vérifier l’état et tous les messages d’erreur de l’appel asynchrone. Pour fournir des informations supplémentaires à la fonction de rappel, utilisez le paramètre facultatif asyncContext dans l’appel setAsync .

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setRecipients();
    }
});

// Sets the recipients of the item being composed.
function setRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail 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;
    }

    // Set the recipients in the To or Required field of the item being composed.
    toRecipients.setAsync(
        [{
            "displayName": "Graham Durkin", 
            "emailAddress": "graham@contoso.com"
         },
         {
            "displayName": "Donnie Weinberg",
            "emailAddress": "donnie@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the To or Required field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Cc or Optional field of the item being composed.
    ccRecipients.setAsync(
        [{
            "displayName": "Perry Horning", 
            "emailAddress": "perry@contoso.com"
         },
         {
            "displayName": "Guy Montenegro",
            "emailAddress": "guy@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the Cc or Optional field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Bcc field of the message being composed.
    if (bccRecipients) {
        bccRecipients.setAsync(
            [{
                "displayName": "Lewis Cate", 
                "emailAddress": "lewis@contoso.com"
            },
            {
                "displayName": "Francisco Stitt",
                "emailAddress": "francisco@contoso.com"
            }],
            (asyncResult) => {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    console.log(asyncResult.error.message);
                    return;
                }
    
                console.log("Successfully set the recipients in the Bcc field.");
                // Run additional operations appropriate to your scenario.
        });
    }
}

Ajouter des destinataires

Si vous ne souhaitez pas remplacer des destinataires existants dans un rendez-vous ou un message, au lieu d’utiliser Recipients.setAsync, utilisez la Recipients.addAsync méthode asynchrone pour ajouter des destinataires. addAsync fonctionne de la même façon que setAsync dans le cas où il nécessite un argument d’entrée recipients . Vous pouvez éventuellement fournir une fonction de rappel et tous les arguments du rappel à l’aide du asyncContext paramètre . Ensuite, vérifiez l’état, le résultat et toute erreur de l’appel asynchrone addAsync à l’aide du asyncResult paramètre de sortie de la fonction de rappel. L’exemple suivant vérifie si l’élément en cours de composition est un rendez-vous, puis y ajoute deux participants requis.

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        addAttendees();
    }
});

// Adds the specified recipients as required attendees of the 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"
          }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully added the required attendees.");
            // Run additional operations appropriate to your scenario.
        });
    }
}

Voir aussi