Vue d’ensemble du modèle objet du ruban

Article
10/10/2023

Le runtime Visual Studio Tools pour Office expose un modèle objet fortement typé que vous pouvez utiliser pour obtenir et définir les propriétés des contrôles du ruban au moment de l’exécution. Par exemple, vous pouvez remplir dynamiquement des contrôles de menu, ou afficher et masquer les contrôles de manière contextuelle. Vous pouvez également ajouter des onglets, des groupes et des contrôles à un ruban, mais uniquement avant le chargement du ruban par la application Office lication. Pour plus d’informations, consultez Définir les propriétés qui deviennent en lecture seule.

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.

Ce modèle objet Ruban se compose principalement de la classe Ruban, des événements de ruban et des classes de contrôle Ruban.

Classe de ruban

Lorsque vous ajoutez un nouvel élément ruban (Concepteur visuel) à un projet, Visual Studio ajoute une classe de ruban à votre projet. La classe Ribbon hérite de la RibbonBase classe.

Cette classe apparaît sous la forme d’une classe partielle qui est divisée entre le fichier de code du ruban et le fichier de code du Concepteur de ruban.

Événements du ruban

La classe Ribbon contient les trois événements suivants :

Événement	Description
Load	Déclenché lorsque la application Office lication charge la personnalisation du ruban. Le Load gestionnaire d’événements est automatiquement ajouté au fichier de code du ruban. Utilisez ce gestionnaire d’événements pour exécuter du code personnalisé lorsque le ruban se charge.
LoadImage	Vous permet de mettre en cache des images dans la personnalisation du ruban lorsque le ruban se charge. Vous pouvez obtenir un léger gain de performances si vous écrivez du code pour mettre en cache les images du ruban dans ce gestionnaire d’événements. Pour plus d’informations, consultez LoadImage.
Close	Déclenché lorsque l’instance du ruban se ferme.

Contrôles du ruban

L’espace Microsoft.Office.Tools.Ribbon de noms contient un type pour chaque contrôle que vous voyez dans le groupe contrôles du ruban Bureau de la boîte à outils.

Le tableau suivant montre le type de chaque Ribbon contrôle. Pour obtenir une description de chaque contrôle, consultez la vue d’ensemble du ruban.

Nom du contrôle	Nom de classe
Box	RibbonBox
Button	RibbonButton
Buttongroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
Liste déroulante	RibbonDropDown
Editbox	RibbonEditBox
Galerie	RibbonGallery
Groupe	RibbonGroup
Étiquette	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

L’espace Microsoft.Office.Tools.Ribbon de noms utilise le préfixe « Ribbon » pour ces types afin d’éviter un conflit de noms avec les noms des classes de contrôle dans l’espace System.Windows.Forms de noms.

Lorsque vous ajoutez un contrôle au Concepteur de ruban, le Concepteur de ruban déclare la classe de ce contrôle en tant que champ dans le fichier de code du Concepteur de ruban.

Tâches courantes utilisant les propriétés des contrôles du ruban

Chaque Ribbon contrôle contient des propriétés que vous pouvez utiliser pour effectuer différentes tâches, telles que l’affectation d’une étiquette à un contrôle ou le masquage et l’affichage de contrôles.

Dans certains cas, les propriétés deviennent en lecture seule une fois le ruban chargé ou après l’ajout d’un contrôle à un menu dynamique. Pour plus d’informations, consultez Définir les propriétés qui deviennent en lecture seule.

Le tableau suivant décrit certaines des tâches que vous pouvez effectuer à l’aide Ribbon des propriétés de contrôle.

Pour cette tâche :	Procédez comme suit :
Masquer ou afficher un contrôle.	Utilisez la propriété Visible.
Activez ou désactivez un contrôle.	Utilisez la propriété Enabled.
Définissez la taille d’un contrôle.	Utilisez la propriété ControlSize.
Obtenez l’image qui s’affiche sur un contrôle.	Utilisez la propriété Image.
Modifiez l’étiquette d’un contrôle.	Utilisez la propriété Label.
Ajoutez des données définies par l’utilisateur à un contrôle.	Utilisez la propriété Tag.
Obtenir les éléments dans un RibbonBox, RibbonDropDown, RibbonGalleryou RibbonSplitButton Contrôle.	Utilisez la propriété Items.
Ajoutez des éléments à un contrôle ou à un RibbonComboBoxcontrôleRibbonDropDown RibbonGallery.	Utilisez la propriété Items.
Ajouter des contrôles à un RibbonMenu.	Utilisez la propriété Items. Pour ajouter des contrôles à l’issue RibbonMenu du chargement du ruban dans la application Office lication, vous devez définir la Dynamic propriété sur true avant le chargement du ruban dans la application Office lication. Pour plus d’informations, consultez Définir les propriétés qui deviennent en lecture seule.
Obtenir l’élément sélectionné d’un RibbonComboBox, RibbonDropDown, ou RibbonGallery.	Utilisez la propriété SelectedItem. Pour un RibbonComboBox, utilisez la Text propriété.
Obtenir les groupes sur un RibbonTab.	Utilisez la propriété Groups.
Spécifiez le nombre de lignes et de colonnes qui apparaissent dans un RibbonGallery.	Utilisez les propriétés et ColumnCount les RowCount propriétés.

Définir des propriétés qui deviennent en lecture seule

Certaines propriétés ne peuvent être définies qu’avant le chargement du ruban. Il existe trois emplacements pour définir ces propriétés :

