创作 .vsct 文件

  • 项目

本文档演示如何创作 .vsct 文件，以将菜单项、工具栏和其他用户界面（UI）元素添加到 Visual Studio 集成开发环境（IDE）。 将 UI 元素添加到尚未具有 .vsct 文件的 Visual Studio 包（VSPackage）时，请使用这些步骤。

对于新项目，建议使用 Visual Studio 包模板，因为它会生成一个 .vsct 文件，具体取决于所选内容，它已具有菜单命令、工具窗口或自定义编辑器所需的元素。 可以修改此 .vsct 文件以满足 VSPackage 的要求。 有关如何修改 .vsct 文件的详细信息，请参阅扩展菜单和命令中的示例。

创作文件

在这些阶段创作 .vsct 文件：为文件和资源创建结构、声明 UI 元素、将 UI 元素放在 IDE 中，并添加任何专用行为。

文件结构

.vsct 文件的基本结构是包含 Commands 元素和 Symbols 元素的 CommandTable 根元素。

创建文件结构

  1. 按照操作方法中的步骤将 .vsct 文件添加到项目：创建 .vsct 文件。

  2. 将所需的命名空间添加到 CommandTable 元素，如以下示例所示：

    <CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">

  3. 在元素中 CommandTable ，添加一个 Commands 元素来托管所有自定义菜单、工具栏、命令组和命令。 若要加载自定义 UI 元素，元素 Commands 必须将其 Package 属性设置为包的名称。

    在 Commands 元素之后，添加一个 Symbols 元素来定义包的 GUID，以及 UI 元素的名称和命令 ID。

包括 Visual Studio 资源

使用 Extern 元素访问定义 Visual Studio 命令的文件以及在 IDE 中放置 UI 元素所需的菜单。 如果使用包外部定义的命令，请使用 UsedCommands 元素通知 Visual Studio。

包括 Visual Studio 资源

  1. 在元素顶部 CommandTable ，为每个要引用的外部文件添加一个 Extern 元素，并将该属性设置为 href 文件的名称。 可以引用以下头文件来访问 Visual Studio 资源：

    • Stdidcmd.h：为 Visual Studio 公开的所有命令定义 ID。

    • Vsshlids.h：包含 Visual Studio 菜单的命令 ID。

  2. 如果包调用 Visual Studio 或其他包定义的任何命令，请在元素后面Commands添加一个UsedCommands元素。 使用 你调用的每个命令的 UsedCommand 元素填充此元素，该元素不是包的一部分。 将guid元素的UsedCommand和id属性设置为要调用的命令的 GUID 和 ID 值。

    有关如何查找 Visual Studio 命令的 GUID 和 ID 的详细信息，请参阅 Visual Studio 命令的 GUID 和 ID。 若要从其他包调用命令，请使用这些包的 .vsct 文件中定义的命令的 GUID 和 ID。

声明 UI 元素

在 .vsct 文件的节中Symbols声明所有新的 UI 元素。

声明 UI 元素

  1. 在元素中 Symbols ，添加三个 GuidSymbol 元素。 每个 GuidSymbol 元素都有一个 name 属性和一个 value 属性。 设置 name 属性，使其反映元素的用途。 该 value 属性采用 GUID。 （若要生成 GUID，在 工具 菜单，选择“ 创建 GUID”，然后选择“ 注册表格式”。

    第一个 GuidSymbol 元素表示包，通常没有子元素。 第二 GuidSymbol 个元素表示命令集，并将包含定义菜单、组和命令的所有符号。 第三 GuidSymbol 个元素表示图像存储，并包含命令的所有图标的符号。 如果没有使用图标的命令，则可以省略第三 GuidSymbol 个元素。

  2. 在表示命令集的 GuidSymbol 元素中，添加一个或多个 IDSymbol 元素。 其中每个都表示要添加到 UI 的菜单、工具栏、组或命令。

    对于每个 IDSymbol 元素，请将属性 name 设置为用于引用相应菜单、组或命令的名称，然后将元素设置为 value 表示其命令 ID 的十六进制数字。 没有两 IDSymbol 个具有相同父级的元素可以具有相同的值。

  3. 如果任一 IDSymbol UI 元素需要图标，请将每个图标的元素添加到表示图像存储的 GuidSymbol 元素。

