Partager via

Ribbon XML

  • Article

L'élément Ribbon (XML) vous permet de personnaliser un ruban en utilisant XML. Utilisez l'élément Ribbon (XML) si vous souhaitez personnaliser le ruban d'une manière qui n'est pas prise en charge par l'élément Ribbon (Visual Designer). Pour une comparaison de ce que vous pouvez faire avec chaque élément, voir Vue d'ensemble du ruban.

S'applique à : Les informations de cette rubrique s'appliquent aux projets de niveau document et aux projets de complément VSTO pour les applications suivantes : Excel ; InfoPath 2013 et InfoPath 2010 ; Outlook ; PowerPoint ; Project ; Visio ; Word. Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Ajouter un élément du ruban (XML) à un projet

Vous pouvez ajouter un élément Ribbon (XML) à tout projet Office à partir de la boîte de dialogue Ajouter un nouvel élément . Visual Studio ajoute automatiquement les fichiers suivants à votre projet :

  • Un fichier XML de ruban. Ce fichier définit l'interface utilisateur du ruban. Utilisez ce fichier pour ajouter des éléments d'interface utilisateur tels que des onglets, des groupes et des contrôles. Pour plus de détails, reportez-vous à la référence du fichier Ribbon XML, plus loin dans cette rubrique.

  • Un fichier de code du ruban. Ce fichier contient la classe du ruban. Cette classe porte le nom que vous avez spécifié pour l'élément Ribbon (XML) dans la boîte de dialogue Ajouter un nouvel élément . Les applications Microsoft Office utilisent une instance de cette classe pour charger le ruban personnalisé. Pour plus de détails, voir la référence de la classe Ribbon plus loin dans cette rubrique.

    Par défaut, ces fichiers ajoutent un groupe personnalisé à l'onglet Compléments du ruban.

Afficher le ruban personnalisé dans une application Microsoft Office

Après avoir ajouté un élément Ribbon (XML) à votre projet, vous devez ajouter du code à la classe ThisAddin, ThisWorkbook ou ThisDocument qui remplace la méthode CreateRibbonExtensibilityObject et renvoie la classe XML du ruban à l'application Office.

L'exemple de code suivant remplace la méthode CreateRibbonExtensibilityObject et retourne une classe XML de ruban nommée MyRibbon.

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

Définir le comportement du ruban personnalisé

Vous pouvez répondre aux actions de l'utilisateur, telles que cliquer sur un bouton du ruban, en créant des méthodes de rappel. Les méthodes de rappel ressemblent aux événements figurant dans les contrôles Windows Forms, mais elles sont identifiées par un attribut dans le code XML de l'élément d'interface utilisateur. Vous écrivez des méthodes dans la classe du ruban et un contrôle appelle la méthode qui porte le même nom que la valeur d'attribut. Par exemple, vous pouvez créer une méthode de rappel qui est appelée lorsque l'utilisateur clique sur un bouton du ruban. Deux étapes sont nécessaires pour créer une méthode de rappel :

  • Assignez un attribut à un contrôle dans le fichier XML du ruban, qui identifie une méthode de rappel dans votre code.

  • Définissez la méthode de rappel dans la classe du ruban.

Remarque

Outlook requiert une étape supplémentaire. Pour plus d'informations, voir Personnaliser un ruban pour Outlook.

Pour une procédure-à-pas-pas qui démontre comment automatiser une application à partir du ruban, voir Procédure-à-pas-pas : Créez un onglet personnalisé à l'aide de Ribbon XML.

Attribuer des méthodes de rappel aux contrôles

Pour affecter une méthode de rappel à un contrôle dans le fichier XML du ruban, ajoutez un attribut qui spécifie le type et le nom de cette méthode. Par exemple, l'élément suivant définit un bouton doté d'une méthode de rappel onAction nommée OnToggleButton1.

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

La méthodeonAction est appelée quand l'utilisateur exécute la tâche principale associée à un contrôle particulier. Par exemple, la méthode de rappel onAction d'un bouton bascule est appelée quand l'utilisateur clique sur le bouton.

La méthode que vous spécifiez dans l'attribut peut avoir un nom quelconque. Toutefois, ce nom doit correspondre au nom de la méthode que vous définissez dans le fichier de code du ruban.

De nombreux types différents de méthodes de rappel peuvent être affectés aux contrôles du ruban. Pour obtenir une liste complète des méthodes de rappel disponibles pour chaque contrôle, consultez l'article technique Personnaliser l'interface utilisateur du ruban Office (2007) pour les développeurs (partie 3 sur 3).

Définir les méthodes de rappel

