Ribbon XML

  • Artikel

Mit dem Menübandelement (XML) können Sie ein Menüband mithilfe von XML anpassen. Verwenden Sie das Menübandelement (XML), wenn Sie das Menüband auf eine Weise anpassen möchten, die vom Menübandelement (Visual Designer) nicht unterstützt wird. Einen Vergleich der Möglichkeiten für die einzelnen Elemente finden Sie in der Übersicht über das Menüband.

Gilt für: Die Informationen in diesem Thema gelten für Projekte auf Dokumentebene und VSTO-Add-In-Projekte für die folgenden Anwendungen: Excel; InfoPath 2013 und InfoPath 2010; Outlook; Powerpoint; Projekt; Visio; Wort. Weitere Informationen finden Sie unter features available by Office-App lication and project type.

Hinzufügen eines Menübandelements (XML) zu einem Projekt

Können Sie einem Office-Projekt ein Element Menüband (XML) über das Dialogfeld Neues Element hinzufügen hinzufügen. Visual Studio fügt die folgenden Dateien automatisch hinzu:

  • Eine Menüband-XML-Datei. Diese Datei definiert die Menüband-Benutzeroberfläche (User Interface, UI). Verwenden Sie diese Datei, um Benutzeroberflächenelemente (z. B. Registerkarten, Gruppen und Steuerelemente) hinzuzufügen. Ausführliche Informationen finden Sie in der Xml-Dateireferenz des Menübands weiter unten in diesem Thema.

  • Eine Menüband-Codedatei. Diese Datei enthält die Klasse "Menüband". Diese Klasse trägt den Namen, den Sie im Dialogfeld Neues Element hinzufügen für das Element Menüband (XML) angeben. Microsoft Office-App lizenzierungen verwenden eine Instanz dieser Klasse, um das benutzerdefinierte Menüband zu laden. Ausführliche Informationen finden Sie weiter unten in diesem Thema unter der Referenz zur Menübandklasse.

    Standardmäßig fügen diese Dateien der Registerkarte "Add-Ins " im Menüband eine benutzerdefinierte Gruppe hinzu.

Anzeigen des benutzerdefinierten Menübands in einer Microsoft Office-App lizenzierung

Nachdem Sie ihrem Projekt ein Menübandelement (XML) hinzugefügt haben, müssen Sie der Klasse ThisAddin, ThisWorkbook oder ThisDocument Code hinzufügen, die die CreateRibbonExtensibilityObject Methode außer Kraft setzt und die XML-Klasse des Menübands an die Office-App lication zurückgibt.

Der folgende Codebeispiel setzt die Methode CreateRibbonExtensibilityObject außer Kraft und gibt eine Klasse "Menüband-XML" namens "MyRibbon" zurück.

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

Definieren des Verhaltens des benutzerdefinierten Menübands

Sie können auf Benutzeraktionen reagieren, z. B. durch Klicken auf eine Schaltfläche im Menüband, indem Sie Rückrufmethoden erstellen. Rückrufmethoden ähneln Ereignissen in Windows Forms-Steuerelementen, werden jedoch durch ein Attribut im XML-Code des Benutzeroberflächenelements identifiziert. Sie schreiben Methoden in der Klasse "Menüband", und ein Steuerelement ruft die Methode auf, die den gleichen Namen wie der Attributwert aufweist. Sie können beispielsweise eine Rückrufmethode erstellen, die aufgerufen wird, wenn ein Benutzer auf eine Schaltfläche im Menüband klickt. Zum Erstellen einer Rückrufmethode sind zwei Schritte erforderlich:

  • Zuweisen eines Attributs zu einem Steuerelement in der Menüband-XML-Datei, die eine Rückrufmethode in Ihrem Code identifiziert.

  • Definieren der Rückrufmethode in der Klasse "Menüband".

Hinweis

Für Outlook ist ein zusätzlicher Schritt erforderlich. Weitere Informationen finden Sie unter Anpassen eines Menübands für Outlook.

Eine exemplarische Vorgehensweise, die veranschaulicht, wie eine Anwendung über das Menüband automatisiert wird, finden Sie unter Walkthrough: Create a custom tab by using Ribbon XML.

Zuweisen von Rückrufmethoden zu Steuerelementen

Wenn Sie einem Steuerelement eine Rückrufmethode in der Menüband-XML-Datei zuzuweisen möchten, fügen Sie ein Attribut hinzu, das den Typ der Rückrufmethode und den Namen der Methode angibt. Das folgende Element definiert z. B. eine Umschaltfläche, die über eine onAction -Rückrufmethode mit dem Namen OnToggleButton1.

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

onAction wird aufgerufen, wenn der Benutzer die einem bestimmten Steuerelement zugeordnete Hauptaufgabe ausführt. Die onAction -Rückrufmethode einer Umschaltfläche wird z. B. aufgerufen, wenn der Benutzer auf die Schaltfläche klickt.

Die Methode, die Sie im Attribut angeben, kann einen beliebigen Namen besitzen. Er muss jedoch mit dem Namen der Methode übereinstimmen, den Sie in der Menüband-Codedatei definieren.

Es gibt viele verschiedene Typen von Rückrufmethoden, die Sie Menüband-Steuerelementen zuweisen können. Eine vollständige Liste der für jedes Steuerelement verfügbaren Rückrufmethoden finden Sie im technischen Artikel Anpassen der Office-Benutzeroberfläche (2007) des Menübands für Entwickler (Teil 3 von 3).

Definieren von Rückrufmethoden

