Vue d’ensemble des menus et des barres d’outils
Les menus et les barres d’outils sont la façon dont les utilisateurs accèdent aux commandes dans votre extension. Il s’agit de méthodes graphiques pratiques pour présenter vos commandes aux utilisateurs. En règle générale, les commandes associées sont regroupées dans le même menu ou la même barre d’outils.
Utiliser des menus et des barres d’outils
Cette vue d’ensemble couvre les principaux scénarios d’utilisation des menus et des barres d’outils :
- Créer un menu
- Placer des éléments dans un menu
- Créer une barre d’outils
- Placer des éléments dans une barre d’outils
- Création d’un groupe
- Placer des éléments sur un groupe
- Placer des groupes dans un menu ou une barre d’outils
- Classement de placement (priorité)
Créer un menu
Pour créer un menu avec le nouveau modèle d’extensibilité, ajoutez une propriété statique MenuConfiguration
, ornant la classe avec l’attribut VisualStudioContribution
. Cette propriété statique peut être placée sur n’importe quelle classe dans votre projet d’extension. Dans les nouveaux exemples de modèle d’extensibilité, ils existent sur la Extension
classe par souci de simplicité. Les menus sans enfants visibles ne seront pas visibles dans l’interface utilisateur.
[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");
}
Classe MenuConfiguration
La MenuConfiguration
classe a quelques paramètres que vous devez connaître :
Paramètre | Type | Requise | Description |
---|---|---|---|
Nom d’affichage | Chaîne | Oui | Nom d’affichage par défaut de votre menu. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées. |
TooltipText | Chaîne | Non | Texte à afficher en tant qu’info-bulle lorsque le menu est pointé ou concentré. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées. |
Dispositions | CommandPlacement[] | Non | Spécifie les groupes existants dans Visual Studio auxquels le menu sera parenté. Voir à l’adresse Placer un menu dans l’IDE. |
Children | MenuChild[] | Non | Décrit l’ensemble de commandes, de menus et de groupes qui doivent être parentés de ce menu. L’ordre dans lequel ces éléments sont définis dans le tableau représente l’ordre dans lequel ils apparaîtront visuellement dans l’IDE. Voir à l’emplacement des éléments dans un menu |
Placer un menu dans l’IDE
Les menus sont placés dans l’IDE de la même façon que les commandes. Consultez Placer une commande dans l’IDE.
public override MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
Placements = new CommandPlacement[]
{
CommandPlacement.KnownPlacements.ToolsMenu
},
};
Placer des éléments dans un menu
Le placement sur l’élément d’un menu est effectué en ajoutant des éléments au Children
tableau sur le MenuConfiguration
. L’ordre dans lequel les éléments sont ajoutés à ce tableau détermine la façon dont ces éléments seront affichés visuellement dans l’IDE.
Placer des commandes dans un menu
Le placement de commandes dans un menu est effectué à l’aide de la MenuChild.Command<T>
méthode, en remplaçant l’argument de modèle par le nom de classe du Command
.
[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
Children = new[]
{
MenuChild.Command<MyCommand>(),
},
};
Placer des menus dans un menu
Le placement de menus sur un menu est effectué à l’aide de la MenuChild.Menu
méthode, en passant un autre MenuConfiguration
en tant que paramètre.
[VisualStudioContribution]
public static MenuConfiguration MyChildMenu => new("My Child Menu!");
[VisualStudioContribution]
public static MenuConfiguration MyParentMenu => new("My Parent Menu!")
{
Children = new[]
{
MenuChild.Menu(MyChildMenu),
},
};
Séparation des éléments de menu en groupes
Les éléments d’un menu peuvent être regroupés en ayant un MenuChild.Separator
élément à l’autre. Visuellement, cela ressemblera à une ligne mince placée entre deux éléments.
[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`
},
};
Cela peut également être effectué à l’aide de la MenuChild.Group
méthode pour définir un groupe inline. Vous utiliserez ensuite la GroupChild
classe pour les éléments parents dans le groupe.
[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`
},
};
Dans les deux exemples précédents, le menu résultant serait identique dans l’IDE. Le menu ressemblerait au menu MyMenu1
dans la capture d’écran suivante :
Créer une barre d'outils
Pour créer une barre d’outils avec le nouveau modèle d’extensibilité, ajoutez une propriété statique ToolbarConfiguration
, ornant la classe avec l’attribut VisualStudioContribution
. Cette propriété statique peut être placée sur n’importe quelle classe dans votre projet d’extension. Dans les nouveaux exemples de modèle d’extensibilité, ils existent sur la Extension
classe par souci de simplicité.
[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%");
}
Laissant la Placement
propriété de la ToolbarConfiguration
barre d’outils telle que null
celle-ci placera la barre d’outils standard et peut être rendue visible en sélectionnant la barre d’outils dans le View -> Toolbars
menu.
Classe ToolbarConfiguration
La ToolbarConfiguration
classe a quelques propriétés que vous devez connaître :
Propriété | Type | Requise | Description |
---|---|---|---|
Nom d’affichage | Chaîne | Oui | Nom d’affichage par défaut de votre barre d’outils. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées. |
TooltipText | Chaîne | Non | Texte à afficher en tant qu’info-bulle lorsque la barre d’outils est pointée ou prioritaire. Entourez cette chaîne avec le caractère « % » pour permettre la localisation de cette chaîne. Voir à l’adresse Localiser les métadonnées. |
Dispositions | CommandPlacement[] | Non | Spécifie les groupes existants dans Visual Studio auxquels la barre d’outils sera parentée. Voir à l’adresse Placer une commande dans l’IDE. Laissant cette propriété telle quelle null placera la barre d’outils dans la barre d’outils standard et peut être rendue visible en sélectionnant la barre d’outils dans le View -> Toolbars menu |
Children | ToolbarChild[] | Non | Décrit l’ensemble de commandes, de menus et de groupes qui doivent être parentés de cette barre d’outils. L’ordre dans lequel ces éléments sont définis dans le tableau représente l’ordre dans lequel ils apparaîtront visuellement dans l’IDE. Voir à l’emplacement des éléments dans une barre d’outils |
Placer des éléments dans une barre d’outils
Le placement de commandes dans une barre d’outils est effectué à l’aide de la ToolbarChild.Command<T>
méthode, en remplaçant l’argument de modèle par le nom de classe du Command
.
[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
Children = new[]
{
ToolbarChild.Command<MyCommand>(),
},
};
Séparation des éléments de barre d’outils en groupes
Les éléments d’une barre d’outils peuvent être regroupés en ayant un ToolbarChild.Separator
élément à l’autre. Visuellement, cela ressemblera à une ligne mince placée entre deux éléments.
[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`
},
};
Cela peut également être effectué à l’aide de la ToolbarChild.Group
méthode pour définir un groupe inline. Vous utiliserez ensuite la ToolbarChild
classe pour les éléments parents dans le groupe.
[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`
},
};
Dans les deux exemples ici, la barre d’outils résultante serait identique dans l’IDE. La barre d’outils MyToolbar
ressemble à la barre d’outils dans la capture d’écran ci-dessous :
Créer un groupe
Un groupe est un regroupement visuel d’éléments dans lequel un séparateur sera placé entre les derniers et les premiers éléments des groupes adjacents. Dans les sections ci-dessus, il explique comment créer des groupes à l’intérieur du contexte de la Children
propriété d’un MenuConfiguration
ou ToolbarConfiguration
. Il est également possible de définir des groupes à l’intérieur de leur propre CommandGroupConfiguration
. Cela est utile lorsque vous souhaitez parenter un groupe d’un menu ou d’une barre d’outils existant dans Visual Studio sans définir votre propre menu ou barre d’outils. Il peut également être utile si vous souhaitez mettre en forme votre code d’une manière qui sépare vos définitions de groupe de vos définitions de menu et de barre d’outils.
Pour créer un groupe avec le nouveau modèle d’extensibilité, ajoutez une propriété statique CommandGroupConfiguration
. Cette propriété statique peut être placée sur n’importe quelle classe dans votre projet d’extension. Dans les nouveaux exemples de modèle d’extensibilité, ils existent sur la Extension
classe par souci de simplicité. Si un spécifie un CommandGroupConfiguration
Placement
, il doit également être orné de l’attribut VisualStudioContribution
.
public static CommandGroupConfiguration MyGroup => new();
[VisualStudioContribution]
private static CommandGroupConfiguration MyGroupWithPlacement => new(GroupPlacement.KnownPlacements.ToolsMenu);
Classe CommandGroupConfiguration
La CommandGroupConfiguration
classe a quelques paramètres que vous devez connaître :
Paramètre | Type | Requise | Description |
---|---|---|---|
Placement | GroupPlacement | Non | Spécifie le menu ou la barre d’outils existant dans Visual Studio auquel le groupe sera parenté. Consultez l’article Placer un groupe dans l’IDE. |
Children | GroupChild[] | Non | Décrit l’ensemble de commandes et de menus qui doivent être parentés de ce groupe. L’ordre dans lequel ces éléments sont définis dans le tableau représente l’ordre dans lequel ils apparaîtront visuellement dans l’IDE. Voir à l’emplacement des éléments d’un groupe |
Placer un groupe dans l’IDE
Il existe un ensemble d’emplacements bien définis dans Visual Studio où les commandes peuvent être placées. Ces placements sont définis par la propriété CommandPlacement.KnownPlacements
sur la classe Commands.GroupPlacement
. L’ensemble actuel est KnownPlacements
:
ToolsMenu
- La commande est placée dans un groupe sous le menu « Outils » de niveau supérieur dans Visual Studio.ViewOtherWindowsMenu
- La commande est placée dans un groupe sous le menu « Affichage » de niveau supérieur -> « Autres fenêtres » dans Visual Studio.ExtensionsMenu
- La commande est placée dans un groupe sous le menu « Extensions » de niveau supérieur dans Visual Studio.
[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup1 => new(GroupPlacement.KnownPlacements.ToolsMenu);
[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup2 => new(GroupPlacement.KnownPlacements.ExtensionsMenu.WithPriority(0x100));
Placer des éléments sur un groupe
Les commandes et les menus peuvent être placés sur des groupes à l’aide de la Children
propriété de tableau sur le CommandGroupConfiguration
.
Placer des commandes sur un groupe
Le placement de commandes sur un groupe est effectué à l’aide de la GroupChild.Command<T>
méthode, en remplaçant l’argument de modèle par le nom de classe du Command
.
[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
Children = new[]
{
GroupChild.Command<MyCommand>(),
},
};
Placer des menus sur un groupe
Le placement de menus sur un groupe est effectué à l’aide de la GroupChild.Menu
méthode, en passant un MenuConfiguration
paramètre en tant que paramètre.
[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");
[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
Children = new[]
{
GroupChild.Menu(MyMenu),
},
};
Placer des groupes dans un menu ou une barre d’outils
Placer un groupe dans un menu est effectué à l’aide de la MenuChild.Group
méthode, en passant un CommandGroupConfiguration
paramètre en tant que paramètre. Le placement d’un groupe dans une barre d’outils s’effectue à l’aide de la ToolbarChild.Group
méthode, en passant un CommandGroupConfiguration
paramètre en tant que paramètre. Les groupes parentés sur les menus ou les barres d’outils de cette façon ne peuvent pas avoir la propriété de l’ensemble Placement
CommandGroupConfiguration
sur une valeur sauf null
, et il ne doit pas être orné de l’attribut 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),
},
};
Classement de placement (priorité)
Les placements sont classés en fonction de la valeur de leur Priority
propriété lorsqu’elles sont parentées d’un contrôle défini dans VSCT, par rapport aux autres éléments parentés au même groupe, menu ou barre d’outils. La propriété Priority
est un unsigned short
. La valeur par défaut d’un et peut être modifiée en appelant ou CommandPlacement.WithPriority
GroupPlacement.WithPriority
en passant la valeur souhaitéePriority
.0
GroupPlacement
CommandPlacement
Priority
Il Priority
peut également être défini à l’aide des méthodes et GroupPlacement.VsctParent
de la CommandPlacement.VsctParent
transmission directe du contenu souhaitéPriority
.
La Priority
propriété n’est pas impliquée lors du parentage d’éléments à des contrôles définis via des objets de configuration à l’aide du modèle VisualStudio.Extensibility (c’est-à-dire le groupe, le menu ou la barre d’outils parentée à l’aide CommandGroupConfiguration
de , MenuConfiguration
ou 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);