Dans la fenêtre Propriétés de Visual Studio.
Dans le constructeur de la classe Ribbon .
Dans la méthode du , ThisWorkbookou ThisDocument de la CreateRibbonExtensibilityObjectThisAddinclasse de votre projet.

Les menus dynamiques fournissent certaines exceptions. Vous pouvez créer des contrôles, définir leurs propriétés, puis les ajouter à un menu dynamique au moment de l’exécution, même après le chargement du ruban qui contient le menu.

Les propriétés des contrôles que vous ajoutez à un menu dynamique peuvent être définies à tout moment.

Pour plus d’informations, consultez Propriétés qui deviennent en lecture seule.

Définir des propriétés dans le constructeur du ruban

Vous pouvez définir les propriétés d’un Ribbon contrôle dans le constructeur de la classe Ribbon . Ce code doit apparaître après l’appel à la InitializeComponent méthode. L’exemple suivant ajoute un nouveau bouton à un groupe si l’heure actuelle est 17 :00 Pacific Time (UTC-8) ou une version ultérieure.

Ajoutez le code suivant.

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

Dans les projets Visual C# que vous avez mis à niveau à partir de Visual Studio 2008, le constructeur apparaît dans le fichier de code du ruban.

Dans les projets Visual Basic ou dans les projets Visual C# que vous avez créés dans Visual Studio 2013, le constructeur apparaît dans le fichier de code du Concepteur de ruban. Ce fichier est nommé YourRibbonItem. Designer.cs ou YourRibbonItem. Designer.vb. Pour afficher ce fichier dans les projets Visual Basic, vous devez d’abord cliquer sur le bouton Afficher tous les fichiers dans Explorateur de solutions.

Définir des propriétés dans la méthode CreateRibbonExtensibilityObject

Vous pouvez définir les propriétés d’un Ribbon contrôle lorsque vous remplacez la CreateRibbonExtensibilityObject méthode dans le ThisAddin, ThisWorkbookou ThisDocument la classe de votre projet. Pour plus d’informations sur la méthode, consultez Vue d’ensemble du CreateRibbonExtensibilityObject ruban.

L’exemple suivant définit les propriétés du ruban dans la CreateRibbonExtensibilityObject méthode de la ThisWorkbook classe d’un projet de classeur Excel.

Ajoutez le code suivant.

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

Propriétés qui deviennent en lecture seule

Le tableau suivant montre les propriétés qui ne peuvent être définies qu’avant le chargement du ruban.

Remarque

Vous pouvez définir les propriétés des contrôles sur les menus dynamiques à tout moment. Ce tableau ne s’applique pas dans ce cas.

Propriété	Classe de contrôle du ruban
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
Boîte de dialogue Lanceur	RibbonGroup
Dynamique	RibbonMenu
Global	OfficeRibbon
Groupes	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Nom	RibbonComponent
Poste	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
RibbonType	OfficeRibbon
Rowcount	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
Onglets	OfficeRibbon
Titre	RibbonSeparator

Définir les propriétés des rubans qui s’affichent dans les inspecteurs Outlook

Une nouvelle instance du ruban est créée chaque fois qu’un utilisateur ouvre un inspecteur dans lequel le ruban apparaît. Toutefois, vous pouvez définir les propriétés répertoriées dans le tableau ci-dessus uniquement avant la création de la première instance du ruban. Une fois la première instance créée, ces propriétés deviennent en lecture seule, car la première instance définit le fichier XML utilisé par Outlook pour charger le ruban.

Si vous avez une logique conditionnelle qui définit l’une de ces propriétés sur une valeur différente lorsque d’autres instances du ruban sont créées, ce code n’aura aucun effet.

Remarque

Vérifiez que la propriété Name est définie pour chaque contrôle que vous ajoutez à un ruban Outlook. Si vous ajoutez un contrôle à un ruban Outlook au moment de l’exécution, vous devez définir cette propriété dans votre code. Si vous ajoutez un contrôle à un ruban Outlook au moment du design, la propriété Name est définie automatiquement.

Événements de contrôle du ruban

Chaque classe de contrôle contient un ou plusieurs événements. Le tableau suivant décrit ces événements.

Événement	Description
Cliquez	Se produit lorsqu’un contrôle est cliqué.
TextChanged	Se produit lorsque le texte d’une zone d’édition ou d’une zone de liste modifiable est modifié.
ItemsLoading	Se produit lorsque la collection Items du contrôle est demandée par Bureau. Bureau met en cache la collection Items jusqu’à ce que votre code modifie les propriétés du contrôle, ou que vous appelez la InvalidateControl méthode.
ButtonClick	Se produit lorsqu’un bouton dans un RibbonGallery ou RibbonDropDown un clic est effectué.
SelectionChanged	Se produit lorsque la sélection dans une RibbonDropDown ou RibbonGallery des modifications est effectuée.
Boîte de dialogue Lanceur Click	Se produit lorsque l’icône du lanceur de dialogue dans le coin inférieur droit d’un groupe est cliquée.

Les gestionnaires d’événements pour ces événements ont les deux paramètres suivants.

Paramètre	Description
Expéditeur	Qui Object représente le contrôle qui a déclenché l’événement.
e	Qui RibbonControlEventArgs contient un IRibbonControl. Utilisez ce contrôle pour accéder à toute propriété qui n’est pas disponible dans le modèle objet du ruban fourni par le runtime Visual Studio Tools pour Office.