Übersicht über Menüs und Symbolleisten

  • Artikel

Menüs und Symbolleisten sind die Art und Weise, wie Benutzer auf Befehle in Ihrer Erweiterung zugreifen. Sie sind praktische grafische Methoden, um Ihre Befehle benutzern zu präsentieren. In der Regel sind verwandte Befehle zusammen im gleichen Menü oder auf derselben Symbolleiste gruppiert.

Arbeiten mit Menüs und Symbolleisten

In dieser Übersicht werden die folgenden wichtigsten Szenarien für das Arbeiten mit Menüs und Symbolleisten behandelt:

Erstellen eines Menüs

Um ein Menü mit dem neuen Erweiterbarkeitsmodell zu erstellen, fügen Sie eine statische MenuConfiguration Eigenschaft hinzu, die die Klasse mit dem VisualStudioContribution Attribut schmückt. Diese statische Eigenschaft kann für jede Klasse in Ihrem Erweiterungsprojekt platziert werden. In den neuen Extensibility Model-Beispielen sind sie für die Extension Klasse zur Einfachheit vorhanden. Menüs ohne sichtbare untergeordnete Elemente werden in der Benutzeroberfläche nicht angezeigt.

[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
  [VisualStudioContribution]
  public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");
}

Die MenuConfiguration Klasse verfügt über einige Parameter, mit denen Sie vertraut sein sollten:

Parameter Type Erforderlich BESCHREIBUNG
DisplayName String Ja Der Standardanzeigename des Menüs. Umgeben Sie diese Zeichenfolge mit dem Zeichen "%", um die Lokalisierung dieser Zeichenfolge zu aktivieren. Siehe " Lokalisieren von Metadaten".
Tooltiptext String Nein Der Text, der als QuickInfo angezeigt werden soll, wenn das Menü mit dem Mauszeiger oder dem Fokus angezeigt wird. Umgeben Sie diese Zeichenfolge mit dem Zeichen "%", um die Lokalisierung dieser Zeichenfolge zu aktivieren. Siehe " Lokalisieren von Metadaten".
Positionierung CommandPlacement[] Nein Gibt die vorhandenen Gruppen in Visual Studio an, zu denen das Menü übergeordnet wird. Siehe " Einfügen eines Menüs in der IDE".
Children MenuChild[] Nein Beschreibt den Satz von Befehlen, Menüs und Gruppen, die diesem Menü übergeordnet werden sollen. Die Reihenfolge, in der diese Elemente im Array definiert sind, stellen die Reihenfolge dar, in der sie visuell in der IDE angezeigt werden. Anzeigen von Elementen in einem Menü

Platzieren eines Menüs in der IDE

Menüs werden auf die gleiche Weise wie Befehle in der IDE platziert. Siehe "Platzieren eines Befehls in der IDE".

public override MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Placements = new CommandPlacement[]
    {
        CommandPlacement.KnownPlacements.ToolsMenu
    },
};

Platzieren von Elementen in einem Menü

Das Platzieren eines Elements in einem Menü erfolgt durch Hinzufügen von Elementen zum Array auf dem ChildrenMenuConfiguration. Die Reihenfolge, in der Elemente diesem Array hinzugefügt werden, diktieren, wie diese Elemente visuell in der IDE angezeigt werden.

Platzieren von Befehlen in einem Menü

Das Platzieren von Befehlen in einem Menü erfolgt mithilfe der MenuChild.Command<T> Methode und ersetzt das Vorlagenargument durch den Klassennamen des Command.

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Command<MyCommand>(),
    },
};

Platzieren von Menüs in einem Menü

Das Platzieren von Menüs in einem Menü erfolgt mithilfe der MenuChild.Menu Methode, wobei eine andere als Parameter übergeben wird MenuConfiguration .

[VisualStudioContribution]
public static MenuConfiguration MyChildMenu => new("My Child Menu!");

[VisualStudioContribution]
public static MenuConfiguration MyParentMenu => new("My Parent Menu!")
{
    Children = new[]
    {
        MenuChild.Menu(MyChildMenu),
    },
};

