Ensembles de conditions requises de l’API JavaScript pour Outlook

Les versions API requises pour les compléments Outlook sont indiquées à l’aide de l’élément Requirements dans leur manifeste. Les compléments Outlook contiennent toujours un élément Set avec un attribut défini sur et un attribut défini sur l’ensemble minimal de conditions requises de l’API qui prend en charge les scénarios du complément.

Par exemple, l’extrait de manifeste suivant indique l’ensemble minimal de conditions requises 1.1.

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

Toutes les API Outlook appartiennent à l’ensemble de conditions requises Mailbox. L’ensemble de conditions requises Mailbox possède plusieurs versions et chaque nouvel ensemble d’API publié appartient à une version plus récente de l’ensemble. L’ensemble d’API le plus récent n’est pas pris en charge par tous les clients Outlook, mais si ce dernier prend en charge un ensemble de conditions requises, toutes les API comprises dans cet ensemble sont également prises en charge. (consultez la documentation sur une API ou une fonctionnalité spécifique pour les exceptions).

La définition d’une version minimale d’ensemble de conditions requises dans le manifeste permet de contrôler les clients Outlook dans lesquels le complément va apparaître. Si un client ne prend pas en charge l’ensemble minimal de conditions requises, il ne charge pas le complément. Par exemple, si la version de l’ensemble de conditions requises spécifiée est 1.3, le complément n’apparaîtra pas dans les clients Outlook qui ne prennent pas en charge au minimum la version 1.3.

Notes

Pour utiliser des API dans l’un des ensembles de conditions requises numérotés, vous devez référencer la bibliothèque de production sur le CDN (https://appsforoffice.microsoft.com/lib/1/hosted/office.js).

Pour plus d’informations sur l’utilisation des API disponibles en préversion, consultez la section Utilisation des API disponibles en préversion plus loin dans cet article.

Utilisation des API d’un ensemble de conditions requises ultérieure

La définition d’un ensemble de conditions requises ne limite pas votre complément à utiliser les API de cette version. Par exemple, si le complément indique l’ensemble de conditions « Boîte aux lettres 1.1 », mais qu’il s’est exécuté dans un client Outlook prenant en charge « Boîte aux lettres 1.3 », le complément peut utiliser les API de l’ensemble de conditions « 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.
}

Important

Il existe actuellement un bogue qui isSetSupported('Mailbox', '1.3') renvoie par erreur true dans Outlook sur le Web par rapport à Exchange 2013. Pour en savoir plus sur les combinaisons prises en charge d'ensembles d'exigences, de serveurs Exchange et de clients Outlook, reportez-vous à Ensembles d'exigences pris en charge par les serveurs Exchange et les clients Outlook.

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

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

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.

Choix d’un ensemble minimal de conditions requises

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.

Important

Si votre serveur Exchange cible et votre client Outlook prennent en charge différents ensembles de conditions requises, vous êtes limité à la plage inférieure d’ensembles de conditions requises. Par exemple, si un complément est exécuté dans Outlook 2016 sur Mac (configuration maximale requise : 1.6) sur Exchange 2013 (ensemble de conditions requises le plus élevé : 1.1), votre complément est limité à l’ensemble de conditions requises 1.1.

Prise en charge par le serveur Exchange

Les serveurs suivants prennent en charge des compléments Outlook.

Produit Version principale d’Exchange Ensembles de conditions requises des API prises en charge
Exchange Online Dernière version 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11
IdentityAPI 1.3*
Exchange local 2019 1.1, 1.2, 1.3, 1.4, 1.5
2016 1.1, 1.2, 1.3, 1.4, 1.5
2013 1.1

Notes

* Pour nécessiter le jeu d'API d'identité 1.3 dans votre code additionnel, vérifiez s'il est pris en charge en appelant isSetSupported('IdentityAPI', '1.3'). Le déclarer dans le manifeste de votre macro complémentaire n'est pas pris 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.

Prise en charge du client Outlook

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

