Commandes de complément

Les commandes de complément sont des éléments d’interface utilisateur qui étendent l’interface utilisateur d’Office et lancent des actions dans votre complément. Vous pouvez les utiliser pour ajouter un bouton sur le ruban ou un élément dans le menu contextuel. Lorsque les utilisateurs sélectionnent une commande de complément, ils lancent des actions telles que l’exécution de code JavaScript ou l’affichage d’une page du complément dans le volet Office. Les commandes de complément aident les utilisateurs à trouver et utiliser votre complément, ce qui favorise l’adoption et la réutilisation de votre complément, et améliore la fidélisation des clients.

Remarque

• Les catalogues SharePoint ne prennent pas en charge les commandes de complément. Vous pouvez déployer des commandes de complément via les applications intégrées ou AppSource, ou utiliser le chargement indépendant pour déployer votre commande de complément à des fins de test.
• Les compléments de contenu ne prennent actuellement pas en charge les commandes de complément.

Types de commandes de complément

Il existe deux types de commandes de complément en fonction du type d’action déclenchée par la commande.

• Commandes du volet Office : le bouton ou l’élément de menu ouvre le volet Office du complément. Vous ajoutez ce type de commande de complément avec des marques dans le manifeste. Le « code-behind » de la commande est fourni par Office.
• Commandes de fonction : le bouton ou l’élément de menu exécute n’importe quel Code JavaScript arbitraire. Le code appelle presque toujours des API dans la bibliothèque JavaScript Office, mais cela n’est pas nécessaire. Ce type de complément n’affiche généralement aucune autre interface utilisateur que le bouton ou l’élément de menu lui-même. Notez ce qui suit sur les commandes de fonction :
  • La fonction déclenchée peut appeler la méthode displayDialogAsync pour afficher une boîte de dialogue, ce qui est un bon moyen d’afficher une erreur, d’afficher la progression ou d’inviter l’utilisateur à entrer des données. Si le complément est configuré pour utiliser un runtime partagé, la fonction peut également appeler la méthode showAsTaskpane .
  • Le runtime dans lequel la commande de fonction s’exécute est un runtime complet basé sur un navigateur. Il peut afficher un code HTML et appeler Internet pour envoyer ou obtenir des données.

Emplacement des commandes de complément

Lorsqu’un utilisateur installe un complément, l’emplacement de ses commandes dépend de l’application, de la plateforme et du contexte. Les commandes de complément se trouvent dans le ruban, dans un onglet par défaut ou personnalisé, ou dans une barre d’action (s’applique uniquement à certaines plateformes Outlook). Ils apparaissent dans l’interface utilisateur sous la forme d’un bouton ou d’un élément dans un menu déroulant.

Pour les commandes de complément qui s’affichent sur le ruban, si vous utilisez la disposition simplifiée du ruban, le nom du complément est supprimé de la barre de l’application. Seul le bouton de commande du complément dans le ruban est conservé.

À mesure que le ruban ou la barre d’action devient plus encombré, les commandes de complément s’affichent dans le menu de dépassement. Les commandes du même complément sont généralement regroupées.

Excel, PowerPoint et Word

L’onglet par défaut dépend de l’application et du contexte. Pour Excel, PowerPoint et Word, l’onglet par défaut est Accueil.

Outlook

Pour Outlook, l’emplacement par défaut d’une commande de complément est basé sur la plateforme et le mode Outlook actuel. Pour obtenir des conseils, voir Obtenir un complément Office pour Outlook.

Menu déroulant

Une commande de complément de menu déroulant définit une liste statique d’éléments. Les boutons dans le menu peuvent correspondre à n’importe quelle combinaison de boutons qui exécutent une fonction ou qui ouvrent un volet Office. Les sous-menus ne sont pas pris en charge.

Fonctionnalités de commande

Les fonctionnalités de commande suivantes sont actuellement prises en charge.

Points d’extension

• Onglets du ruban : étendez les onglets intégrés ou créez un onglet personnalisé. Un complément ne peut avoir qu’un seul onglet personnalisé.
• Menus contextuels - Permet d’étendre les menus contextuels sélectionnés.

Types de contrôles

• Boutons simples - Permettent de déclencher des actions spécifiques.
• Menus - Menu déroulant simple avec des boutons qui déclenchent des actions.

État Activé ou Désactivé par défaut

Vous pouvez spécifier si la commande est activée ou désactivée lors du lancement de votre complément et modifier le paramètre par programme.

Remarque

Cette fonctionnalité n’est pas prise en charge dans tous les scénarios ou applications Office. Pour plus d’informations, reportez-vous aux Commandes Activé et Désactivé pour les compléments.

Position sur le ruban (aperçu)

Vous pouvez spécifier l’emplacement où s’affiche un onglet personnalisé sur le ruban de l’application Office, par exemple, « juste à droite de l’onglet Accueil ».

Remarque

Cette fonctionnalité n’est pas prise en charge dans tous les scénarios ou applications Office. Pour plus d’informations, voir Positionner un onglet personnalisé sur le ruban.

Intégration des boutons Office intégrés