Trennen von Menüelementen in Gruppen

Elemente innerhalb eines Menüs können gruppiert werden, indem sie zwischen MenuChild.Separator Elementen stehen. Visuell sieht dies wie eine dünne Linie zwischen zwei Elementen aus.

[VisualStudioContribution]
public static MenuConfiguration MyMenu1 => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        MenuChild.Menu(MyMenu2), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu2`
        MenuChild.Separator,
        MenuChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
        MenuChild.Menu(MyMenu3), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu3`
    },
};

Dies kann auch mithilfe der MenuChild.Group Methode zum Definieren einer Gruppeninline erreicht werden. Anschließend verwenden Sie die GroupChild Klasse, um übergeordnete Elemente für die Gruppe zu verwenden.

[VisualStudioContribution]
public static MenuConfiguration MyMenu1 => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Group(
            GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
            GroupChild.Menu(MyMenu2)), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu2`
        MenuChild.Group(
            GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
            GroupChild.Menu(MyMenu3)), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu3`
    },
};

In den beiden vorherigen Beispielen wäre das resultierende Menü in der IDE identisch. Das Menü MyMenu1 würde wie das Menü im folgenden Screenshot aussehen:

Screenshot of menu with separator.

Erstellen einer Symbolleiste

Um eine Symbolleiste mit dem neuen Erweiterbarkeitsmodell zu erstellen, fügen Sie eine statische ToolbarConfiguration Eigenschaft hinzu, die die Klasse mit dem VisualStudioContribution Attribut schmückt. Diese statische Eigenschaft kann für jede Klasse in Ihrem Erweiterungsprojekt platziert werden. In den neuen Extensibility Model-Beispielen sind sie für die Einfachheit der Extension Klasse vorhanden.

[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
  [VisualStudioContribution]
  public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%");
}

Wenn Sie die Placement Eigenschaft der ToolbarConfigurationnull Symbolleiste verlassen, wird sie auf der Standardsymbolleiste platziert und kann sichtbar gemacht werden, indem Sie die View -> Toolbars Symbolleiste im Menü auswählen.

ToolbarConfiguration-Klasse

Die ToolbarConfiguration Klasse verfügt über einige Eigenschaften, mit denen Sie vertraut sein sollten:

Eigenschaft Type Erforderlich BESCHREIBUNG
DisplayName String Ja Der Standardanzeigename der Symbolleiste. Umgeben Sie diese Zeichenfolge mit dem Zeichen "%", um die Lokalisierung dieser Zeichenfolge zu aktivieren. Siehe " Lokalisieren von Metadaten".
Tooltiptext String Nein Der Text, der als QuickInfo angezeigt werden soll, wenn die Symbolleiste mit dem Mauszeiger oder dem Fokus angezeigt wird. Umgeben Sie diese Zeichenfolge mit dem Zeichen "%", um die Lokalisierung dieser Zeichenfolge zu aktivieren. Siehe " Lokalisieren von Metadaten".
Positionierung CommandPlacement[] Nein Gibt die vorhandenen Gruppen in Visual Studio an, zu denen die Symbolleiste übergeordnet wird. Weitere Informationen finden Sie unter " Platzieren eines Befehls in der IDE". Wenn Sie diese Eigenschaft so verlassen, wie null sie die Symbolleiste auf der Standardsymbolleiste platzieren und sichtbar gemacht werden können, indem Sie die View -> Toolbars Symbolleiste im Menü auswählen
Children ToolbarChild[] Nein Beschreibt den Satz von Befehlen, Menüs und Gruppen, die dieser Symbolleiste übergeordnet werden sollen. Die Reihenfolge, in der diese Elemente im Array definiert sind, stellen die Reihenfolge dar, in der sie visuell in der IDE angezeigt werden. Unter " Elemente auf einer Symbolleiste platzieren" anzeigen

Platzieren von Elementen auf einer Symbolleiste

Das Platzieren von Befehlen auf einer Symbolleiste erfolgt mithilfe der ToolbarChild.Command<T> Methode, wobei das Vorlagenargument durch den Klassennamen des CommandTyps ersetzt wird.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Command<MyCommand>(),
    },
};