在 IDE 中放置 UI 元素

菜单、组和按钮元素包含包中定义的所有菜单、组和命令的定义。 通过使用 父 元素（UI 元素定义的一部分）或使用 在其他地方定义的 CommandPlacement 元素，将这些菜单、组和命令放在 IDE 中。

每个 Menu元素 Group都有 Button 一个 guid 属性和一个 id 属性。 始终设置guid属性以匹配表示命令集的GuidSymbol元素的名称，并将该属性设置为id表示节中的Symbols菜单、组或命令的IDSymbol元素的名称。

定义 UI 元素

  1. 如果要定义任何新菜单、子菜单、快捷菜单或工具栏，请将元素添加到MenusCommands元素。 然后，对于要创建的每个菜单，向元素添加一个 Menu 元素 Menus 。

    guid设置元素的属性Menu，id然后将该type属性设置为所需的菜单类型。 还可以设置属性 priority 以在父组中建立菜单的相对位置。

    注意

    该 priority 属性不适用于工具栏和上下文菜单。

  2. Visual Studio IDE 中的所有命令都必须由命令组托管，这些命令是菜单和工具栏的直接子级。 如果要向 IDE 添加新菜单或工具栏，这些菜单或工具栏必须包含新的命令组。 还可以将命令组添加到现有菜单和工具栏，以便你可以直观地对命令进行分组。

    添加新的命令组时，必须先创建一个 Groups 元素，然后为每个命令组添加一个 Group 元素。

    guid设置每个Group元素的属性，id然后设置属性priority以在父菜单上建立组的相对位置。 有关详细信息，请参阅 创建可重用的按钮组。

  3. 如果要向 IDE 添加新命令，请将元素 Buttons 添加到 Commands 元素。 然后，对于每个命令，向元素添加一个 Button 元素 Buttons 。

    1. guid设置每个Button元素的属性，id然后将该type属性设置为所需的按钮类型。 还可以设置属性 priority 以在父组中建立命令的相对位置。

      注意

      用于 type="button" 工具栏上的标准菜单命令和按钮。

    2. 在Button元素中，添加包含 ButtonText 元素和 CommandName 元素的 Strings 元素。 该 ButtonText 元素为菜单项提供文本标签，或工具栏按钮的工具提示。 该 CommandName 元素提供命令的名称，以在命令中很好地使用。

    3. 如果命令将具有图标，请在Button元素中创建一个 Icon 元素，并将其和id属性设置为guidBitmap图标的元素。

      注意

      工具栏按钮必须具有图标。

    有关详细信息，请参阅 MenuCommands 与 OleMenuCommands。

  4. 如果任一命令需要图标，请将 Bitmaps 元素添加到 Commands 元素。 然后，对于每个图标，向 元素添加位图 元素 Bitmaps 。 这是指定位图资源的位置的位置。 有关详细信息，请参阅 向菜单命令添加图标。

    可以依赖父级结构来正确放置大多数菜单、组和命令。 对于非常大的命令集，或者当菜单、组或命令必须出现在多个位置时，建议指定命令放置。

依赖父级在 IDE 中放置 UI 元素

  1. 对于典型的父级，请在每个GroupMenu元素中创建一个Parent元素，并在Command包中定义的元素。

    元素的目标 Parent 是包含菜单、组或命令的菜单或组。

    1. 将 guid 属性设置为定义命令集的 GuidSymbol 元素的名称。 如果目标元素不是包的一部分，请使用该命令集的 guid，如相应的 .vsct 文件中定义。

    2. 设置属性 id 以匹配 id 目标菜单或组的属性。 有关 Visual Studio 公开的菜单和组的列表，请参阅 Visual Studio 菜单 的 GUID 和 ID 或 Visual Studio 工具栏的 GUID 和 ID。

    如果 IDE 中放置了大量 UI 元素，或者如果元素应出现在多个位置，请在 CommandPlacements 元素中定义其位置，如以下步骤所示。

