Übersicht über das Menübandobjektmodell

Die Visual Studio Tools für die Office-Laufzeitumgebung bieten ein stark typisiertes Objektmodell, mit dem Sie zur Laufzeit die Eigenschaften von Menüband-Steuerelementen abrufen und festlegen können. Sie können beispielsweise Menüsteuerelemente dynamisch auffüllen oder Steuerelemente kontextbezogen ein- und ausblenden. Sie können einem Menüband auch Registerkarten, Gruppen und Steuerelemente hinzufügen, aber nur bevor das Menüband von der Office-Anwendung geladen wird. Weitere Informationen finden Sie unter Festlegen von Eigenschaften, die zu schreibgeschütztem Zugriff führen.

Gilt für: Die Informationen in diesem Thema gelten für Dokumentprojekte und VSTO-Add-In-Projekte für die folgenden Anwendungen: Excel; InfoPath 2013 und InfoPath 2010; Outlook; PowerPoint; Project; Visio; Word. Weitere Informationen finden Sie unter Funktionen verfügbar nach Office-Anwendung und Projekttyp.

Dieses Menübandobjektmodell besteht hauptsächlich aus den Menübandklassen, Menübandereignissen und Menüband-Steuerelementklassen.

Menübandklasse

Wenn Sie einem Projekt ein neues Ribbon (Visual Designer) hinzufügen, fügt Visual Studio Ihrem Projekt eine Ribbon-Klasse hinzu. Die Ribbon-Klasse erbt von der RibbonBase Klasse.

Diese Klasse wird als partielle Klasse angezeigt, die zwischen der Codedatei des Menübands und der Codedatei des Menüband-Designers geteilt wird.

Menübandereignisse

Die Ribbon-Klasse enthält die folgenden drei Ereignisse:

Menübandsteuerelemente

Der Microsoft.Office.Tools.Ribbon Namespace enthält einen Typ für jedes Steuerelement, das in der Gruppe " Office Ribbon Controls " der Toolbox angezeigt wird.

Die folgende Tabelle zeigt den Typ für jedes Ribbon Steuerelement. Eine Beschreibung der einzelnen Steuerelemente finden Sie in der Ribbon-Übersicht.

Der Microsoft.Office.Tools.Ribbon Namespace verwendet das Präfix "Ribbon" für diese Typen, um einen Namenskonflikt mit den Namen von Steuerelementklassen im System.Windows.Forms Namespace zu vermeiden.

Wenn Sie dem Menüband-Designer ein Steuerelement hinzufügen, deklariert der Menüband-Designer die Klasse für dieses Steuerelement als Feld in der Codedatei des Menüband-Designers.

Typische Aufgaben unter Verwendung der Eigenschaften von Menübandsteuerelementen

Jedes Ribbon Steuerelement enthält Eigenschaften, mit denen Sie verschiedene Aufgaben ausführen können, z. B. das Zuweisen einer Bezeichnung zu einem Steuerelement oder das Ausblenden und Anzeigen von Steuerelementen.

In einigen Fällen werden Eigenschaften nur-lesend, nachdem das Menüband geladen oder ein Steuerelement zu einem dynamischen Menü hinzugefügt wird. Weitere Informationen finden Sie unter Festlegen von Eigenschaften, die schreibgeschützt werden.

In der folgenden Tabelle werden einige der Aufgaben beschrieben, die Sie mithilfe von Ribbon Steuerelementeigenschaften ausführen können.

Eigenschaften festlegen, die nur-lesbar werden

Einige Eigenschaften können nur festgelegt werden, bevor das Menüband geladen wird. Es gibt drei Orte zum Festlegen dieser Eigenschaften:

• Im Fenster "Eigenschaften " von Visual Studio.

• Im Konstruktor der Klasse Ribbon.

• In der CreateRibbonExtensibilityObject-Methode der ThisAddin-, ThisWorkbook- oder ThisDocument-Klasse Ihres Projekts.

  Dynamische Menüs bieten einige Ausnahmen. Sie können neue Steuerelemente erstellen, deren Eigenschaften festlegen und sie dann zur Laufzeit einem dynamischen Menü hinzufügen, auch nachdem das Menüband geladen wurde, das das Menü enthält.

  Eigenschaften von Steuerelementen, die Sie einem dynamischen Menü hinzufügen, können jederzeit festgelegt werden.

  Weitere Informationen finden Sie unter Eigenschaften, die schreibgeschützt sind.