Trennen von Symbolleistenelementen in Gruppen

Elemente in einer Symbolleiste können gruppiert werden, indem sie zwischen ToolbarChild.Separator Elementen stehen. Visuell sieht dies wie eine dünne Linie zwischen zwei Elementen aus.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Separator,
        ToolbarChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

Dies kann auch mithilfe der ToolbarChild.Group Methode zum Definieren einer Gruppeninline erreicht werden. Anschließend verwenden Sie die ToolbarChild Klasse, um übergeordnete Elemente für die Gruppe zu verwenden.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Group(
            GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Group(
            GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

In den beiden Beispielen würde die resultierende Symbolleiste in der IDE identisch sein. Die Symbolleiste MyToolbar würde wie die Symbolleiste im folgenden Screenshot aussehen:

Screenshot of a toolbar with separator.

Erstellen einer Gruppe

Eine Gruppe ist eine visuelle Gruppierung von Elementen, in denen ein Trennzeichen zwischen den letzten und ersten Elementen benachbarter Gruppen platziert wird. In den obigen Abschnitten wird beschrieben, wie Gruppen innerhalb des Kontexts der Children Eigenschaft eines oder ToolbarConfigurationmehrerer MenuConfiguration Elemente erstellt werden. Es ist auch möglich, Gruppen innerhalb ihrer eigenen CommandGroupConfigurationzu definieren. Dies ist nützlich, wenn Sie eine Gruppe zu einem vorhandenen Menü oder einer vorhandenen Symbolleiste in Visual Studio überziehen möchten, ohne ihr eigenes Menü oder die eigene Symbolleiste zu definieren. Es kann auch hilfreich sein, wenn Sie Ihren Code auf eine Weise formatieren möchten, die Ihre Gruppendefinitionen von Ihren Menü- und Symbolleistendefinitionen trennt.

Um eine Gruppe mit dem neuen Erweiterbarkeitsmodell zu erstellen, fügen Sie eine statische CommandGroupConfiguration Eigenschaft hinzu. Diese statische Eigenschaft kann für jede Klasse in Ihrem Erweiterungsprojekt platziert werden. In den neuen Extensibility Model-Beispielen sind sie für die Einfachheit der Extension Klasse vorhanden. Wenn ein CommandGroupConfiguration Attribut angibt Placement, sollte es auch mit dem VisualStudioContribution Attribut versehen werden.

public static CommandGroupConfiguration MyGroup => new();

[VisualStudioContribution]
private static CommandGroupConfiguration MyGroupWithPlacement => new(GroupPlacement.KnownPlacements.ToolsMenu);

CommandGroupConfiguration-Klasse

Die CommandGroupConfiguration Klasse verfügt über einige Parameter, mit denen Sie vertraut sein sollten:

Parameter Type Erforderlich Beschreibung
Platzierung GroupPlacement Nein Gibt das vorhandene Menü oder die Symbolleiste in Visual Studio an, zu dem die Gruppe übergeordnet wird. Anzeigen unter " Platzieren einer Gruppe in der IDE".
Children GroupChild[] Nein Beschreibt den Satz von Befehlen und Menüs, die dieser Gruppe übergeordnet werden sollen. Die Reihenfolge, in der diese Elemente im Array definiert sind, stellen die Reihenfolge dar, in der sie visuell in der IDE angezeigt werden. Anzeigen von Elementen in einer Gruppe

Platzieren einer Gruppe in der IDE

Es gibt eine Reihe von gut definierten Stellen in Visual Studio, an denen Befehle platziert werden können. Diese Platzierungen werden durch die Eigenschaft CommandPlacement.KnownPlacements für die Klasse Commands.GroupPlacementdefiniert. Der aktuelle Satz von KnownPlacements ist:

  • ToolsMenu – Der Befehl wird in einer Gruppe unter dem Menü "Extras" auf oberster Ebene in Visual Studio platziert.
  • ViewOtherWindowsMenu – Der Befehl wird in einer Gruppe unter dem Menü "Ansicht"> der obersten Ebene " "Andere Windows" in Visual Studio platziert.
  • ExtensionsMenu – Der Befehl wird in Einer Gruppe unter dem Menü "Erweiterungen" der obersten Ebene in Visual Studio platziert.
[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup1 => new(GroupPlacement.KnownPlacements.ToolsMenu);

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup2 => new(GroupPlacement.KnownPlacements.ExtensionsMenu.WithPriority(0x100));

Platzieren von Elementen in einer Gruppe

Befehle und Menüs können mithilfe der Arrayeigenschaft auf der ChildrenCommandGroupConfiguration.

Platzieren von Befehlen in einer Gruppe

Das Platzieren von Befehlen in einer Gruppe erfolgt mithilfe der GroupChild.Command<T> Methode, wobei das Vorlagenargument durch den Klassennamen des Typs Commandersetzt wird.

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
    Children = new[]
    {
        GroupChild.Command<MyCommand>(),
    },
};

Platzieren von Menüs in einer Gruppe

Das Platzieren von Menüs in einer Gruppe erfolgt mithilfe der GroupChild.Menu Methode, die einen MenuConfiguration als Parameter übergibt.

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
    Children = new[]
    {
        GroupChild.Menu(MyMenu),
    },
};

Platzieren von Gruppen in einem Menü oder einer Symbolleiste

Das Platzieren einer Gruppe in einem Menü erfolgt mithilfe der MenuChild.Group Methode, indem ein CommandGroupConfiguration Parameter übergeben wird. Das Platzieren einer Gruppe auf einer Symbolleiste erfolgt mithilfe der ToolbarChild.Group Methode, indem ein CommandGroupConfiguration Parameter übergeben wird. Gruppen, die auf diese Weise menüs oder Symbolleisten zugeordnet sind, können nicht über die Placement Eigenschaft des CommandGroupConfiguration Satzes auf einen beliebigen Wert verfügen, außer null, und sie sollte nicht mit dem VisualStudioContribution Attribut versehen werden.

private static CommandGroupConfiguration MyGroup => new()
{
    Children = new[]
    {
        GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Group(MyGroup),
    },
};

private static CommandGroupConfiguration MyGroup => new()
{
    Children = new[]
    {
        GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
}

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Group(MyGroup),
    },
};

