Menu i paski narzędzi — omówienie

Menu i paski narzędzi to sposób, w jaki użytkownicy uzyskują dostęp do poleceń w rozszerzeniu. Są to wygodne graficzne sposoby prezentowania poleceń użytkownikom. Zazwyczaj powiązane polecenia są grupowane razem w tym samym menu lub na tym samym pasku narzędzi.

Praca z menu i paskami narzędzi

W tym omówieniu omówiono te najważniejsze scenariusze pracy z menu i paskami narzędzi:

• Tworzenie menu
• Umieszczanie elementów w menu
• Tworzenie paska narzędzi
• Umieszczanie elementów na pasku narzędzi
• Tworzenie grupy
• Umieszczanie elementów w grupie
• Umieszczanie grup w menu lub pasku narzędzi
• Kolejność umieszczania (priorytet)

Tworzenie menu

Aby utworzyć menu z nowym modelem rozszerzalności, dodaj właściwość statyczną MenuConfiguration , adorując klasę za pomocą atrybutu VisualStudioContribution . Tę właściwość statyczną można umieścić w dowolnej klasie w projekcie Extension. W nowych przykładach modelu rozszerzalności istnieją one w Extension klasie dla uproszczenia. Menu bez widocznych elementów podrzędnych nie będą widoczne w interfejsie użytkownika.

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

MenuConfiguration, klasa

Klasa MenuConfiguration ma kilka parametrów, które należy znać:

Parametr	Type	Wymagania	opis
Nazwa wyświetlana	String	Tak	Domyślna nazwa wyświetlana menu. Umieść ten ciąg znakiem "%", aby umożliwić lokalizowanie tego ciągu. Zobacz w temacie Lokalizowanie metadanych.
Tooltiptext	String	Nie	Tekst wyświetlany jako etykietka narzędzia po umieszczeniu wskaźnika myszy na menu lub na fokusie. Umieść ten ciąg znakiem "%", aby umożliwić lokalizowanie tego ciągu. Zobacz w temacie Lokalizowanie metadanych.
Miejsca docelowe	CommandPlacement[]	Nie.	Określa istniejące grupy w programie Visual Studio, do których będzie nadrzędne menu. Zobacz artykuł Place a menu in the IDE (Umieść menu w środowisku IDE).
Dzieci	MenuChild[]	Nie.	Opisuje zestaw poleceń, menu i grup, które powinny być nadrzędne dla tego menu. Kolejność, w której te elementy są zdefiniowane w tablicy, reprezentuje kolejność, w której będą wyświetlane wizualnie w środowisku IDE. Zobacz w menu Umieść elementy

Umieszczanie menu w środowisku IDE

Menu są umieszczane w środowisku IDE tak samo jak polecenia. Zobacz Place a command in the IDE (Umieść polecenie w środowisku IDE).

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

Umieszczanie elementów w menu

Umieszczanie elementu w menu odbywa się przez dodanie elementów do Children tablicy w elemencie MenuConfiguration. Kolejność dodawania elementów do tej tablicy określa sposób wizualnego wyświetlania tych elementów w środowisku IDE.

Umieszczanie poleceń w menu

Umieszczanie poleceń w menu odbywa się przy użyciu MenuChild.Command<T> metody , zastępując argument szablonu nazwą Commandklasy .

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

Umieszczanie menu w menu

Umieszczanie menu w menu odbywa się przy użyciu MenuChild.Menu metody , przekazując inny MenuConfiguration jako parametr.

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

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

Oddzielanie elementów menu do grup

Elementy w menu można grupować razem, mając między MenuChild.Separator sobą elementy. Wizualnie będzie to wyglądać jak cienka linia umieszczona między dwoma elementami.

[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`
    },
};

Można to również osiągnąć przy użyciu MenuChild.Group metody w celu zdefiniowania wbudowanej grupy. Następnie należy użyć GroupChild klasy do elementów nadrzędnych do grupy.

[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`
    },
};

W dwóch poprzednich przykładach wynikowe menu byłoby identyczne w środowisku IDE. Menu będzie wyglądać podobnie do menu MyMenu1 na poniższym zrzucie ekranu:

Tworzenie paska narzędzi

