Partager via

Spécifier les applications Office et les exigences de l’API avec le manifeste du complément uniquement

  • Article

Remarque

Pour plus d’informations sur la spécification des exigences avec le manifeste unifié pour Microsoft 365, voir Spécifier les hôtes Office et les exigences d’API avec le manifeste unifié.

Votre complément Office peut dépendre d’une application Office spécifique (également appelée hôte Office) ou de membres spécifiques de la bibliothèque JavaScript Office (office.js). Par exemple, votre complément peut :

  • Exécutez dans une seule application Office (par exemple, Word ou Excel) ou plusieurs applications.
  • Utilisez les API JavaScript Office qui ne sont disponibles que dans certaines versions d’Office. Par exemple, la version perpétuelle sous licence en volume de Excel 2016 ne prend pas en charge toutes les API liées à Excel dans la bibliothèque JavaScript Office.

Dans ces situations, vous devez vous assurer que votre complément n’est jamais installé sur les applications Office ou les versions d’Office dans lesquelles il ne peut pas s’exécuter.

Il existe également des scénarios dans lesquels vous souhaitez contrôler les fonctionnalités de votre complément qui sont visibles par les utilisateurs en fonction de leur application Office et de leur version d’Office. Voici deux exemples :

  • Votre complément a des fonctionnalités utiles dans Word et PowerPoint, telles que la manipulation de texte, mais il dispose de certaines fonctionnalités supplémentaires qui n’ont de sens que dans PowerPoint, telles que les fonctionnalités de gestion des diapositives. Vous devez masquer les fonctionnalités PowerPoint uniquement lorsque le complément s’exécute dans Word.
  • Votre complément a une fonctionnalité qui nécessite une méthode d’API JavaScript Office qui est prise en charge dans certaines versions d’une application Office, comme l’abonnement Microsoft 365 Excel, mais n’est pas prise en charge dans d’autres, telles que les Excel 2016 perpétuels sous licence en volume. Toutefois, votre complément dispose d’autres fonctionnalités qui nécessitent uniquement des méthodes d’API JavaScript Office prises en charge dans les Excel 2016 perpétuels sous licence en volume. Dans ce scénario, vous avez besoin que le complément soit installable sur cette version de Excel 2016, mais la fonctionnalité qui nécessite la méthode non prise en charge doit être masquée pour ces utilisateurs.

Cet article vous aidera à comprendre les options que vous devez choisir afin de vous assurer que votre complément fonctionne comme prévu et atteint l’audience la plus large possible.

Remarque

Pour obtenir une vue d’ensemble de l’emplacement où les compléments Office sont actuellement pris en charge, consultez la page Disponibilité des applications clientes et des plateformes Office pour les compléments Office .

Conseil

La plupart des tâches décrites dans cet article sont effectuées pour vous, en tout ou en partie, lorsque vous créez votre projet de complément avec un outil, tel que le générateur Yeoman pour les compléments Office ou l’un des modèles de complément Office dans Visual Studio. Dans ce cas, interprétez la tâche comme signifiant que vous devez vérifier qu’elle a été effectuée.

Utiliser la dernière bibliothèque d’API JavaScript Office

Votre complément doit charger la version la plus récente de la bibliothèque d’API JavaScript Office à partir du réseau de distribution de contenu (CDN). Pour ce faire, vérifiez que vous avez la balise suivante <script> dans le premier fichier HTML que votre complément ouvre. L’utilisation de /1.1/ dans l’URL CDN garantit que vous référencez la version d’Office.js la plus récente.

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

Spécifier les applications Office qui peuvent héberger votre complément

Par défaut, un complément peut être installé dans toutes les applications Office prises en charge par le type de complément spécifié (autrement dit, Courrier, Volet Office ou Contenu). Par exemple, un complément du volet Office peut être installé par défaut sur Access, Excel, OneNote, PowerPoint, Project et Word.

Pour vous assurer que votre complément est installable uniquement dans un sous-ensemble d’applications Office, utilisez les éléments Hosts et Host dans le manifeste du complément uniquement.

Par exemple, la déclaration Hosts> et Host suivante< spécifie que le complément peut s’installer sur n’importe quelle version d’Excel, ce qui inclut Excel sur le Web, Windows et iPad, mais ne peut pas être installé sur une autre application Office.><

<Hosts>
  <Host Name="Workbook" />
</Hosts>

L’élément <Hosts> peut contenir un ou plusieurs <éléments Host> . Il doit y avoir un élément Host> distinct< pour chaque application Office sur laquelle le complément doit être installable. L’attribut Name est obligatoire et peut être défini sur l’une des valeurs suivantes.

