Ribbon XML

  • Article

L’élément Ruban (XML) vous permet de personnaliser un ruban à l’aide de XML. Utilisez l’élément Ruban (XML) si vous souhaitez personnaliser le ruban d’une manière qui n’est pas prise en charge par l’élément Ruban (Concepteur visuel). Pour obtenir une comparaison de ce que vous pouvez faire avec chaque élément, consultez la vue d’ensemble du ruban.

S’applique à : Les informations contenues dans cette rubrique s’appliquent aux projets au niveau du document et aux projets de complément VSTO pour les applications suivantes : Excel ; InfoPath 2013 et InfoPath 2010 ; Outlook; Powerpoint; Projet; Visio; Mot. Pour plus d’informations, consultez Fonctionnalités disponibles par application Office lication et le type de projet.

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

Vous pouvez ajouter un élément Ruban (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 d’informations, consultez la référence de fichier XML du ruban 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 Ruban (XML) dans la boîte de dialogue Ajouter un nouvel élément . Microsoft application Office lications utilisent une instance de cette classe pour charger le ruban personnalisé. Pour plus d’informations, consultez la référence de classe du ruban 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 Office lication Microsoft

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 CreateRibbonExtensibilityObject méthode et retourne la classe XML du ruban à la application Office lication.

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 utilisateur, telles que cliquer sur un bouton sur le 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 appelée lorsqu’un utilisateur clique sur un bouton sur le 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, consultez Personnaliser un ruban pour Outlook.

Pour obtenir une procédure pas à pas qui montre comment automatiser une application à partir du ruban, consultez Procédure pas à pas : Créer un onglet personnalisé à l’aide du code XML du ruban.

Affecter 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 la liste complète des méthodes de rappel disponibles pour chaque contrôle, consultez l’article technique Personnaliser l’interface utilisateur du ruban Bureau (2007) pour les développeurs (partie 3 de 3) .

Définir des 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 obtenir la liste complète des signatures de méthode de rappel pour les contrôles du ruban, consultez l’article technique Personnaliser l’interface utilisateur du ruban Bureau (2007) pour les développeurs (partie 3 sur 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.");
    }
}

Informations de référence sur les fichiers 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.

Élément 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 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 la liste complète des éléments et attributs disponibles, consultez l’article technique Personnaliser l’interface utilisateur du ruban Bureau (2007) pour les développeurs (partie 2 sur 3).

Informations de référence sur les classes du ruban

Visual Studio génère la classe du ruban dans le fichier de code du ruban. Ajoutez les méthodes de rappel pour les contrôles du ruban à cette classe. 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. Microsoft application Office lications 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 :GetCustomUI doit être implémenté uniquement pour renvoyer le contenu du fichier XML du ruban ; il ne doit pas être utilisé pour initialiser votre complément 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 . Sinon, le ruban personnalisé peut 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 . Microsoft application Office lications appellent cette méthode quand ils 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 Bureau (2007) pour les développeurs (partie 1 sur 3).
GetResourceText Appelée par la méthode GetCustomUI pour obtenir le contenu du fichier XML du ruban.

Contenu connexe