Plateforme Version principale d’Office/Outlook Ensembles de conditions requises des API prises en charge
Windows Abonnement Microsoft 365 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81, 1.91, 1.101, 1.111
IdentityAPI 1.32
2021 achat unique 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81, 1.91
IdentityAPI 1.32
Achat définitif 2019 (au détail) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81
Achat définitif 2019 (licence en volume) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
Achat définitif 2016 1.1, 1.2, 1.3, 1.43
Achat définitif 2013 1.1, 1.2, 1.33, 1.43
Mac interface utilisateur actuelle
(connecté à un abonnement Microsoft 365)
1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
IdentityAPI 1.32
new UI (preview)4
(connecté à un abonnement Microsoft 365)
1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9
IdentityAPI 1.32
2021 achat unique 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
IdentityAPI 1.32
Achat définitif 2019 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
Achat définitif 2016 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
iOS Abonnement Microsoft 365 1.1, 1.2, 1.3, 1.4, 1.55
Android Abonnement Microsoft 365 1.1, 1.2, 1.3, 1.4, 1.55
Navigateur web interface utilisateur moderne d’Outlook lors de sa connexion à
Exchange Online : abonnement à Microsoft 365, Outlook.com
1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11
IdentityAPI 1.32
interface utilisateur classique d’Outlook lors de sa connexion à
Exchange local
1.1, 1.2, 1.3, 1.4, 1.5, 1.6

Notes

1 La prise en charge de la version 1.8 dans Outlook sous Windows avec un abonnement Microsoft 365 ou un achat définitif au détail est disponible depuis la version 1910 (build 12130.20272). La prise en charge de la version 1.9 dans Outlook sous Windows avec un abonnement Microsoft 365 est disponible depuis la version 2008 (build 13127.20296). La prise en charge de la version 1.10 dans Outlook sous Windows avec un abonnement Microsoft 365 est disponible depuis la version 2104 (build 13929.20296). La prise en charge de 1.11 dans Outlook sur Windows avec un abonnement Microsoft 365 est disponible à partir de la version 2110 (build 14527.20226). Pour plus d’informations en fonction de version, consultez la page de l’historique des mises à jour d’Office 2019 ou Microsoft 365 et comment trouver la version client et le canal de mise à jour Office que vous utilisez.

2 Pour nécessiter le jeu d'API d'identité 1.3 dans votre code additionnel, vérifiez s'il est pris en charge en appelant isSetSupported('IdentityAPI', '1.3'). Le déclarer dans le manifeste de votre macro complémentaire n'est pas pris 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.

3 La prise en charge de la version 1.3 dans Outlook 2013 a été ajoutée dans le cadre de la mise à jour du 8 décembre 2015 pour Outlook 2013 (KB3114349). La prise en charge de la version 1.4 dans Outlook 2013 a été ajoutée dans le cadre de la mise à jour du 13 septembre 2016 pour Outlook 2013 (KB3118280). La prise en charge de la version 1.4 dans Outlook 2016 a été ajoutée dans le cadre la mise à jour du 3 juillet 2018 pour Office 2016 (KB4022223).

4 prise en charge de la nouvelle interface utilisateur (préversion) d’Outlook sur Mac est disponible dans la 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.

5 actuellement, d’autres aspects sont à prendre en considération lors de la conception et de l’implémentation de compléments pour les clients mobiles. Par exemple, le seul mode pris en charge est lecture de message. Pour plus d’informations, voir considérations relatives au code lors de l’ajout de la prise en charge des commandes de complément pour lesOutlook Mobile.

Conseil

Vous pouvez faire la distinction entre les deux versions d’Outlook, classique et moderne, dans un navigateur Web en regardant la barre d’outils de votre boîte aux lettres.

moderne

Capture d'écran partielle de la barre d'outils moderne d' Outlook.

classique

Capture d’écran partielle de la barre d’outils Outlook classique.

Utilisation des API de 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é.

Notes

L’aperçu API peut être modifiés et n’est pas destinés à utiliser dans un environnement de production.

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.