Nom Applications clientes Office Types de compléments disponibles
Document Word sur le web, Windows, Mac, iPad Volet de tâches
Boîte aux lettres Outlook sur le web, Windows (nouveau et classique), Mac, Android, iOS Courrier
Bloc-notes OneNote sur le web Volet Office, Contenu
Présentation PowerPoint sur le web, Windows, Mac, iPad Volet Office, Contenu
Project Project sur Windows Volet de tâches
Classeur Excel sur le Web, Windows, Mac, iPad Volet Office, Contenu
Database Access (obsolète) Volet de tâches

Remarque

Les applications Office sont prises en charge sur différentes plateformes et s’exécutent sur des ordinateurs de bureau, des navigateurs web, des tablettes et des appareils mobiles. En règle générale, vous ne pouvez pas spécifier quelle plateforme peut être utilisée pour exécuter votre complément. Par exemple, si vous spécifiez Workbook, Excel sur le Web et sur Windows peuvent être utilisés pour exécuter votre complément. Toutefois, si vous spécifiez Mailbox, votre complément ne s’exécutera pas sur les clients mobiles Outlook, sauf si vous définissez le point d’extension mobile.

Remarque

Il n’est pas possible qu’un manifeste de complément s’applique uniquement à plusieurs types : Courrier, Volet Office ou Contenu. Cela signifie que si vous souhaitez que votre complément soit installable sur Outlook et sur l’une des autres applications Office, vous devez créer deux compléments, l’un avec un manifeste de type Courrier et l’autre avec un manifeste de type Office ou contenu.

Spécifier les versions et plateformes d’Office qui peuvent héberger votre complément

Vous ne pouvez pas spécifier explicitement les versions et builds d’Office ou les plateformes sur lesquelles votre complément doit être installable, et vous ne souhaitez pas le faire, car vous devrez réviser votre manifeste chaque fois que la prise en charge des fonctionnalités de complément que votre complément utilise est étendue à une nouvelle version ou plateforme. Au lieu de cela, spécifiez dans le manifeste les API dont votre complément a besoin. Office empêche l’installation du complément sur des combinaisons de version et de plateforme Office qui ne prennent pas en charge les API et garantit que le complément n’apparaîtra pas dans Mes compléments.

Importante

Utilisez uniquement le manifeste de base pour spécifier les membres d’API dont votre complément doit avoir une valeur significative. Si votre complément utilise une API pour certaines fonctionnalités, mais possède d’autres fonctionnalités utiles qui ne nécessitent pas l’API, vous devez concevoir le complément afin qu’il puisse être installé sur des combinaisons de plateformes et de versions Office qui ne prennent pas en charge l’API, mais qui offrent une expérience réduite sur ces combinaisons. Pour plus d’informations, consultez Concevoir pour d’autres expériences.

Ensembles de conditions requises

Pour simplifier le processus de spécification des API dont votre complément a besoin, Office regroupe la plupart des API dans des ensembles de conditions requises. Les API du modèle objet d’API commune sont regroupées par la fonctionnalité de développement qu’elles prennent en charge. Par exemple, toutes les API connectées aux liaisons de table se trouvent dans l’ensemble de conditions requises appelé « TableBindings 1.1 ». Les API dans les modèles objet spécifiques à l’application sont regroupées par quand elles ont été publiées pour être utilisées dans les compléments de production.

Les ensembles de conditions requises sont avec version. Par exemple, les API qui prennent en charge les boîtes de dialogue se trouvent dans l’ensemble de conditions requises DialogApi 1.1. Lorsque des API supplémentaires qui activent la messagerie à partir d’un volet Office vers un dialogue ont été libérées, elles ont été regroupées dans DialogApi 1.2, ainsi que toutes les API dans DialogApi 1.1. Chaque version d’un ensemble de conditions requises est un sur-ensemble de toutes les versions antérieures.

La prise en charge de l’ensemble de conditions requises varie selon l’application Office, la version de l’application Office et la plateforme sur laquelle elle s’exécute. Par exemple, DialogApi 1.2 n’est pas pris en charge sur les versions perpétuelles sous licence en volume d’Office avant Office 2021, mais DialogApi 1.1 est pris en charge sur toutes les versions perpétuelles d’Office 2016. Vous souhaitez que votre complément soit installable sur chaque combinaison de plateforme et de version d’Office qui prend en charge les API qu’il utilise. Vous devez donc toujours spécifier dans le manifeste la version minimale de chaque ensemble de conditions requises par votre complément. Vous trouverez plus d’informations sur la procédure à suivre plus loin dans cet article.

