Activer votre complément Outlook sur plusieurs messages

  • Article

Avec la fonctionnalité de sélection multiple d’élément, votre complément Outlook peut désormais activer et effectuer des opérations sur plusieurs messages sélectionnés en une seule fois. Certaines opérations, telles que le chargement de messages dans votre système de gestion de la relation client (CRM) ou la catégorisation de nombreux éléments, peuvent désormais être effectuées facilement en un seul clic.

Les sections suivantes montrent comment configurer votre complément pour récupérer la ligne d’objet et l’adresse e-mail de l’expéditeur de plusieurs messages en mode lecture.

Remarque

La prise en charge de la fonctionnalité de sélection multiple d’élément a été introduite dans l’ensemble de conditions requises 1.13, avec des propriétés d’élément supplémentaires désormais disponibles dans les ensembles de conditions requises suivants. Voir les clients et les plateformes qui prennent en charge cet ensemble de conditions requises.

Configuration de votre environnement

Suivez le guide de démarrage rapide Outlook pour créer un projet de complément avec le générateur Yeoman pour les compléments Office.

Configurer le manifeste

  1. Dans votre éditeur de code préféré, ouvrez le projet de démarrage rapide Outlook que vous avez créé.

  2. Ouvrez le fichier manifest.json situé à la racine du projet.

  3. Dans le tableau « authorization.permissions.resourceSpecific », remplacez la valeur de la propriété « name » par « Mailbox.ReadWrite.User ». Cela doit ressembler à ce qui suit lorsque vous avez terminé.

    "authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "Mailbox.ReadWrite.User",
                "type": "Delegated"
            }
        ]
    }
},

  4. Dans le premier objet du tableau « extensions.runtimes », apportez les modifications suivantes.

    1. Remplacez la propriété « requirements.capabilities.minVersion » par « 1.13 ».
    2. Dans le même objet « actions », ajoutez la propriété « supportsNoItemContext » et définissez-la sur true.
    3. Dans le même objet « actions », ajoutez la propriété « multiselect » et définissez-la sur true.

    Votre code doit ressembler à ce qui suit une fois que vous avez apporté les modifications.

    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ]
        },
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "TaskPaneRuntimeShow",
                "type": "openPage",
                "pinnable": false,
                "view": "dashboard",
                "supportsNoItemContext": true,
                "multiselect": true
            }
        ]
    },
    ...
]

  5. Supprimez le deuxième objet du tableau « extensions.runtimes », dont « id » est « CommandsRuntime ».

  6. Dans le tableau « extensions.ribbons.tabs.controls », supprimez le deuxième objet, dont « id » est « ActionButton ».

  7. Enregistrez vos modifications.

Remarque

Si vous activez la fonctionnalité de sélection multiple d’élément dans votre complément, votre complément prend automatiquement en charge la fonctionnalité de contexte sans élément , même si elle n’est pas explicitement configurée dans le manifeste. Pour plus d’informations sur le comportement d’épinglage du volet Office dans les compléments à sélection multiple, consultez Épinglage du volet Office dans les compléments à sélection multiple.

Configurer le volet Office

La sélection multiple d’élément s’appuie sur l’événement SelectedItemsChanged pour déterminer quand les messages sont sélectionnés ou désélectionnés. Cet événement nécessite une implémentation du volet Office.

  1. À partir du dossier ./src/taskpane , ouvrez taskpane.html.

  2. Dans l’élément <body>, remplacez tout l’élément <main> par le balisage suivant.

    <main id="app-body" class="ms-welcome__main">
    <h2 class="ms-font-l">Get information about each selected message</h2>
    <ul id="selected-items"></ul>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Get information</span>
    </div>
</main>

  3. Pour Outlook classique sur Windows uniquement. Remplacez l’élément de script existant par le balisage suivant. Cela fait référence à la préversion de l’API JavaScript Office.

    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>

    Remarque

    La préversion de l’API JavaScript Office est utilisée, car cette procédure pas à pas implémente les loadItemByIdAsync méthodes et unloadAsync , qui sont actuellement en préversion. Si votre complément à sélection multiple n’implémente pas ces méthodes, utilisez https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js à la place. Pour plus d’informations, consultez Référencement de la bibliothèque d’API JavaScript Office.

  4. Enregistrez vos modifications.