Platzierungsordnung (Priorität)

Platzierungen werden basierend auf dem Wert ihrer Priority Eigenschaft sortiert, wenn ein übergeordnetes Element zu einem in VSCT definierten Steuerelement relativ zu anderen Elementen, die der gleichen Gruppe, einem Menü oder einer Symbolleiste zugeordnet sind, zugeordnet wird. Bei der Priority-Eigenschaft handelt es sich um eine unsigned short. Der Standardwert Priority für ein CommandPlacement und GroupPlacement ist 0 und kann durch Aufrufen der CommandPlacement.WithPriority Methoden oder GroupPlacement.WithPriority Methoden geändert werden, wobei der gewünschte Priority Wert übergeben wird. Dies Priority kann auch mithilfe der CommandPlacement.VsctParent Methoden und GroupPlacement.VsctParent methoden festgelegt und direkt an die gewünschte Priority übergeben werden.

Die Priority Eigenschaft ist nicht beteiligt, wenn elemente zum Steuern über Konfigurationsobjekte mithilfe des VisualStudio.Extensibility-Modells definiert werden (d. h. die Gruppe, das Menü oder die Symbolleiste, für die übergeordnete Elemente definiert wurden, mithilfe CommandGroupConfigurationvon , MenuConfigurationoder ToolbarConfiguration).

GroupPlacement

GroupPlacement.KnownPlacements.ToolsMenu.WithPriority(0x0500);

// Parenting a group to the "Help" top level menu
GroupPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x0088, priority: 0x0500);

CommandPlacement

CommandPlacement.KnownPlacements.ToolsMenu.WithPriority(0x0500);

// Parenting a command to the "Help -> About" group
CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x016B, priority: 0x0801);