Définissez vos méthodes de rappel dans la classe du ruban, dans le fichier de code du ruban. Une méthode de rappel a plusieurs conditions requises :

  • Elle doit être déclarée comme publique.

  • Son nom doit correspondre au nom d'une méthode de rappel que vous avez affectée à un contrôle dans le fichier XML du ruban.

  • Sa signature doit correspondre à la signature d'un type de méthode de rappel disponible pour le contrôle du ruban associé.

    Pour une liste complète des signatures des méthodes de rappel pour les contrôles du ruban, voir l'article technique Personnaliser l'interface utilisateur du ruban Office (2007) pour les développeurs (Partie 3 de 3). Visual Studio ne fournit pas de prise en charge IntelliSense pour les méthodes de rappel que vous créez dans le fichier de code du ruban. Si vous créez une méthode de rappel qui ne correspond pas à une signature valide, le code est compilé mais rien ne se passe quand l'utilisateur clique sur le contrôle.

    Toutes les méthodes de rappel ont un paramètre IRibbonControl qui représente le contrôle qui a appelé la méthode. Ce paramètre permet de réutiliser la même méthode de rappel pour plusieurs contrôles. L'exemple de code suivant présente une méthode de rappel onAction qui exécute différentes tâches en fonction du contrôle sur lequel l'utilisateur clique.

    public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
{
    if (control.Id == "checkBox1")
    {
        MessageBox.Show("You clicked " + control.Id);
    }
    else
    {
        MessageBox.Show("You clicked a different control.");
    }
}

Référence du fichier XML du ruban

Vous pouvez définir votre ruban personnalisé en ajoutant des éléments et des attributs au fichier XML du ruban. Par défaut, le fichier XML du ruban contient le code XML suivant.

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

Le tableau suivant décrit les éléments par défaut du fichier XML du ruban.

Element Description
customUI Représente le ruban personnalisé dans le projet de complément VSTO.
ribbon Représente le ruban.
onglets Représente un ensemble d'onglets du ruban.
onglet Représente un onglet individuel du ruban.
groupe Représente un groupe de contrôles sous l'onglet du ruban.

Ces éléments ont des attributs qui spécifient l'apparence et le comportement du ruban personnalisé. Le tableau suivant décrit les attributs par défaut figurant dans le fichier XML du ruban.

Attribut Élément parent Description
onLoad customUI Identifie une méthode qui est appelée lorsque l'application charge le ruban.
idMso onglet Identifie un onglet intégré à afficher dans le ruban.
id groupe Identifie le groupe.
label groupe Spécifie le texte qui apparaît sur le groupe.

Les éléments et les attributs par défaut figurant dans le fichier XML du ruban sont un petit sous-ensemble des éléments et attributs disponibles. Pour obtenir une liste complète des éléments et attributs disponibles, consultez l'article technique Personnaliser l'interface utilisateur du ruban Office (2007) pour les développeurs (partie 2 sur 3).

Référence de la classe du ruban

Visual Studio génère la classe du ruban dans le fichier de code du ruban. Ajoutez à cette classe les méthodes de rappel des contrôles du ruban. Cette classe implémente l’interface IRibbonExtensibility.

Le tableau suivant décrit les méthodes par défaut de cette classe.

Méthode Description
GetCustomUI Retourne le contenu du fichier XML du ruban. Les applications Microsoft Office appellent cette méthode pour obtenir une chaîne XML qui définit l'interface utilisateur de votre ruban personnalisé. Cette méthode implémente la méthode GetCustomUI . Remarque : GetCustomUIdoit être mis en œuvre uniquement pour renvoyer le contenu du fichier XML du ruban ; il ne doit pas être utilisé pour initialiser votre module d'extension VSTO. En particulier, vous ne devez pas essayer d'afficher des boîtes de dialogue ni d'autres fenêtres dans votre implémentation de GetCustomUI . Dans le cas contraire, le ruban personnalisé risque de ne pas se comporter correctement. Si vous devez exécuter du code qui initialise votre complément VSTO, ajoutez ce code au gestionnaire d’événements ThisAddIn_Startup .
OnLoad Affecte le paramètre IRibbonControl au champ Ribbon . Les applications Microsoft Office appellent cette méthode lorsqu'elles chargent le ruban personnalisé. Vous pouvez utiliser ce champ pour mettre à jour dynamiquement le ruban personnalisé. Pour plus d'informations, consultez l'article technique Personnaliser l'interface utilisateur du ruban Office (2007) pour les développeurs (Partie 1 de 3).
GetResourceText Appelée par la méthode GetCustomUI pour obtenir le contenu du fichier XML du ruban.

Contenu connexe