Aby utworzyć pasek narzędzi z nowym modelem rozszerzalności, dodaj właściwość statyczną ToolbarConfiguration , adorując klasę za pomocą atrybutu VisualStudioContribution . Tę właściwość statyczną można umieścić w dowolnej klasie w projekcie Extension. W nowych przykładach modelu rozszerzalności istnieją w Extension klasie dla uproszczenia.

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

Pozostawienie Placement właściwości ToolbarConfiguration as null spowoduje umieszczenie paska narzędzi na pasku paska narzędzi w warstwie Standardowa i może być widoczne, wybierając pasek narzędzi w View -> Toolbars menu.

ToolbarConfiguration, klasa

Klasa ToolbarConfiguration ma kilka właściwości, które należy znać:

Właściwość	Type	Wymagania	opis
Nazwa wyświetlana	String	Tak	Domyślna nazwa wyświetlana paska narzędzi. Umieść ten ciąg znakiem "%", aby umożliwić lokalizowanie tego ciągu. Zobacz w temacie Lokalizowanie metadanych.
Tooltiptext	String	Nie	Tekst, który ma być wyświetlany jako etykietka narzędzia po umieszczeniu na pasku narzędzi lub ustawieniu fokusu. Umieść ten ciąg znakiem "%", aby umożliwić lokalizowanie tego ciągu. Zobacz w temacie Lokalizowanie metadanych.
Miejsca docelowe	CommandPlacement[]	Nie.	Określa istniejące grupy w programie Visual Studio, do których zostanie nadrzędny pasek narzędzi. Zobacz w temacie Place a command in the IDE (Umieść polecenie w środowisku IDE). Pozostawienie tej właściwości w taki sposób, jak null spowoduje umieszczenie paska narzędzi na pasku paska narzędzi w warstwie Standardowa i może być widoczne, wybierając pasek narzędzi w View -> Toolbars menu
Dzieci	ToolbarChild[]	Nie.	Opisuje zestaw poleceń, menu i grup, które powinny być nadrzędne dla tego paska narzędzi. Kolejność, w której te elementy są zdefiniowane w tablicy, reprezentuje kolejność, w której będą wyświetlane wizualnie w środowisku IDE. Zobacz artykuł Place items on a toolbar (Umieść elementy na pasku narzędzi)

Umieszczanie elementów na pasku narzędzi

Umieszczanie poleceń na pasku narzędzi odbywa się przy użyciu ToolbarChild.Command<T> metody , zastępując argument szablonu nazwą Commandklasy .

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

Oddzielanie elementów paska narzędzi do grup

Elementy na pasku narzędzi można grupować, łącząc ToolbarChild.Separator elementy między elementami. Wizualnie będzie to wyglądać jak cienka linia umieszczona między dwoma elementami.

[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`
    },
};

Można to również osiągnąć przy użyciu ToolbarChild.Group metody w celu zdefiniowania wbudowanej grupy. Następnie należy użyć ToolbarChild klasy do elementów nadrzędnych do grupy.

[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`
    },
};

W dwóch przykładach w tym miejscu wynikowy pasek narzędzi będzie identyczny w środowisku IDE. Pasek narzędzi będzie wyglądać podobnie do paska narzędzi MyToolbar na poniższym zrzucie ekranu:

Tworzenie grupy

Grupa to wizualne grupowanie elementów, w których separator zostanie umieszczony między ostatnimi i pierwszymi elementami sąsiednich grup. W powyższych sekcjach opisano sposób tworzenia grup wewnątrz kontekstu Children właściwości obiektu MenuConfiguration lub ToolbarConfiguration. Istnieje również możliwość definiowania grup wewnątrz własnych CommandGroupConfigurationelementów . Jest to przydatne, gdy chcesz utworzyć grupę w istniejącym menu lub pasku narzędzi w programie Visual Studio bez definiowania własnego menu lub paska narzędzi. Może to być również przydatne, jeśli chcesz sformatować kod w sposób, który oddziela definicje grup od definicji menu i paska narzędzi.

Aby utworzyć grupę przy użyciu nowego modelu rozszerzalności, dodaj właściwość statyczną CommandGroupConfiguration . Tę właściwość statyczną można umieścić w dowolnej klasie w projekcie Extension. W nowych przykładach modelu rozszerzalności istnieją w Extension klasie dla uproszczenia. Jeśli element CommandGroupConfiguration określa Placementparametr , należy go również ozdobić atrybutem VisualStudioContribution .