Conseil

Pour plus d’informations sur le contrôle de version des ensembles de conditions requises, consultez Disponibilité des ensembles de conditions requises Office et pour obtenir la liste complète des ensembles de conditions requises et des informations sur les API dans chacun d’eux, commencez par les ensembles de conditions requises des compléments Office. Les rubriques de référence pour la plupart des API Office.js spécifient également l’ensemble de conditions requises auxquelles elles appartiennent (le cas échéant).

Remarque

Certains ensembles de conditions requises sont également associés à des éléments de manifeste. Pour plus d’informations sur le moment où ce fait est pertinent pour la conception de votre complément, consultez Spécification des exigences dans un élément VersionOverrides .

Élément Requirements

Utilisez l’élément Requirements et son élément enfant Sets pour spécifier les ensembles de conditions requises minimales qui doivent être pris en charge par l’application Office pour installer votre complément.

Toutes les API des modèles spécifiques à l’application se trouvent dans des ensembles de conditions requises, mais certaines d’entre elles dans le modèle d’API commun ne le sont pas. Utilisez les méthodes pour spécifier les membres d’API sans définition dont votre complément a besoin. Vous ne pouvez pas utiliser l’élément <Methods> avec les compléments Outlook.

Si l’application ou la plateforme Office ne prend pas en charge les ensembles de conditions requises ou les membres d’API spécifiés dans l’élément <Requirements> , le complément ne s’exécute pas dans cette application ou cette plateforme et ne s’affiche pas dans Mes compléments.

Remarque

L’élément <Requirements> est facultatif pour tous les compléments, à l’exception des compléments Outlook. Lorsque l’attribut xsi:type de l’élément racine OfficeApp est MailApp, il doit y avoir un <élément Requirements> qui spécifie la version minimale de l’ensemble de conditions requises mailbox requise par le complément. Pour plus d’informations, consultez Ensembles de conditions requises de l’API JavaScript Outlook.

L’exemple de code suivant montre comment configurer un complément installable dans toutes les applications Office qui prennent en charge les éléments suivants :

  • TableBindings ensemble de conditions requises, qui a une version minimale de « 1.1 ».
  • OOXML ensemble de conditions requises, qui a une version minimale de « 1.1 ».
  • Document.getSelectedDataAsync méthode.
<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OOXML" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Notez ce qui suit à propos de cet exemple.

  • L’élément <Requirements> contient les <éléments enfants Sets> et <Methods> .
  • L’élément <Sets> peut contenir un ou plusieurs <éléments Set> . DefaultMinVersionspécifie la valeur par défaut MinVersion de tous les éléments Set> enfants<.
  • Un élément Set spécifie un ensemble de conditions requises que l’application Office doit prendre en charge pour rendre le complément installable. L’attribut Name spécifie le nom de l’ensemble de conditions requises. spécifie MinVersion la version minimale de l’ensemble de conditions requises. MinVersionremplace la valeur de l’attribut DefaultMinVersion dans les jeux> parents<.
  • L’élément <Methods> peut contenir un ou plusieurs éléments Method . Vous ne pouvez pas utiliser l’élément <Methods> avec les compléments Outlook.
  • L’élément< Method> spécifie une méthode individuelle que l’application Office doit prendre en charge pour rendre le complément installable. L’attribut Name est obligatoire et spécifie le nom de la méthode qualifiée avec son objet parent.

Concevoir pour d’autres expériences

Les fonctionnalités d’extensibilité fournies par la plateforme de complément Office peuvent être divisées en trois types :

  • Fonctionnalités d’extensibilité disponibles immédiatement après l’installation du complément. Vous pouvez utiliser ce type de fonctionnalité en configurant un élément VersionOverrides dans le manifeste. Les commandes de complément, qui sont des boutons et des menus personnalisés du ruban, sont un exemple de ce type de fonctionnalité.
  • Fonctionnalités d’extensibilité qui sont disponibles uniquement lorsque le complément est en cours d’exécution et qui sont implémentées avec Office.js API JavaScript ; par exemple, boîtes de dialogue.
  • Fonctionnalités d’extensibilité disponibles uniquement au moment de l’exécution, mais implémentées avec une combinaison de Office.js JavaScript et de configuration dans un <élément VersionOverrides> . Les fonctions personnalisées Excel, l’authentification unique et les onglets contextuels personnalisés en sont des exemples.

