Implémenter un volet Office épinglable dans Outlook

  • Article

La forme d’expérience utilisateur du volet Office pour les commandes de complément ouvre un volet office vertical à droite d’un message ouvert ou d’une demande de réunion. Cela permet à un complément de fournir une interface utilisateur pour des interactions plus détaillées, telles que le remplissage de plusieurs champs de texte. Ce volet Office peut être affiché dans le volet de lecture lors de l’affichage d’une liste de messages, ce qui permet un traitement rapide d’un message.

Toutefois, par défaut, si un utilisateur dispose d’un volet Office de complément ouvert pour un message dans le volet de lecture, puis sélectionne un nouveau message, le volet Office est automatiquement fermé. Pour un complément très sollicité, l’utilisateur peut préférer conserver ce volet ouvert, supprimant ainsi le besoin de réactiver le complément sur chaque message. Avec les volets Office épinglés, votre complément peut donner cette option à l’utilisateur.

Remarque

Bien que la fonctionnalité du volet Office épinglée ait été introduite dans l’ensemble de conditions requises 1.5, elle est actuellement disponible uniquement pour les abonnés Microsoft 365 à l’aide des éléments suivants :

  • Outlook 2016 ou version ultérieure sur Windows (build 7668.2000 ou version ultérieure pour les utilisateurs dans les canaux Actuels ou Microsoft 365 Insider, build 7900.xxxx ou version ultérieure pour les utilisateurs des canaux différés)
  • Outlook 2016 ou version ultérieure sur Mac (version 16.13.503 ou ultérieure)
  • Outlook moderne sur le web
  • nouvel Outlook sur Windows (préversion)

Importante

Les volets Office épinglés ne sont pas disponibles pour les éléments suivants :

  • Rendez-vous/réunions
  • Outlook.com

Prise en charge de l’épinglage des volets des tâches

La première étape consiste à ajouter une prise en charge de l’épinglage, ce qui est effectué dans le manifeste du complément. Le balisage varie en fonction du type de manifeste utilisé par votre complément.

Ajoutez une propriété « épinglé », définie sur true, à l’objet dans le tableau « actions » qui définit le bouton ou l’élément de menu qui ouvre le volet Office. Voici un exemple.

"actions": [
    {
        "id": "OpenTaskPane",
        "type": "openPage",
        "view": "TaskPaneView",
        "displayName": "OpenTaskPane",
        "pinnable": true
    }
]

Pour obtenir un exemple complet, consultez le contrôle msgReadOpenPaneButton dans l’exemple de manifeste command-demo.

Remarque

L’épinglage du volet Office est automatiquement pris en charge dans un complément qui s’active sans que le volet de lecture soit activé ou qu’un message soit sélectionné au préalable. 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é.

Gestion des mises à jour de l’interface utilisateur en fonction du message actuellement sélectionné

Pour mettre à jour l’interface utilisateur ou les variables internes de votre volet Office en fonction de l’élément actif, vous devez enregistrer un gestionnaire d’événements pour être notifié de la modification.

Mettre en œuvre le gestionnaire d’événements

Le gestionnaire d’événements doit accepter un seul paramètre, qui est un littéral d’objet. La propriété type de cet objet est réglée sur Office.EventType.ItemChanged. Lorsque l’événement est appelé, l’objet Office.context.mailbox.item est déjà mis à jour pour refléter l’élément actuellement sélectionné.

function itemChanged(eventArgs) {
  // Update UI based on the new current item.
  updateTaskPaneUI(Office.context.mailbox.item);
}

Importante

L’implémentation des gestionnaires d’événements pour un événement ItemChanged implique de vérifier si l’élément Office.content.mailbox.item est null.

// Example implementation.
function updateTaskPaneUI(item) {
  // Assuming that item is always a read item (instead of a compose item).
  if (item != null) console.log(item.subject);
}

Enregistrement du gestionnaire d’événements

Utilisez la méthode Office.context.mailbox.addHandlerAsync pour inscrire votre gestionnaire d’événements pour l’événement Office.EventType.ItemChanged. Cette opération doit être effectuée dans la Office.onReady fonction de votre volet Office.

Office.onReady(() => {
  $(document).ready(() => {
    // Set up the ItemChanged event.
    Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, itemChanged);
    updateTaskPaneUI(Office.context.mailbox.item);
  });
});

Épinglage du volet Office en sélection multiple

Dans Outlook sur le web et la nouvelle version d’Outlook sur Windows (préversion), lorsque le volet Office d’un complément qui implémente la fonctionnalité de sélection multiple d’élément 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 et sur Mac, le volet Office d’un complément à sélection multiple n’est pas automatiquement épinglé et se ferme lorsqu’un utilisateur bascule vers un autre élément de courrier.

Déployer sur les utilisateurs

Si vous envisagez de publier votre complément Outlook sur AppSource et qu’il est configuré avec un volet Office pouvant être épinglé, le contenu de votre complément ne doit pas être statique et doit afficher clairement les données relatives au message qui est ouvert ou sélectionné dans la boîte aux lettres. Cela garantit que votre complément réussira la validation AppSource.

Voir aussi

Pour un exemple de complément qui implémente un volet Office épinglables, consultez command-demo sur GitHub.