Festlegen von Eigenschaften im Konstruktor des Menübands

Sie können die Eigenschaften eines Ribbon Steuerelements im Konstruktor der Ribbon-Klasse festlegen. Dieser Code muss nach dem Aufruf der InitializeComponent Methode angezeigt werden. Im folgenden Beispiel wird einer Gruppe eine neue Schaltfläche hinzugefügt, wenn die aktuelle Uhrzeit 17:00 Uhr Pazifische Zeit (UTC-8) oder später ist.

Fügen Sie den folgenden Code hinzu.

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

In Visual C#-Projekten, die Sie von Visual Studio 2008 aktualisiert haben, wird der Konstruktor in der Menüband-Codedatei angezeigt.

In Visual Basic-Projekten oder in Visual C#-Projekten, die Sie in Visual Studio 2013 erstellt haben, wird der Konstruktor in der Codedatei des Menüband-Designers angezeigt. Diese Datei heißt "YourRibbonItem". Designer.cs oder YourRibbonItem. Designer.vb. Um diese Datei in Visual Basic-Projekten anzuzeigen, müssen Sie zuerst im Projektmappen-Explorer auf die Schaltfläche "Alle Dateien anzeigen " klicken.

Festlegen von Eigenschaften in der CreateRibbonExtensibilityObject-Methode

Sie können die Eigenschaften eines Ribbon Steuerelements festlegen, wenn Sie die Methode in der CreateRibbonExtensibilityObjectThisAddin, ThisWorkbookoder ThisDocument Klasse Ihres Projekts überschreiben. Weitere Informationen zu der CreateRibbonExtensibilityObject-Methode finden Sie unter Ribbon-Übersicht.

Im folgenden Beispiel werden die Ribbon-Eigenschaften in der CreateRibbonExtensibilityObject Methode der ThisWorkbook Klasse eines Excel-Workbook-Projekts konfiguriert.

Fügen Sie den folgenden Code hinzu.

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

Eigenschaften, die schreibgeschützt werden

In der folgenden Tabelle sind Eigenschaften aufgeführt, die nur vor dem Laden des Ribbons festgelegt werden können.

Festlegen von Eigenschaften für Menübänder, die in Outlook-Inspektoren angezeigt werden

Jedes Mal wird eine neue Instanz des Menübands erstellt, wenn ein Benutzer einen Inspektor öffnet, in dem das Menüband angezeigt wird. Sie können die in der obigen Tabelle aufgeführten Eigenschaften jedoch erst festlegen, bevor die erste Instanz des Menübands erstellt wird. Nachdem die erste Instanz erstellt wurde, sind diese Eigenschaften schreibgeschützt, da die erste Instanz die XML-Datei definiert, die Outlook zum Laden des Menübands verwendet.

Wenn Sie bedingte Logik haben, die eine dieser Eigenschaften auf einen anderen Wert festlegt, wenn andere Instanzen des Menübands erstellt werden, hat dieser Code keine Auswirkung.

Ribbon-Steuerungsereignisse

Jede Steuerelementklasse enthält ein oder mehrere Ereignisse. In der folgenden Tabelle werden diese Ereignisse beschrieben.

Die Ereignishandler für diese Ereignisse weisen die folgenden beiden Parameter auf.

Verwandte Inhalte

• Greifen Sie zur Laufzeit auf das Menüband zu
• Menübandübersicht
• Gewusst wie: Erste Schritte beim Anpassen des Menübands
• Menüband-Designer
• Anleitung: Erstellen einer benutzerdefinierten Registerkarte mithilfe des Menüband-Designers
• Anleitung: Aktualisieren der Steuerelemente auf einem Menüband zur Laufzeit
• Anpassen eines Menübands für Outlook
• So geht's: Anpassen einer eingebauten Registerkarte
• Vorgehensweise: Hinzufügen von Steuerelementen zur Backstage-Ansicht
• Vorgehensweise: Exportieren eines Menübands aus dem Menüband-Designer in Menüband-XML
• Vorgehensweise: Anzeigen von Add-In-Benutzeroberflächenfehlern