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 le portail des applications intégrées ou la Place de marché Microsoft, 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 :

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

  • Le runtime se ferme lorsque la fonction se termine ou que 5 minutes se sont écoulées, selon la valeur antérieure.

  • La fonction déclenchée peut appeler la méthode displayDialogAsync pour afficher une boîte de dialogue. Il s’agit d’un bon moyen d’afficher une erreur, d’afficher la progression ou d’inviter l’utilisateur à entrer une entrée.

    Remarque

    En raison du délai d’expiration de 5 minutes, la boîte de dialogue doit être conçue de sorte que les utilisateurs terminent leur interaction et la ferment dans les 5 minutes. Votre complément doit utiliser un volet Office pour des interactions plus longues.

  • Si le complément est configuré pour utiliser un runtime partagé, la fonction peut également appeler la méthode showAsTaskpane .

  Conseil

  Les commandes de fonction ne sont pas la seule façon d’exécuter du code JavaScript arbitraire dans un complément. Un complément peut également inclure :

  • Gestionnaires personnalisés pour certains événements, tels qu’un utilisateur ouvrant un nouveau volet de messages dans Outlook.
  • Agents Copilot personnalisés qui effectuent des actions en réponse aux demandes en langage naturel des utilisateurs du complément.

Emplacement des commandes de complément

Lorsqu’un utilisateur installe un complément, les commandes du complément se trouvent dans le ruban, dans un onglet Office intégré ou un onglet personnalisé spécifié dans le manifeste. (Vous pouvez également placer des commandes de complément dans un onglet contextuel personnalisé que votre code de complément définit lors de l’exécution.) Ils apparaissent dans l’interface utilisateur sous la forme d’un bouton ou d’un élément dans un menu déroulant.

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

Dans Office sur le Web, si vous utilisez la disposition à ligne unique ou simplifiée du ruban, le nom du complément n’est pas affiché sur le ruban. Seule l’icône de commande du complément s’affiche.

Excel, PowerPoint et Word

L’exemple suivant montre un exemple de commandes de complément dans un groupe personnalisé sous l’onglet Données du ruban Excel.

Outlook

Pour Outlook, lorsque vous souhaitez une commande de complément sur un onglet du ruban intégré, plutôt que de créer la vôtre, la commande s’affiche sous l’onglet par défaut en fonction de la plateforme et du mode Outlook actuel. Pour obtenir des conseils, voir Utiliser des compléments dans 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.

Commandes de complément groupées sur le ruban

Plusieurs commandes de complément peuvent être regroupées sur le ruban. Un groupe doit contenir au moins une commande de complément sous la forme d’un bouton ou d’un menu déroulant. Dans Office sur Windows et sur Mac, l’étiquette et l’icône d’un bouton ou d’un menu déroulant sont généralement affichées pour les commandes de complément dans un groupe. Toutefois, la taille de l’icône et la visibilité de l’étiquette peuvent varier en raison des facteurs suivants qui limitent l’espace.

• Nombre de commandes de complément dans le groupe.
• Taille de la fenêtre du client Office.

Si la fenêtre cliente est agrandie et qu’il y a plus de trois contrôles dans un groupe, l’étiquette de chaque contrôle s’affiche, mais la taille de son icône peut varier (certains sont affichés comme 16 x 16 pixels tandis que d’autres sont affichés comme 32 x 32 pixels).

Lorsqu’il y a deux commandes de complément ou plus dans un groupe et que l’espace devient limité, les ajustements suivants sont apportés à la façon dont les commandes de complément sont affichées. Ces modifications sont appliquées aux groupes de commandes de complément de droite à gauche sur le ruban dans la séquence suivante.

1. Les petites icônes (16 x 16 pixels) et les étiquettes sont affichées pour chaque commande de complément dans un groupe.
2. Seules les petites icônes sont affichées.
3. Le groupe s’affiche sous la forme d’un menu déroulant au lieu d’afficher des commandes de complément individuelles sur le ruban. Une icône de curseur de défilement s’affiche également sur le ruban, ce qui vous permet de faire défiler le ruban.

