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

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écuter dans une seule application Office (par exemple, Word ou Excel) ou dans plusieurs applications.
• Utiliser les API JavaScript d’Office qui ne sont disponibles que dans certaines versions d’Office. Par exemple, la version perpétuelle sous licence en volume d’Excel 2016 ne prend pas en charge toutes les API liées à Excel dans la bibliothèque JavaScript Office.

Dans ce cas, vous devez vous assurer que votre complément n’est jamais installé sur les applications 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. En voici deux exemples :

• Votre complément possède des fonctionnalités utiles dans Word et PowerPoint, telles que la manipulation de texte, mais il comporte également des 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 possède une fonctionnalité qui nécessite une méthode d’API JavaScript Office qui est prise en charge dans certaines versions d’une application Office, par exemple l’abonnement Microsoft 365 Excel, mais qui n’est pas prise en charge dans d’autres, comme Excel 2016 perpétuel avec licence en volume. Toutefois, votre complément comporte d’autres fonctionnalités qui ne nécessitent que les méthodes de l’API JavaScript Office prises en charge dans Excel 2016 perpétuel sous licence en volume. Dans ce scénario, vous devez que le complément puisse être installé sur cette version d’Excel 2016, mais la fonctionnalité qui nécessite la méthode non prise en charge doit être cachée à 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.

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, assurez-vous que vous avez la balise suivante <script> dans le premier fichier HTML ouvert par votre complément. L’utilisation de /1/ dans l’URL CDN garantit que vous référencez la version d’Office.js la plus récente.

<script src="https://officeapis.public.onecdn.static.microsoft/1/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é (à savoir Courrier, Volet des tâches ou Contenu). Par exemple, un complément volet Office peut être installé par défaut sur Access, Excel, OneNote, PowerPoint, Project et Word.

Pour garantir que votre complément peut être installé dans un sous-ensemble d’applications Office uniquement, utilisez les hôtes et les éléments hôte dans le manifeste du complément uniquement.

Par exemple, la déclaration suivante <Hosts> spécifie <Host> que le complément peut être installé sur n’importe quelle version d’Excel, y compris Excel sur le web, Windows et iPad, mais ne peut être installé sur aucune autre application Office.

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

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

Spécifier les versions et les 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. Vous ne le souhaiteriez pas, car vous devriez réviser votre manifeste chaque fois que la prise en charge des fonctionnalités du complément que votre complément utilise est étendue à une nouvelle version ou plateforme. Indiquez plutôt dans le manifeste les API dont votre complément a besoin. Office empêche l’installation du complément sur une combinaison 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.

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 besoins. Les API du modèle objet API commun sont regroupées en fonction de la fonctionnalité de développement qu’elles prennent en charge. Par exemple, toutes les API connectées à des liaisons de table figurent dans l’ensemble de conditions requises appelé « TableBindings 1.1 ». Les API des modèles objets spécifiques à l’application sont regroupées par date de publication pour être utilisées dans des compléments de production.

Les ensembles de conditions requises sont versionnés. Par exemple, les API qui prennent en charge les boîtes de dialogue figurent dans l’ensemble de conditions requises DialogApi 1.1. Lorsque des API supplémentaires qui permettent d’envoyer la messagerie d’un volet Office à une boîte de dialogue ont été publiées, elles ont été regroupées dans DialogApi 1.2, avec toutes les API de 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 des ensembles 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, ExcelApi 1.17 n’est pas pris en charge sur les versions perpétuelles d’Office sous licence en volume antérieures à Office 2024, mais ExcelApi 1.14 est pris en charge jusqu’à Office 2021. Vous souhaitez que votre complément puisse être installé sur toutes les versions d’Office et de plateforme qui prennent en charge les API qu’il utilise. Vous devez donc toujours spécifier dans le manifeste la version minimale de chaque jeu de conditions requises requises par votre complément. Plus de détails sur la procédure à suivre sont disponibles plus loin dans cet article.

Élément Requirements

Utilisez l’élément Requirements et son élément enfant Sets pour spécifier la configuration minimale requise Sets 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 figurent dans des ensembles d’exigences, mais certaines de celles du modèle d’API commun ne le sont pas. Utilisez les méthodes pour spécifier les membres d’API setless requis par votre complément. Vous ne pouvez pas utiliser l’élément avec des <Methods> 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écutera pas dans cette application ou plateforme et ne s’affichera pas dans Mes compléments.

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

• TableBindings défini de configuration requise avec une version minimale de « 1.1 ».
• OoxmlCoercion défini de configuration requise avec une version minimale de « 1.1 ».
• Document.getSelectedDataAsync méthode.

<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OoxmlCoercion" 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 et <Methods> enfant<Sets>.
• L’élément <Sets> peut contenir un ou plusieurs <Set> éléments. DefaultMinVersion Spécifie la valeur par défaut MinVersion de tous les éléments enfants <Set> .
• 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 besoins. Spécifie MinVersion la version minimale de l’ensemble des exigences. MinVersion Remplace la valeur de l’attribut DefaultMinVersion dans le fichier parent <Sets>.
• L’élément <Methods> peut contenir un ou plusieurs éléments Method . Vous ne pouvez pas utiliser l’élément avec des <Methods> 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é offertes par la plateforme des compléments Office peuvent être utilement divisées en trois types :

• Fonctionnalités d’extensibilité qui sont 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é.
• Les 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, les boîtes de dialogue.
• Fonctionnalités d’extensibilité qui ne sont disponibles qu’au moment de l’exécution, mais qui sont implémentées avec une combinaison de Office.js JavaScript et de configuration dans un <VersionOverrides> élément. Il s’agit par exemple des fonctions personnaliséesd’Excel, de l’authentification unique et des onglets contextuels personnalisés.

Si votre complément utilise une fonctionnalité d’extensibilité spécifique pour certaines de ses fonctionnalités, mais qu’il dispose d’autres fonctionnalités utiles qui ne nécessitent pas la fonctionnalité d’extensibilité, vous devez concevoir le complément de manière à ce qu’il puisse être installé sur des combinaisons de plates-formes et de versions d’Office qui ne prennent pas en charge la fonctionnalité d’extensibilité. Cela peut fournir une expérience précieuse, bien que diminuée, sur ces combinaisons.

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

• Pour les fonctionnalités implémentées entièrement avec JavaScript, consultez Vérifier la disponibilité de l’API au moment de l’exécution.
• Pour les fonctionnalités qui nécessitent la configuration d’un <VersionOverrides> élément, consultez Spécification des exigences dans un élément VersionOverrides

Spécifier les conditions requises dans un élément VersionOverrides

L’élément VersionOverrides a été ajouté au schéma du 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 de ruban et menus 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 qu’il est utile et qu’il soit installable, même sur les versions d’Office qui ne le prennent pas en charge. Dans ce scénario, identifiez la fonctionnalité à l’aide d’un élément d’exigences (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 . En effet, Office autorise l’installation du complément, mais 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 de qui remplacent les <VersionOverrides> éléments dans le manifeste de base, tels qu’un <Hosts> élément, 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 un <VersionOverrides> qui implémentent réellement des fonctionnalités supplémentaires plutôt que de remplacer les paramètres du manifeste de base. Deux exemples sont les modèles et WebApplicationInfoEquivalentAddins. Ces parties du <VersionOverrides> ne seront pas ignorées, pour autant 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 la section Élément Conditions requises 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>

Voir aussi

• Manifeste des compléments Office
• Ensembles de conditions requises pour les compléments Office
• Exemples de compléments Office