public static CommandGroupConfiguration MyGroup => new();

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

CommandGroupConfiguration, klasa

Klasa CommandGroupConfiguration ma kilka parametrów, które należy znać:

Parametr	Type	Wymagania	opis
Umieszczenie	GroupPlacement	Nie.	Określa istniejące menu lub pasek narzędzi w programie Visual Studio, do którego grupa zostanie nadrzędna. Zobacz w temacie Umieszczanie grupy w środowisku IDE.
Dzieci	GroupChild[]	Nie.	Opisuje zestaw poleceń i menu, które powinny być nadrzędne dla tej grupy. Kolejność, w której te elementy są zdefiniowane w tablicy, reprezentuje kolejność, w której będą wyświetlane wizualnie w środowisku IDE. Zobacz artykuł Place items on a group (Umieszczanie elementów w grupie)

Umieszczanie grupy w środowisku IDE

W programie Visual Studio znajduje się zestaw dobrze zdefiniowanych miejsc, w których można umieszczać polecenia. Te umieszczania są definiowane przez właściwość CommandPlacement.KnownPlacements klasy Commands.GroupPlacement. Bieżący zestaw to KnownPlacements :

• ToolsMenu - Polecenie zostanie umieszczone w grupie w menu "Narzędzia" najwyższego poziomu w programie Visual Studio.
• ViewOtherWindowsMenu — Polecenie zostanie umieszczone w grupie w menu "Widok" najwyższego poziomu —> "Inne okna" w programie Visual Studio.
• ExtensionsMenu — Polecenie zostanie umieszczone w grupie w menu "Rozszerzenia" najwyższego poziomu w programie Visual Studio.

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup1 => new(GroupPlacement.KnownPlacements.ToolsMenu);

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

Umieszczanie elementów w grupie

Polecenia i menu można umieszczać w grupach przy użyciu Children właściwości tablicy w obiekcie CommandGroupConfiguration.

Umieszczanie poleceń w grupie

Umieszczanie poleceń w grupie odbywa się przy użyciu GroupChild.Command<T> metody , zastępując argument szablonu nazwą Commandklasy .

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

Umieszczanie menu w grupie

Umieszczanie menu w grupie odbywa się przy użyciu GroupChild.Menu metody , przekazując MenuConfiguration jako parametr.

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

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

Umieszczanie grup w menu lub pasku narzędzi

Umieszczenie grupy w menu odbywa się przy użyciu MenuChild.Group metody , przekazując CommandGroupConfiguration jako parametr. Umieszczenie grupy na pasku narzędzi odbywa się przy użyciu ToolbarChild.Group metody , przekazując CommandGroupConfiguration jako parametr. Grupy nadrzędne do menu lub pasków narzędzi w ten sposób nie mogą mieć Placement właściwości CommandGroupConfiguration zestawu do żadnej wartości z wyjątkiem null, i nie powinny być ozdobione atrybutem VisualStudioContribution .

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),
    },
};

Kolejność umieszczania (priorytet)

Umieszczania są uporządkowane na podstawie wartości właściwości Priority , gdy element nadrzędny do kontrolki zdefiniowanej w programie VSCT jest powiązany z innymi elementami nadrzędnymi dla tej samej grupy, menu lub paska narzędzi. Właściwość Priority to unsigned short. Wartość domyślna elementu i jest i może zostać zmodyfikowana przez wywołanie CommandPlacement.WithPriority metody lubGroupPlacement.WithPriority, przekazując żądaną Priority wartość.0GroupPlacementCommandPlacementPriority Element Priority można również ustawić przy użyciu CommandPlacement.VsctParent metod i GroupPlacement.VsctParent i i przekazując żądany Priority bezpośrednio.

Właściwość nie jest związana Priority z elementami nadrzędnymi do kontrolek zdefiniowanych za pośrednictwem obiektów konfiguracji przy użyciu modelu VisualStudio.Extensibility (tj. grupy, menu lub paska narzędzi, do którego element nadrzędny został zdefiniowany przy użyciu metody CommandGroupConfiguration, MenuConfigurationlub 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);