Si votre complément utilise une fonctionnalité d’extensibilité spécifique pour certaines de ses fonctionnalités, mais qu’il a d’autres fonctionnalités utiles qui ne nécessitent pas la fonctionnalité d’extensibilité, vous devez concevoir le complément afin qu’il soit installable sur des combinaisons de versions de plateforme et d’Office qui ne prennent pas en charge la fonctionnalité d’extensibilité. Il peut fournir une expérience précieuse, bien que réduite, sur ces combinaisons.

Vous implémentez cette conception différemment en fonction de la façon dont la fonctionnalité d’extensibilité est implémentée :

Spécifier la configuration requise dans un élément VersionOverrides

L’élément VersionOverrides a été ajouté au schéma de manifeste principalement, mais pas exclusivement, pour prendre en charge les fonctionnalités qui doivent être disponibles immédiatement après l’installation d’un complément, telles que les commandes de complément (boutons et menus du ruban personnalisés). Office doit connaître ces fonctionnalités lorsqu’il analyse le manifeste du complément.

Supposons que votre complément utilise l’une de ces fonctionnalités, mais le complément est précieux et doit être installable, même sur les versions d’Office qui ne prennent pas en charge la fonctionnalité. Dans ce scénario, identifiez la fonctionnalité à l’aide d’un élément Requirements (et de ses éléments enfants Sets et Methods ) que vous incluez en tant qu’enfant de l’élément <VersionOverrides> lui-même plutôt qu’en tant qu’enfant de l’élément de base OfficeApp . Cela a pour effet qu’Office autorise l’installation du complément, mais Office ignore certains des éléments enfants de l’élément <VersionOverrides sur les> versions d’Office où la fonctionnalité n’est pas prise en charge.

Plus précisément, les éléments enfants des <VersionsOverrides qui remplacent les> éléments du manifeste de base, tels qu’un <élément Hosts> , sont ignorés et les éléments correspondants du manifeste de base sont utilisés à la place. Toutefois, il peut y avoir des éléments enfants dans versionOverrides<> qui implémentent des fonctionnalités supplémentaires plutôt que de remplacer des paramètres dans le manifeste de base. Deux exemples sont les WebApplicationInfo et EquivalentAddins. Ces parties de <VersionOverrides> ne seront pas ignorées, en supposant que la plateforme et la version d’Office prennent en charge la fonctionnalité correspondante.

Pour plus d’informations sur les éléments descendants de l’élément <Requirements> , consultez l’élément Requirements plus haut dans cet article.

Voici un exemple.

<VersionOverrides ... >
   ...
   <Requirements>
      <Sets DefaultMinVersion="1.1">
         <Set Name="WordApi" MinVersion="1.2"/>
      </Sets>
   </Requirements>
   <Hosts>

      <!-- ALL MARKUP INSIDE THE HOSTS ELEMENT IS IGNORED WHEREVER WordApi 1.2 IS NOT SUPPORTED -->

      <Host xsi:type="Workbook">
         <!-- markup for custom add-in commands -->
      </Host>
   </Hosts>
</VersionOverrides>

Avertissement

Si votre complément inclut des commandes de complément, faites attention avant d’inclure un <élément Requirements> dans versionOverrides<>. Sur les combinaisons de plateforme et de version qui ne prennent pas en charge la configuration requise, aucune commande de complément n’est installée, même celles qui appellent des fonctionnalités qui n’en ont pas besoin. Prenons l’exemple d’un complément doté de deux boutons de ruban personnalisés. L’un d’eux appelle les API JavaScript Office disponibles dans l’ensemble de conditions requises ExcelApi 1.4 (et versions ultérieures). L’autre appelle des API qui ne sont disponibles que dans ExcelApi 1.9 (et versions ultérieures). Si vous placez une exigence pour ExcelApi 1.9 dans VersionOverrides<>, lorsque la version 1.9 n’est pas prise en charge, aucun des boutons n’apparaît sur le ruban. Une meilleure stratégie dans ce scénario consiste à utiliser la technique décrite dans Vérifier la disponibilité de l’API au moment de l’exécution. Le code appelé par le deuxième bouton utilise isSetSupported d’abord pour case activée pour la prise en charge d’ExcelApi 1.9. S’il n’est pas pris en charge, le code fournit à l’utilisateur un message indiquant que cette fonctionnalité du complément n’est pas disponible sur sa version d’Office.

Conseil

Il est inutile de répéter un <élément Requirement> dans un <VersionOverrides> qui apparaît déjà dans le manifeste de base. Si la condition requise est spécifiée dans le manifeste de base, le complément ne peut pas s’installer là où la condition requise n’est pas prise en charge, de sorte qu’Office n’analyse même pas l’élément <VersionOverrides> .

Voir aussi