Definieren Sie die Rückrufmethoden in der Klasse "Menüband" in der Menüband-Codedatei. Für eine Rückrufmethode gelten mehrere Anforderungen:

  • Sie muss als öffentlich deklariert werden.

  • Ihr Name muss mit dem Namen einer Rückrufmethode übereinstimmen, die Sie einem Steuerelement in der Menüband-XML-Datei zugewiesen haben.

  • Ihre Signatur muss mit die Signatur eines Typs einer Rückrufmethode übereinstimmen, die für das zugehörige Menüband-Steuerelement verfügbar ist.

    Eine vollständige Liste der Rückrufmethodensignaturen für Menübandsteuerelemente finden Sie im technischen Artikel Anpassen der Office-Benutzeroberfläche (2007) des Menübands für Entwickler (Teil 3 von 3). Visual Studio bietet keine IntelliSense-Unterstützung für Rückrufmethoden, die Sie in der Menüband-Codedatei erstellen. Wenn Sie eine Rückrufmethode erstellen, die nicht mit einer gültigen Signatur übereinstimmt, wird der Code zwar kompiliert. Es geschieht jedoch nichts, wenn der Benutzer auf das Steuerelement klickt.

    Alle Rückrufmethoden verfügen über einen Parameter IRibbonControl , der das Steuerelement darstellt, das die Methode aufgerufen hat. Sie können diesen Parameter verwenden, um die gleiche Rückrufmethode für mehrere Steuerelemente wiederzuverwenden. Das folgende Codebeispiel veranschaulicht eine onAction -Rückrufmethode, die verschiedene Aufgaben abhängig davon ausführt, auf welches Steuerelement der Benutzer klickt.

    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.");
    }
}

XML-Menübanddateireferenz

Sie können Ihr benutzerdefiniertes Menüband definieren, indem Sie der XML-Datei des Menübands Elemente und Attribute hinzufügen. Standardmäßig enthält die Menüband-XML-Datei die folgenden XML-Elemente.

<?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>

In der folgende Tabelle werden die Standardelemente in der Menüband-XML-Datei beschrieben.

Element Beschreibung
customUI Stellt das benutzerdefinierte Menüband im VSTO-Add-In-Projekt dar.
ribbon Stellt das Menüband dar.
Registerkarten Stellt eine Sammlung von Registerkarten des Menübands dar.
Registerkarte Stellt eine einzelne Registerkarte des Menübands dar.
group Stellt eine Gruppe von Steuerelementen auf der Registerkarte des Menübands dar.

Diese Elemente verfügen über Attribute, die das Aussehen und Verhalten des benutzerdefinierten Menübands angeben. In der folgende Tabelle werden die Standardattribute in der Menüband-XML-Datei beschrieben.

attribute Übergeordnetes Element Beschreibung
Onload customUI Identifiziert eine Methode, die aufgerufen wird, wenn die Anwendung das Menüband lädt.
idMso Registerkarte Identifiziert eine integrierte Registerkarte, die im Menüband angezeigt werden soll.
id group Gibt die Gruppe an.
label group Gibt den Text an, der für die Gruppe angezeigt wird.

Die Standardelemente und -attribute in der Menüband-XML-Datei sind eine kleine Teilmenge der Elemente und Attribute, die verfügbar sind. Eine vollständige Liste der verfügbaren Elemente und Attribute finden Sie im technischen Artikel Anpassen der Office-Benutzeroberfläche (2007) des Menübands für Entwickler (Teil 2 von 3).

Referenz zur Menübandklasse

Visual Studio generiert die Klasse "Menüband" in der Menüband-Codedatei. Fügen Sie dieser Klasse die Rückrufmethoden für Steuerelemente im Menüband hinzu. Diese Klasse implementiert die IRibbonExtensibility -Schnittstelle.

Die folgende Tabelle beschreibt die Standardmethoden in dieser Klasse.

Methode Beschreibung
GetCustomUI Gibt den Inhalt der Menüband-XML-Datei zurück. Microsoft Office-App lications rufen diese Methode auf, um eine XML-Zeichenfolge abzurufen, die die Benutzeroberfläche Ihres benutzerdefinierten Menübands definiert. Diese Methode implementiert die Methode GetCustomUI . Hinweis:GetCustomUI Sollte nur implementiert werden, um den Inhalt der XML-Datei des Menübands zurückzugeben. Es sollte nicht verwendet werden, um Ihr VSTO-Add-In zu initialisieren. Insbesondere sollten nicht versuchen, Dialogfelder oder andere Fenster in Ihrer GetCustomUI Implementierung anzuzeigen. Andernfalls verhält sich das benutzerdefinierte Menüband möglicherweise nicht ordnungsgemäß. Wenn Sie Code ausführen müssen, der Ihr VSTO-Add-In initialisiert, fügen Sie den Code dem ThisAddIn_Startup -Ereignishandler hinzu.
OnLoad Weist den Parameter IRibbonControl dem Feld Ribbon zu. Microsoft Office-App lications rufen diese Methode auf, wenn sie das benutzerdefinierte Menüband laden. Sie können dieses Feld verwenden, um das benutzerdefinierte Menüband dynamisch zu aktualisieren. Weitere Informationen finden Sie im technischen Artikel Anpassen der Office-Benutzeroberfläche (2007) des Menübands für Entwickler (Teil 1 von 3).
GetResourceText Wird von der Methode GetCustomUI aufgerufen, um den Inhalt der Menüband-XML-Datei abzurufen.

Zugehöriger Inhalt