Implémenter un gestionnaire pour l’événement SelectedItemsChanged

Pour alerter votre complément lorsque l’événement SelectedItemsChanged se produit, vous devez inscrire un gestionnaire d’événements à l’aide de la addHandlerAsync méthode .

  1. À partir du dossier ./src/taskpane , ouvrez taskpane.js.

  2. Remplacez la Office.onReady() fonction par ce qui suit :

    let list;

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
    document.getElementById("run").onclick = run;
    list = document.getElementById("selected-items");

    // Register an event handler to identify when messages are selected.
    Office.context.mailbox.addHandlerAsync(Office.EventType.SelectedItemsChanged, run, (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      console.log("Event handler added.");
    });
  }
});

  3. Enregistrez vos modifications.

Obtenir des propriétés et exécuter des opérations sur les messages sélectionnés

Maintenant que vous avez inscrit un gestionnaire d’événements, votre complément peut désormais obtenir des propriétés ou exécuter des opérations sur plusieurs messages sélectionnés. Il existe deux façons de traiter les messages sélectionnés. L’utilisation de chaque option dépend des propriétés et des opérations dont vous avez besoin pour votre scénario.

  • Appelez la méthode getSelectedItemsAsync pour obtenir les propriétés suivantes.

    • Valeur booléenne de pièce jointe
    • Conversation ID
    • Internet message ID
    • ID d’élément
    • Mode Élément (Read ou Compose)
    • Type d’élément (Message est le seul type pris en charge pour l’instant)
    • Ligne d’objet

  • Appelez la méthode loadItemByIdAsync (préversion) pour obtenir les propriétés qui ne sont pas fournies par getSelectedItemsAsync ou pour exécuter des opérations sur les messages sélectionnés. La loadItemByIdAsync méthode charge un message sélectionné à la fois à l’aide de l’ID EWS (Exchange Web Services) du message. Pour obtenir les ID EWS des messages sélectionnés, nous vous recommandons d’appeler getSelectedItemsAsync. Après avoir traité un message sélectionné à l’aide loadItemByIdAsyncde , vous devez appeler la méthode unloadAsync (préversion) avant d’appeler loadItemByIdAsync sur un autre message sélectionné.

    Conseil

    Avant d’utiliser la loadItemByIdAsync méthode , déterminez si vous pouvez déjà accéder aux propriétés dont vous avez besoin à l’aide de getSelectedItemsAsync. Si vous le pouvez, vous n’avez pas besoin d’appeler loadItemByIdAsync.

L’exemple suivant implémente les getSelectedItemsAsync méthodes et loadItemByIdAsync pour obtenir la ligne d’objet et l’adresse e-mail de l’expéditeur à partir de chaque message sélectionné.

Remarque

La loadItemByIdAsync méthode est actuellement en préversion dans Outlook classique sur Windows. Pour afficher un aperçu de cette API, installez la version 2405 (build 17606.10000) ou ultérieure. Ensuite, rejoignez le programme Microsoft 365 Insider et sélectionnez l’option Canal bêta .

  1. Dans taskpane.js, remplacez la fonction existante run par le code suivant.

    export async function run() {
  // Clear the list of previously selected messages, if any.
  clearList(list);

  // Get the subject line and sender's email address of each selected message and log it to a list in the task pane.
  Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log(asyncResult.error.message);
      return;
    }

    const selectedItems = asyncResult.value;
    getItemInfo(selectedItems);
  });
}

// Gets the subject line and sender's email address of each selected message.
async function getItemInfo(selectedItems) {
  for (const item of selectedItems) {
    addToList(item.subject);
    // The loadItemByIdAsync method is currently only available to preview in classic Outlook on Windows.
    if (Office.context.diagnostics.platform === Office.PlatformType.PC) {
      await getSenderEmailAddress(item);
    }
  }
}

