Spécifier les applications Office et les exigences de l’API

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 l’API JavaScript Office (office.js). Par exemple, votre complément peut :

• Exécuter dans une application Office (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 d’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 est en cours d’exécution dans Word.
• Votre complément dispose d’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 qui n’est pas prise en charge dans d’autres, comme Excel 2016 perpétuel sous licence en volume. Toutefois, votre complément a d’autres fonctionnalités qui nécessitent uniquement des méthodes d’API JavaScript Office prises en charge dans Excel 2016 perpétuel sous licence en volume. Dans ce scénario, vous avez besoin que le complément soit installable sur cette version d’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.

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/ 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.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 de 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 dans un sous-ensemble d’applications Office, utilisez les éléments Hosts et Host dans le manifeste.

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, 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.

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.

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 antérieures à 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.

API non dans un ensemble de conditions requises

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. Il existe également un moyen de spécifier l’une de ces API sans définition dans le manifeste lorsque votre complément en a besoin. Cet article contient d’autres détails plus avant.

Élément Requirements

Utilisez l’élément Requirements et ses éléments enfants Sets and Methods pour spécifier les ensembles de conditions requises minimales ou les membres d’API qui doivent être pris en charge par l’application Office pour installer votre complément.

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.

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 :

• Pour connaître les fonctionnalités implémentées entièrement avec JavaScript, consultez Vérifications d’exécution pour la prise en charge des méthodes et des ensembles de conditions requises.
• Pour connaître les fonctionnalités qui nécessitent la configuration d’un <élément VersionOverrides> , consultez Spécification des exigences dans un élément VersionOverrides.

Vérifications du runtime pour la prise en charge des méthodes et des ensembles de conditions requises

Vous effectuez un test au moment de l’exécution pour découvrir si l’office de l’utilisateur prend en charge un ensemble de conditions requises avec la méthode isSetSupported . Transmettez le nom de l’ensemble de conditions requises et la version minimale en tant que paramètres. Si l’ensemble de conditions requises est pris en charge, isSetSupported retourne true. Le code ci-dessous vous montre un exemple.

if (Office.context.requirements.isSetSupported('WordApi', '1.2'))
{
   // Code that uses API members from the WordApi 1.2 requirement set.
} else {
   // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2).
}

Tenez compte du code suivant :

• Le premier paramètre est obligatoire. Il s’agit d’une chaîne qui représente le nom de l’ensemble de conditions requises. Pour plus d’informations concernant les ensembles de conditions requises disponibles, voir Ensembles de conditions requises pour complément Office.
• Le deuxième paramètre est facultatif. Il s’agit d’une chaîne qui spécifie la version minimale de l’ensemble de conditions requises que l’application Office doit prendre en charge pour que le code dans l’instruction if s’exécute (par exemple, « 1.9 »). Si elle n’est pas utilisée, la version « 1.1 » est supposée.

Le tableau suivant présente les noms des ensembles de conditions requises pour les modèles d’API spécifiques à l’application.

Voici un exemple d’utilisation de la méthode avec l’un des ensembles de conditions requises du modèle d’API commun.

if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set.
}

Lorsque votre complément dépend d’une méthode qui ne fait pas partie d’un ensemble de conditions requises, utilisez la vérification du runtime pour déterminer si la méthode est prise en charge par l’application Office, comme illustré dans l’exemple de code suivant. Pour consulter la liste complète des méthodes qui n’appartiennent pas à un ensemble de conditions requises, voir Ensemble de conditions requises pour les compléments Office.

L’exemple de code suivant vérifie si l’application Office prend en charge document.setSelectedDataAsync.

if (Office.context.document.setSelectedDataAsync)
{
    // Run code that uses `document.setSelectedDataAsync`.
}

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>

Voir aussi

• Manifeste des compléments Office
• Ensembles de conditions requises pour les compléments Office
• Word-Add-in-Get-Set-EditOpen-XML