Freigeben über

Ribbon XML

  • Artikel

Das Element Ribbon (XML) ermöglicht das Anpassen eines Menübands mithilfe von XML. Verwenden Sie das Element Ribbon (XML), wenn Sie das Menüband auf eine Weise anpassen möchten, die nicht vom Element Ribbon (Visual Designer) unterstützt wird. Einen Vergleich der Möglichkeiten für die einzelnen Elemente finden Sie in der Ribbon-Übersicht über.

Gilt für: Die Informationen in diesem Thema betreffen Projekte auf Dokumentebene und VSTOAddIn-Projekte für die folgenden Anwendungen: Excel, InfoPath 2013 und InfoPath 2010, Outlook, PowerPoint, Project, Visio und Word. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

Hinzufügen eines Elements Ribbon (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. Details finden Sie unter Referenz zur Ribbon-XML-Datei 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-Anwendungen verwenden eine Instanz dieser Klasse, um das benutzerdefinierte Menüband zu laden. Details finden Sie unter Referenz zur Klasse Ribbon weiter unten in diesem Thema.

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

Nachdem Sie Ihrem Projekt einRibbon (XML) -Element hinzugefügt haben, müssen Sie der Klasse ThisAddin, ThisWorkbook oder ThisDocument Code hinzufügen, der die CreateRibbonExtensibilityObject-Methode überschreibt und die Menüband-XML-Klasse an die Office-Anwendung 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, wie z. B. das Klicken auf eine Schaltfläche im Menüband, reagieren, 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. Beispielsweise können Sie eine Rückrufmethode erstellen, die aufgerufen wird, wenn ein Benutzer auf eine Schaltfläche auf dem 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 das Automatisieren eine Anwendung über das Menüband veranschaulicht, finden Sie unter Walkthrough: Creating 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 Menüband-Benutzeroberfläche von Office (2007) 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üband-Steuerelemente finden Sie im technischen Artikel Anpassen der Menüband-Benutzeroberfläche von Office (2007) 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.");
    }
}

Referenz zur Menüband-XML-Datei

Sie können Ihr benutzerdefiniertes Menüband durch Hinzufügen von Elementen und Attributen zur Menüband-XML-Datei definieren. 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 das Verhalten des benutzerdefinierten Menübands angeben. In der folgende Tabelle werden die Standardattribute in der Menüband-XML-Datei beschrieben.

Attribut Übergeordnetes Element Beschreibung
OnLoad customUI Gibt eine Methode an, die aufgerufen wird, wenn die Anwendung das Menüband lädt.
idMso Registerkarte Gibt eine integrierte Registerkarte an, die im Menüband angezeigt wird.
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 Menüband-Benutzeroberfläche von Office (2007) für Entwickler (Teil 2 von 3).

Referenz zur Klasse "Menüband"

Visual Studio generiert die Klasse "Menüband" in der Menüband-Codedatei. Fügen Sie dieser Klasse die Rückrufmethoden für Steuerelemente auf dem 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-Anwendungen 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 ggf. 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-Anwendungen rufen diese Methode beim Laden des benutzerdefinierten Menübands auf. Sie können dieses Feld verwenden, um das benutzerdefinierte Menüband dynamisch zu aktualisieren. Weitere Informationen finden Sie im technischen Artikel Anpassen der Menüband-Benutzeroberfläche von Office (2007) 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