// Gets the sender's email address of each selected message.
async function getSenderEmailAddress(item) {
  const itemId = item.itemId;
  await new Promise((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
      }

      const loadedItem = result.value;
      const sender = loadedItem.from.emailAddress;
      appendToListItem(sender);

      // Unload the current message before processing another selected message.
      loadedItem.unloadAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        resolve();
      });
    });
  });
}

// Clears the list in the task pane.
function clearList(list) {
  while (list.firstChild) {
    list.removeChild(list.firstChild);
  }
}

// Adds an item to a list in the task pane.
function addToList(item) {
  const listItem = document.createElement("li");
  listItem.textContent = item;
  list.appendChild(listItem);
}

// Appends data to the last item of the list in the task pane.
function appendToListItem(data) {
  const listItem = list.lastChild;
  listItem.textContent += ` (${data})`;
}

  2. Enregistrez vos modifications.

Essayez

  1. À partir d’un terminal, exécutez le code suivant dans le répertoire racine de votre projet. Cela démarre le serveur web local et charge une version test de votre complément.

    npm start

    Conseil

    Si votre complément ne charge pas automatiquement la version test, suivez les instructions fournies dans Charger une version test des compléments Outlook pour le charger manuellement dans Outlook.

  2. Dans Outlook, vérifiez que le volet de lecture est activé. Pour activer le volet de lecture, consultez Utiliser et configurer le volet de lecture pour afficher un aperçu des messages.

  3. Accédez à votre boîte de réception et choisissez plusieurs messages en maintenant la touche Ctrl enfoncée tout en sélectionnant messages.

  4. Sélectionnez Afficher le volet des tâches. L’emplacement du complément varie en fonction de votre client Outlook. Pour obtenir des conseils, voir Utiliser des compléments dans Outlook.

  5. Dans le volet Office, sélectionnez Obtenir des informations. Une liste des lignes d’objet et des adresses e-mail de l’expéditeur des messages sélectionnés s’affiche dans le volet Office.

    Exemple de liste de lignes d’objet récupérées à partir de plusieurs messages sélectionnés.

  6. Lorsque vous souhaitez arrêter le serveur web local et désinstaller le complément, suivez les instructions applicables :

    • Pour arrêter le serveur, exécutez la commande suivante. Si vous avez utilisé npm start, la commande suivante doit également désinstaller le complément.

      npm stop

    • Si vous avez chargé manuellement le complément, consultez Supprimer un complément chargé de manière indépendante.

Comportement et limitations de sélection multiple d’élément

La sélection multiple d’élément prend uniquement en charge les messages dans une boîte aux lettres Exchange en mode lecture et composition. Un complément Outlook s’active uniquement sur plusieurs messages si les conditions suivantes sont remplies.

  • Les messages doivent être sélectionnés dans une boîte aux lettres Exchange à la fois. Les boîtes aux lettres non-Exchange ne sont pas prises en charge.
  • Les messages doivent être sélectionnés dans un dossier de boîte aux lettres à la fois. Un complément ne s’active pas sur plusieurs messages s’ils se trouvent dans des dossiers différents, sauf si l’affichage Conversations est activé. Pour plus d’informations, consultez Sélection multiple dans les conversations.
  • Un complément doit implémenter un volet Office pour détecter l’événement SelectedItemsChanged .
  • Le volet de lecture dans Outlook doit être activé. Une exception à cela est si la fonctionnalité de sélection multiple d’élément est activée via la fonctionnalité de contexte aucun élément dans le manifeste. Pour plus d’informations, voir Activer votre complément Outlook sans que le volet de lecture soit activé ou qu’un message soit sélectionné.
  • Un maximum de 100 messages peuvent être sélectionnés à la fois.
  • La loadItemByIdAsync méthode ne traite qu’un seul message sélectionné à la fois. N’oubliez pas d’appeler unloadAsync une fois loadItemByIdAsync le traitement du message terminé. De cette façon, le complément peut charger et traiter le message sélectionné suivant.
  • En règle générale, vous pouvez uniquement exécuter des opérations d’obtention sur un message sélectionné chargé à l’aide de la loadItemByIdAsync méthode . Toutefois, la gestion des catégories d’un message chargé est une exception. Vous pouvez ajouter, obtenir et supprimer des catégories à partir d’un message chargé.
  • La loadItemByIdAsync méthode est prise en charge dans les compléments de commande de volet office et de fonction. Cette méthode n’est pas prise en charge dans les compléments d’activation basée sur les événements .

