Partager via

Spécifier les applications Office et les exigences d’API avec le manifeste unifié

  • Article

Remarque

Pour plus d’informations sur la spécification des exigences avec le manifeste de complément uniquement, consultez Spécifier les hôtes Office et les exigences d’API avec le manifeste de 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 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 de Excel 2016 ne prend pas en charge toutes les API liées à Excel dans la bibliothèque JavaScript Office.
  • Être conçu pour une utilisation uniquement dans un facteur de forme mobile.

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 trois 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 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, 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.
  • Votre complément dispose de fonctionnalités prises en charge dans Office de bureau, mais pas dans Office mobile.

Cet article vous aide à comprendre comment vous assurer que votre complément fonctionne comme prévu et atteint le public le 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.1/hosted/office.js" type="text/javascript"></script>

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

Pour spécifier les applications Office sur lesquelles votre complément peut être installé, utilisez le tableau « extensions.requirements.scopes ». Spécifiez n’importe quel sous-ensemble de « mail », « workbook », « document » et « presentation ». Le tableau suivant indique les combinaisons d’applications et de plateformes Office qui correspondent à ces valeurs. Il montre également quel type de complément peut être installé pour chaque étendue.

Nom Applications clientes Office Types de compléments disponibles
document Word sur le web, Windows, Mac, iPad Volet de tâches
mail Outlook sur le web, Windows (nouveau et classique), Android, iOS Courrier
présentation PowerPoint sur le web, Windows, Mac, iPad Volet Office, Contenu
workbook Excel sur le Web, Windows, Mac, iPad Volet Office, Contenu

Remarque

Les compléments de contenu ont une propriété « extensions.contentRuntimes ». Ils ne peuvent pas avoir de propriété « extensions.runtimes » et ne peuvent donc pas être combinés avec un complément volet Office ou Courrier. Pour plus d’informations sur les compléments de contenu, voir Compléments Office de contenu.

Par exemple, le code JSON suivant 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 qu’il ne peut pas être installé sur une autre application Office.

"extensions": [
    {
        "requirements": {
            "scopes": [ "workbook" ],
        },
        ...
    }
]

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 « courrier », votre complément ne s’exécutera pas sur les clients mobiles Outlook, sauf si vous définissez le point d’extension mobile.

Spécifier les API Office dont votre complément a besoin

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 la propriété « requirements » qui est un enfant direct de « extensions » 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 soit installable 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. À cet effet, utilisez les propriétés « requirements » qui ne sont pas des enfants directs de « extensions ». 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).

propriété extensions.requirements.capabilities

Utilisez la propriété « requirements.capabilities » pour spécifier les ensembles de conditions requises minimales 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 la propriété « requirements.capabilities », le complément ne s’exécute pas dans cette application ou cette plateforme et ne s’affiche pas dans Mes compléments.

Conseil

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. Si votre complément nécessite une API qui ne figure dans aucun ensemble de conditions requises, vous pouvez implémenter un case activée d’exécution pour la disponibilité de l’API et afficher un message aux utilisateurs du complément s’il n’est pas pris en charge. Pour plus d’informations, consultez Vérifier la disponibilité de l’API au moment de l’exécution.

L’exemple de code suivant montre comment configurer un complément qui peut être installé dans toutes les combinaisons d’applications et de plateformes 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 ».
"extensions": [
    {
        "requirements": {
            "capabilities": [ 
                {
                    "name": "TableBindings",
                    "minVersion": "1.1"
                },
                {
                    "name": "OOXML",
                    "minVersion": "1.1"
                }
            ],
        },
        ...
    }
]

Conseil

Pour plus d’informations et un autre exemple d’utilisation de la propriété « extensions.requirements », consultez la section « extensions.requirements » dans Spécifier les exigences de complément Office dans le manifeste unifié pour Microsoft 365.

Spécifier les facteurs de forme sur lesquels votre complément peut être installé

Pour un complément Outlook, vous pouvez spécifier si le complément doit être installable sur un ordinateur de bureau (y compris des tablettes) ou sur des facteurs de forme mobiles. Pour configurer cela, utilisez la propriété « extensions.requirements.formFactors ». L’exemple suivant montre comment rendre le complément Outlook installable sur les deux facteurs de forme.

"extensions": [
    {
        "requirements": {
            ...
            "formFactors": [
                "desktop",
                "mobile"
            ]
        },
        ...
    }
]

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. 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é qui sont disponibles uniquement au moment de l’exécution, mais qui sont implémentées avec une combinaison de Office.js configuration JavaScript et manifeste. 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 :

Voir aussi