Dans Office sur le Web, la taille de l’icône et la visibilité des étiquettes des contrôles dans les groupes ne changent pas à mesure que la fenêtre du navigateur est redimensionnée. L’icône du curseur de défilement s’affiche simplement sur le ruban.

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 nouvel onglet principal personnalisé. Un complément peut avoir un seul onglet principal personnalisé. (Vous pouvez également placer des commandes de complément sur un onglet contextuel personnalisé.)

  Remarque

  Pour Outlook, les onglets personnalisés sont uniquement pris en charge dans Outlook classique sur Windows. Dans Outlook sur le web, sur Mac et dans le nouvel Outlook sur Windows, vous pouvez placer des groupes de contrôles personnalisés sur l’un des onglets du ruban intégré à la place.

• 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 de disponibilité par défaut

Vous pouvez spécifier si la commande est disponible au lancement de votre complément et modifier le paramètre par programmation.

Remarque

Cette fonctionnalité n’est pas prise en charge dans tous les scénarios ou applications Office. Pour plus d’informations, consultez Modifier la disponibilité des commandes de complément.

Position sur le ruban

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 un onglet contextuel personnalisé ; c’est-à-dire un onglet visible uniquement sur le ruban dans certains contextes, par exemple lorsqu’un graphique est sélectionné 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 sur le web
• Office sur Windows connecté à un abonnement Microsoft 365
• Office sur Mac connecté à un abonnement Microsoft 365
• Office 2021 perpétuel ou version ultérieure sur Windows ou sur 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 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.

Meilleures pratiques pour les commandes de complément sur le ruban

Le tableau suivant présente les limites recommandées pour les objets d’un ruban d’application Office.

Objet	Limite recommandée	Justification de la facilité d’utilisation
Onglets	Sept onglets visibles à la fois	Empêche de surcharger les utilisateurs avec un trop grand nombre d’options et les aide à se souvenir de l’emplacement des commandes. Nous vous recommandons d’utiliser des onglets contextuels pour réduire l’encombrement.
Groupes par onglet	Six groupes	Permet aux utilisateurs d’analyser et de localiser rapidement les commandes.
Commandes par groupe	Sept commandes	Réduit la fatigue de décision d’un trop grand nombre d’options.
Total des commandes sur le ruban	70 commandes visibles	Aide les utilisateurs à localiser efficacement les actions. Si votre complément comporte plus de 70 commandes, nous vous recommandons d’implémenter des galeries, des menus déroulants ou des boîtes de dialogue pour le dépassement de capacité.

Outre les limites d’objets recommandées, gardez les points suivants à l’esprit lors de la configuration des commandes de complément sur le ruban.

• Placez les commandes sur un onglet existant, tel que les onglets Insertion et Révision, 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 sur plusieurs versions d’Office (par exemple, Office sur le Web ou bureau) et qu’un onglet n’est pas disponible dans toutes les versions.
• 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.
• Assurez-vous que les groupes se réduisent correctement lorsque la taille de la fenêtre d’application Office change. Bien que le ruban offre un redimensionnement dynamique (voir Commandes de complément groupées sur le ruban), vous devez également définir des combinaisons de groupes pour votre complément.
• 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.
• Implémentez une boîte de dialogue pour fournir aux utilisateurs des options avancées. Cela empêche votre complément de surcharger le ruban avec des commandes rarement utilisées. Pour savoir comment implémenter un dialogue, voir Utiliser l’API de boîte de dialogue Office dans les compléments Office.

Remarque

Les compléments qui occupent trop d’espace risquent de ne pas réussir la validation de la Place de marché Microsoft.

É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 de complément uniquement, consultez Créer des commandes de complément avec le manifeste de complément uniquement 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.