Vous pouvez insérer les boutons prédéfinis du ruban Office dans vos groupes personnalisés de commandes et votre onglet personnalisé du ruban.

Remarque

Cette fonctionnalité n’est pas prise en charge dans tous les scénarios ou applications Office. Pour plus d’informations, voir Intégrer des boutons prédéfinis Office dans les onglets personnalisés.

Onglets contextuels

Vous pouvez spécifier qu’un onglet n’est visible que dans le ruban dans certains contextes, par exemple lorsque vous sélectionnez un graphique dans Excel.

Remarque

Cette fonctionnalité n’est pas prise en charge dans tous les scénarios ou applications Office. Si vous souhaitez en savoir, veuillez consulter la rubrique Créer des onglets contextuels personnalisés dans des compléments Office.

Plateformes prises en charge

Les commandes de complément sont actuellement prises en charge sur les plateformes suivantes, à l’exception des limitations spécifiées plus haut dans les sous-sections de Fonctionnalités de commande.

• Office on Windows (build 16.0.6769+, connecté à un abonnement Microsoft 365)
• Office sur Mac (build 15.33+, connecté à un abonnement Microsoft 365)
• Office sur le web
• Office 2019 ou version ultérieure sur Windows ou Mac

Remarque

Pour plus d’informations sur la prise en charge dans Outlook, voir notes de support Outlook.

Débogage

Pour déboguer une commande de complément, vous devez l’exécuter dans Office sur le Web. Pour plus de détails, voir Débogage de compléments dans Office sur le web.

Meilleures pratiques

Appliquez les meilleures pratiques suivantes lorsque vous développez des commandes de complément.

• Utilisez les commandes pour représenter une action spécifique avec un résultat clair et précis pour les utilisateurs. Ne combinez pas plusieurs actions dans un seul bouton.

• Proposez des actions détaillées permettant de réaliser plus efficacement des tâches courantes dans votre complément. Réduisez le nombre d’étapes nécessaires à la réalisation d’une action.

• Pour le placement de vos commandes dans le ruban d'application de l'Office :

  • Placez les commandes sur un onglet existant (Insérer, Vérifier, etc.) si la fonctionnalité fournie y est adaptée. Par exemple, si votre complément permet aux utilisateurs d’insérer un média, ajoutez un groupe à l’onglet Insertion. Notez que tous les onglets ne sont pas disponibles dans toutes les versions d’Office. Pour plus d’informations, voir Manifeste des compléments Office.
  • Placez les commandes sous l’onglet Accueil si la fonctionnalité ne correspond à aucun autre onglet, et si vous avez moins de six commandes de niveau supérieur. Vous pouvez également ajouter des commandes à l’onglet Accueil si votre complément doit fonctionner dans plusieurs versions d’Office (par exemple, Office sur le Web ou bureau) et si un onglet n’est pas disponible dans toutes les versions (par exemple, l’onglet Création n’existe pas dans Office sur le Web).
  • Placez des commandes dans un onglet personnalisé si vous avez plus de six commandes de niveau supérieur.
  • Nommez votre groupe en fonction du nom de votre complément. Si vous avez plusieurs groupes, nommez chaque groupe en fonction de la fonctionnalité offerte par les commandes de ce groupe.
  • N’ajoutez pas de boutons inutiles pour augmenter l’espace de votre complément.
  • Ne positionnez pas un onglet personnalisé à gauche de l’onglet Accueil, ni ne lui donnez le focus par défaut lorsque le document s’ouvre, sauf si votre complément est le principal moyen d’interagir avec le document. Donner une importance excessive à votre complément dérange et contrarie les utilisateurs et les administrateurs.
  • Si votre complément est le principal mode d’interaction des utilisateurs avec le document et que vous avez un onglet de ruban personnalisé, envisagez d’intégrer dans l’onglet les boutons de fonctions d’Office dont les utilisateurs ont fréquemment besoin.
  • Si les fonctionnalités fournies avec un onglet personnalisé doivent être disponibles uniquement dans certains contextes, utilisez des onglets contextuels personnalisés. Si vous utilisez des onglets contextuels personnalisés, veillez à implémenter une expérience de secours pour les cas d’utilisation de votre complément sur des plateformes qui ne prennent pas en charge les onglets contextuels personnalisés.

  Remarque

  Les compléments qui occupent trop d’espace peuvent ne pas obtenir la validation d’AppSource.

• Pour toutes les icônes, suivez les règles de conception d’icône.

• Fournissez une version de votre complément qui fonctionne sur les applications ou plateformes Office (comme l’iPad) qui ne prennent pas en charge les commandes. Un manifeste de complément unique peut être utilisé pour ces versions.

Étapes suivantes

La meilleure façon de commencer à utiliser des commandes de complément consiste à consulter des exemples de commandes de complément Office sur GitHub.

Pour plus d’informations sur la spécification de commandes de complément dans un manifeste XML, consultez Créer des commandes de complément avec le manifeste XML et le contenu de référence VersionOverrides .

Pour plus d’informations sur la spécification des commandes de complément dans le manifeste unifié pour Microsoft 365, consultez Créer des commandes de complément avec le manifeste unifié pour Microsoft 365.