使用命令放置在 IDE 中放置 UI 元素

  1. 在 Commands 元素后面添加 CommandPlacements 元素。

  2. 在元素中 CommandPlacements ，为每个要放置的菜单、组或命令添加一个 CommandPlacement 元素。

    每个 CommandPlacement 元素或 Parent 元素将一个菜单、组或命令放在一个 IDE 位置。 UI 元素只能有一个父元素，但它可以具有多个命令位置。 若要将 UI 元素放置在多个位置，请为每个位置添加一个 CommandPlacement 元素。

  3. guid将每个CommandPlacement元素的和id属性设置为宿主菜单或组，就像对元素一Parent样。 还可以设置属性 priority 以建立 UI 元素的相对位置。

    可以通过父级和命令放置来混合放置。 但是，对于非常大的命令集，建议仅使用命令放置。

添加专用行为

可以使用 CommandFlag 元素来修改菜单和命令的行为，例如更改菜单和命令的外观和可见性。 还可以通过使用 VisibilityConstraints 元素来影响命令何时可见，或使用 KeyBindings 元素添加键盘快捷方式。 某些类型的菜单和命令已内置了专用行为。

添加专用行为

  1. 若要使 UI 元素仅在某些 UI 上下文中可见，例如，加载解决方案时，请使用可见性约束。

    1. 在 Commands 元素后面添加 VisibilityConstraints 元素。

    2. 对于要约束的每个 UI 项，请添加一个 VisibilityItem 元素。

    3. 对于每个 VisibilityItem 元素，将 guid 和 id 属性设置为菜单、组或命令，然后将该 context 属性设置为所需的 UI 上下文，如类中 UIContextGuids80 定义。

  2. 若要在代码中设置 UI 项的可见性或可用性，请使用以下命令标志中的一个或多个：

    • DefaultDisabled

    • DefaultInvisible

    • DynamicItemStart

    • DynamicVisibility

    • NoShowOnMenuController

    • NotInTBList

    有关详细信息，请参阅 CommandFlag 元素。

  3. 若要更改元素的显示方式，或者动态更改其外观，请使用下列一个或多个命令标志：

    • AlwaysCreate

    • CommandWellOnly

    • DefaultDocked

    • DontCache

    • DynamicItemStart

    • FixMenuController

    • IconAndText

    • Pict

    • StretchHorizontally

    • TextMenuUseButton

    • TextChanges

    • TextOnly

    有关详细信息，请参阅 CommandFlag 元素。

  4. 若要更改元素在收到命令时的反应方式，请使用下列一个或多个命令标志：

    • AllowParams

    • CaseSensitive

    • CommandWellOnly

    • FilterKeys

    • NoAutoComplete

    • NoButtonCustomize

    • NoKeyCustomize

    • NoToolbarClose

    • PostExec

    • RouteToDocs

    • TextIsAnchorCommand

    有关详细信息，请参阅 CommandFlag 元素。

  5. 若要将依赖于菜单的键盘快捷方式附加到菜单上的菜单或项，请在菜单或菜单项的元素中添加 ButtonText 与字符（>）。 在父菜单打开时，后跟的字符是活动键盘快捷方式。

  6. 若要将独立于菜单的键盘快捷方式附加到命令，请使用 KeyBindings 元素。 有关详细信息，请参阅 KeyBinding 元素。

  7. 若要本地化菜单文本，请使用 LocCanonicalName 元素。 有关详细信息，请参阅 Strings 元素。

    某些菜单和按钮类型包括专用行为。 以下列表描述了一些专用菜单和按钮类型。 有关其他类型，请参阅types菜单、按钮和组合元素中的属性说明。

    • 组合框：组合框是可用于工具栏的下拉列表。 若要向 UI 添加组合框，请在Commands元素中创建组合元素。 然后，将元素添加到 Combos 要添加的每个组合框的元素 Combo 。 Combo 元素的属性和子 Button 元素与元素相同，并且具有 DefaultWidth 和 idCommandList 属性。 该 DefaultWidth 属性设置宽度（以像素为单位），属性 idCommandList 指向用于填充组合框的命令 ID。

    • 菜单控制器：菜单控制器是一个按钮，旁边有一个箭头。 单击箭头将打开列表。 若要将菜单控制器添加到 UI，请创建一个 Menu 元素并将其 type 属性 MenuController 设置为或 MenuControllerLatched根据所需的行为设置。 若要填充菜单控制器，请将其设置为元素的 Group 父级。 菜单控制器将在其下拉列表中显示该组的所有子级。

相关内容