Ensembles de conditions requises de l’API JavaScript pour Outlook

Les compléments Outlook déclarent les versions d’API dont ils ont besoin dans leur manifeste. Le balisage varie selon que vous utilisez le format de manifeste des compléments uniquement ou le manifeste unifié pour Microsoft 365.

"extensions": [
{
  "requirements": {
    "capabilities": [
      {
        "name": "Mailbox", "minVersion": "1.1"
      }
    ]
  },
  ...
}

<Requirements>
  <Sets>
    <Set Name="Mailbox" MinVersion="1.1" />
  </Sets>
</Requirements>

Toutes les API Outlook appartiennent au jeu de Mailboxconditions. L’ensemble de conditions requises Mailbox possède plusieurs versions et chaque nouvel ensemble d’API publié appartient à une version supérieure de l’ensemble. Tous les clients Outlook ne prennent pas en charge l’ensemble d’API le plus récent, mais si un client Outlook déclare prendre en charge un ensemble d’exigences, il prend généralement en charge toutes les API de cet ensemble d’exigences (case activée la documentation sur une API ou une fonctionnalité spécifique pour toute exception).

La configuration minimale requise spécifiée dans le manifeste détermine les clients Outlook qui peuvent charger le complément. Si le client Outlook ne prend pas en charge au moins la version spécifiée, le complément ne se charge pas. Par exemple, si vous définissez la version du jeu de conditions requises sur 1.3, le complément apparaît uniquement dans les clients Outlook qui prennent en charge la version 1.3 ou une version supérieure.

Utiliser les API des ensembles de conditions requises ultérieurs

La définition d’un ensemble de conditions requises ne limite pas les API disponibles que le complément peut utiliser. Par exemple, si le complément spécifie le jeu de conditions requises « Boîte aux lettres 1.1 », mais qu’il s’exécute dans un client Outlook qui prend en charge « Boîte aux lettres 1.3 », il peut utiliser des API à partir du cahier des charges « Boîte aux lettres 1.3 ».

Pour utiliser une nouvelle API, les développeurs peuvent vérifier si une application particulière prend en charge l’ensemble des conditions requises en procédant comme suit :

if (Office.context.requirements.isSetSupported('Mailbox', '1.3')) {
  // Perform actions.
}
else {
  // Provide alternate flow/logic.
}

Autrement, les développeurs peuvent vérifier la disponibilité d’une nouvelle API en utilisant la technique JavaScript standard.

if (item.somePropertyOrMethod !== undefined) {
  // Use item.somePropertyOrMethod.
  item.somePropertyOrMethod;
}

Ces vérifications ne sont pas nécessaires pour les API présentes dans l’ensemble de conditions requises dont la version est la même que celle spécifiée dans le manifeste.

Choisir une configuration minimale requise définie

Les développeurs doivent utiliser l’ensemble de conditions requises le plus ancien qui contient l’ensemble d’API critique pour leur scénario, sans lequel le complément ne fonctionne pas.

Ensembles de conditions requises pris en charge par les serveurs Exchange et les clients Outlook

Dans cette section, nous prenons note de la plage d’ensembles de conditions requises pris en charge par les serveurs Exchange et les clients Outlook. Pour plus d’informations sur la configuration requise pour le serveur et le client pour l’exécution de compléments Outlook, voir Conditions requises pour les compléments Outlook.

Prise en charge par le serveur Exchange

Le tableau suivant répertorie les serveurs Exchange et les ensembles de conditions requises pour la boîte aux lettres qu’ils prennent en charge. Pour que votre complément s’affiche dans Outlook hébergé dans un environnement Exchange particulier, la version que vous spécifiez comme exigence minimale définie dans le manifeste de votre complément doit être prise en charge par cet environnement.

¹ Pour exiger le jeu d’API d’identité 1.3 dans le code de votre complément Outlook, case activée s’il est pris en charge en appelant isSetSupported('IdentityAPI', '1.3'). Sa déclaration dans le manifeste du Outlook n’est pas prise en charge. Vous pouvez également déterminer si l’API est prise en charge en vérifiant qu’elle n’est pas undefined. Pour plus d’informations, consultez Utilisation des API d’un ensemble de conditions requises ultérieure.

Même si un complément implémente des fonctionnalités d’ensembles de conditions requises ultérieurs qui ne sont pas pris en charge dans un environnement Exchange local, il peut toujours être ajouté à un client Outlook tant que la configuration minimale requise spécifiée dans son manifeste correspond à celles prises en charge par Exchange local. Toutefois, une fonctionnalité implémentée ne fonctionne que si le client Outlook dans lequel le complément est installé prend en charge la configuration minimale requise requise pour une fonctionnalité. Par exemple, un complément de signature spécifiant 1.5 dans son manifeste sera installé et chargé dans l’environnement local Exchange 2019. Toutefois, son appel à Body.setSignatureAsync, qui a été introduit dans l’ensemble de conditions requises 1.10, ne s’exécutera que si le client Outlook sur lequel le complément est installé prend en charge la version 1.10.

Pour déterminer les ensembles d’exigences pris en charge par différents clients Outlook, consultez Prise en charge des clients Outlook. Nous vous recommandons de compléter ce paramètre avec la documentation sur la fonctionnalité spécifique pour toute exception.

Prise en charge du client Outlook

Les compléments sont pris en charge dans Outlook sur les plateformes suivantes.

¹ Les compléments ne sont pas pris en charge dans Outlook sur Android, sur iOS et dans le web mobile moderne avec des comptes Exchange locaux. Certains appareils iOS prennent toujours en charge les compléments lors de l’utilisation de comptes Exchange locaux avec Outlook sur le web classique. Pour plus d’informations sur les appareils pris en charge, consultez Configuration requise pour l’exécution des compléments Office.

² Les compléments ne fonctionnent pas dans l’Outlook sur le web moderne sur les smartphones iPhone et Android. Pour plus d’informations sur les appareils pris en charge, consultez Configuration requise pour l’exécution des compléments Office.

³ Pour exiger le jeu d’API d’identité 1.3 dans le code de votre complément Outlook, case activée s’il est pris en charge en appelant isSetSupported('IdentityAPI', '1.3'). Sa déclaration dans le manifeste du Outlook n’est pas prise en charge. Vous pouvez également déterminer si l’API est prise en charge en vérifiant qu’elle n’est pas undefined. Pour plus d’informations, consultez Utilisation des API d’un ensemble de conditions requises ultérieure.

⁴ Pour en savoir plus sur les versions minimales prises en charge pour les ensembles d’exigences récents dans Outlook classique sur Windows avec un abonnement Microsoft 365 ou une licence perpétuelle commerciale, consultez Prise en charge des versions pour les ensembles d’exigences dans Outlook classique sur Windows.

⁵ La prise en charge de la nouvelle interface utilisateur Mac est disponible dans Outlook Version 16.38.506. Pour plus d’informations, consultez la section Prise en charge du macro complémentaire dans Outlook sur le nouvel interface d’utilisateur Mac.

⁶ Bien que Outlook classique sur Mac ne prenne pas en charge le jeu de conditions requises Boîte aux lettres 1.9, il prend en charge le jeu de conditions requises DialogAPI 1.2. Pour plus d’informations sur la version et la build minimales prises en charge, consultez Ensembles de conditions requises de l’API de dialogue.

⁷ À l’heure actuelle, d’autres éléments sont à prendre en considération lors de la conception et de la mise en œuvre de compléments pour les clients mobiles. Pour plus d’informations, voir Considérations relatives au code lors de l’ajout de la prise en charge des commandes de complément dans Outlook sur les appareils mobiles. Bien qu’Outlook sur Android et sur iOS prenne en charge jusqu’à l’ensemble d’exigences 1.5, votre complément mobile peut désormais implémenter certaines API à partir d’ensembles d’exigences ultérieurs. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, voir API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.

Prise en charge des versions des jeux d’exigences dans Outlook classique sur Windows

Le tableau suivant répertorie la prise en charge des versions pour les ensembles de besoins de boîte aux lettres plus récents dans Outlook classique sur Windows avec un abonnement Microsoft 365 ou une licence perpétuelle commerciale.

Pour plus d’informations sur la version de votre client, consultez la page de l’historique des mises à jour pour Microsoft 365 ou Office 2024 et comment trouver votre version client Office et le canal de mise à jour.

Référencer la bibliothèque de production de l’API JavaScript Office

Pour utiliser des API dans l’un des ensembles de conditions requises numérotées, vous devez référencer la bibliothèque de productionsur le réseau de distribution de contenu (CDN) Office.js. Pour plus d’informations sur l’utilisation des API en préversion, consultez Tester les API en préversion.

Tester les API en préversion

Les nouvelles API Outlook JavaScript sont d’abord introduites dans la « préversion », puis deviennent partie intégrante d’un ensemble de conditions requises spécifiques numérotées une fois qu’un nombre suffisant de tests a été effectué et que les utilisateurs ont renvoyé des commentaires. Pour formuler des commentaires sur une version d’évaluation API, utilisez le mécanisme de commentaires à la fin de la page web où l’API est documenté.

Pour plus d’informations sur les API de préversion, reportez-vous à l’article relatif à l’ensemble de conditions requises de l’API Outlook de préversion.