Remarque

Les invitations et réponses aux réunions sont considérées comme des messages, et non comme des rendez-vous, et peuvent donc être incluses dans une sélection.

Sélection multiple dans les conversations

La sélection multiple d’élément prend en charge l’affichage Conversations , qu’il soit activé sur votre boîte aux lettres ou sur des dossiers spécifiques. Le tableau suivant décrit les comportements attendus lorsque les conversations sont développées ou réduites, lorsque l’en-tête de conversation est sélectionné et lorsque les messages de conversation se trouvent dans un autre dossier que celui actuellement affiché.

Sélection Vue de conversation développée Vue de conversation réduite
L’en-tête de conversation est sélectionné Si l’en-tête de conversation est le seul élément sélectionné, un complément prenant en charge la sélection multiple ne s’active pas. Toutefois, si d’autres messages non-en-tête sont également sélectionnés, le complément s’active uniquement sur ceux-ci et non sur l’en-tête sélectionné. Le comportement diffère selon le client Outlook.

Outlook sur Windows (classique) et sur Mac :
Le message le plus récent (autrement dit, le premier message de la pile de conversations) est inclus dans la sélection du message.

Si le message le plus récent de la conversation se trouve dans un autre dossier de celui actuellement affiché, le message suivant dans la pile située dans le dossier actif est inclus dans la sélection.

Outlook sur le web et nouveau Outlook sur Windows :
Tous les messages de la pile de conversations sont sélectionnés. Cela inclut les messages de la conversation qui se trouvent dans des dossiers autres que ceux actuellement affichés.
Plusieurs messages sélectionnés dans une pile de conversations se trouvent dans le même dossier que celui actuellement affiché Tous les messages choisis dans la même conversation sont inclus dans la sélection. Non applicable Vous devez développer la pile des conversations pour sélectionner plusieurs messages à partir de celle-ci.
Plusieurs messages sélectionnés dans une pile de conversations se trouvent dans des dossiers différents de ceux actuellement affichés Tous les messages choisis dans la même conversation sont inclus dans la sélection. Non applicable Vous devez développer la pile des conversations pour sélectionner plusieurs messages à partir de celle-ci.

Remarque

Sur tous les clients Outlook, vous ne pouvez pas sélectionner plusieurs messages qui appartiennent à différentes conversations. Si vous développez une autre conversation tandis qu’une autre conversation est développée, l’affichage de la conversation actuellement développée se réduit et tous les messages sélectionnés sont désélectionnés. Toutefois, vous pouvez sélectionner plusieurs messages de la même conversation développée et des messages qui ne font pas partie d’une conversation en même temps.

Épinglage du volet Office dans des compléments à sélection multiple

Dans Outlook sur le web et dans le nouvel Outlook sur Windows, lorsque le volet Office d’un complément à sélection multiple est ouvert, il est automatiquement épinglé au client Outlook. Il reste épinglé même lorsqu’un utilisateur bascule vers un autre élément de courrier ou sélectionne l’icône d’épingle dans le volet Office. Le volet Office ne peut être fermé qu’en sélectionnant le bouton Fermer dans le volet Office.

À l’inverse, dans Outlook sur Windows (classique) et sur Mac, le volet Office n’est pas automatiquement épinglé et se ferme lorsqu’un utilisateur bascule vers un autre élément de courrier.

Étapes suivantes

Maintenant que vous avez activé votre complément pour fonctionner sur plusieurs messages sélectionnés, vous pouvez étendre les fonctionnalités de votre complément et améliorer davantage l’expérience utilisateur. Explorez les opérations plus complexes en utilisant les ID d’élément des messages sélectionnés avec des services, tels que Microsoft Graph.

Voir aussi