Vspackage 如何将用户界面元素到 IDE

VSPackage 中添加用户界面 (UI)元素，例如，菜单、工具栏和工具窗口，到 Visual Studio 集成开发环境 (IDE)。

体系结构原则

使 VSPackage 自定义的规则集和结构 UI 名为 命令表结构。 命令表结构基于以下设计原则:

• 不应混乱 UI 或混淆。

• UI 应是动态的，不静态的。

• UI 应自定义。

• UI 应非常有用。

不应混乱 UI 或混淆。

• 若干 Vspackage 在承载 VSPackage 的 Visual Studio 会话中可以安装。 在 VSPackage 添加命令时，它不可中断之前安装的 sharepoint 项目服务，但是，它还应当让其功能另一 Vspackage 并使其提供功能 "。

• 每个菜单，它通过使用主菜单栏、子菜单或快捷菜单，是否捕获，可以包含由其他 Vspackage 提供的菜单项。 因此，小心不阻止拥挤 UI。 如果许多命令同时显示， UI 可能模糊处理用户。

UI 应是动态的，不静态的

• 命令可以根据基础数据和当前用户活动的状态随时显示或隐藏，。

• 必须启用 VSPackage 更改用户界面项的标签，并且其组合框或菜单内容。

• UI 项可能必须添加或移除何时使用 VSPackage。

• UI 项可能需要额外调用 VSPackage 填充其值或检测其当前状态。 这些项的示例包括列表最近使用过的文件 (MRU)、组合框和颜色选择器或纹理的。

• 它可以改进用户体验添加命令到其他 Vspackage 的菜单。 例如，因此，如果您提供的命令类似于 复制，可以在 复制 显示的每个 VSPackage 使该命令。

应自定义 UI

• ，例如，任何时候，用户可以通过将按钮添加到工具窗口或重新排列菜单自定义在 VSPackage 中的 UI 元素。 但是，在某些情况下，您可能希望禁用自定义。

• 某些命令可用使用自定义;即命令可能不可用在菜单或工具栏使用 自定义 对话框，，直至用户添加它。

• 任何时候，用户可以使用来自 Visual Studio 和其他 Vspackage 指令一起的键盘快捷方式自定义命令的键盘快捷键，。

• 使用 命令 窗口中，命令可以执行。 因此， IDE 必须知道哪个指令对应于特定命令标签。 IDE 完成此通过使用称为 规范化的进程，移除空格压缩命令名到单词。 例如， “ Open 的规范化为 “FileOpen。

UI 应十分有用。

• 大多数 UI 项应当让工具提示。

• 为了提供更好的性能，因此，只有当其功能之一调用时， VSPackage 应加载。 这称为 “延迟加载”。

• 对 VSPackage 所需的 IDE 中添加应该是可本地化。

• 可以使用 Visual Studio 中包括的位图也可以提供拥有。

Visual Studio 命令表结构

正如，命令表结构支持前面体系结构原则。 在命令表结构的抽象、数据结构和工具后原则如下所示:

• 有三种基本项目:菜单、命令和组。 菜单在 UI 中显示为菜单上子菜单、工具栏或工具窗口。 命令是用户在 IDE 中执行，因此，它们可以显示菜单项，按钮，列表框，或其他控件的过程。 组是菜单和命令的容器。

• 每个项目是描述项目、其优先级相对于其他项目和标志来修改其行为的定义中指定。

• 每个项目都有描述项的父级中的位置。 项可以有多个父级，因此，它能够于 UI 的多个显示的位置。

  每个命令必须具有组作为其父级，因此，即使它是独生子在该组中。 每个标准菜单还必须具有父组。 工具栏和工具窗口作为其父级。 团队可以使用作为其父 Visual Studio 主菜单栏，或者所有菜单、工具栏或工具窗口。

项定义

. Vsct 文件以 XML 格式。 .vsct 文件定义包的 UI 元素并确定这些元素的位置显示在 IDE 中。 每个菜单、组或命令在包首先分配 GUID 和 ID。 Symbols 部分。 在 .vsct 文件的其余部分中，每个菜单、命令和组由其 GUID 和 ID 组合决定的。 ，当 菜单命令 在模板时，已选择下面的示例演示一个典型的 Symbols 部分标记为生成的由 Visual Studio 包 " 模板。

<Symbols>
  <!-- This is the package guid. -->
  <GuidSymbol name="guidMenuTextPkg" value="{b1253bc6-d266-402b-89e7-5e3d3b22c746}" />

  <!-- This is the guid used to group the menu commands together -->
  <GuidSymbol name="guidMenuTextCmdSet" value="{a633d4e4-6c65-4436-a138-1abeba7c9a69}">

    <IDSymbol name="MyMenuGroup" value="0x1020" />
    <IDSymbol name="cmdidMyCommand" value="0x0100" />
  </GuidSymbol>

  <GuidSymbol name="guidImages" value="{53323d9a-972d-4671-bb5b-9e418480922f}" >
    <IDSymbol name="bmpPic1" value="1" />
    <IDSymbol name="bmpPic2" value="2" />
    <IDSymbol name="bmpPicSearch" value="3" />
    <IDSymbol name="bmpPicX" value="4" />
    <IDSymbol name="bmpPicArrows" value="5" />
  </GuidSymbol>
</Symbols>

Symbols 部分的顶级元素是 GuidSymbol 元素。 GuidSymbol 元素 IDE 用于标识包及其组成部分对 GUID 的映射名称。

备注

GUID 由 Visual Studio 自动包模板生成。可以通过单击 创建 GUID 还会创建一个唯一 GUID 在 工具 菜单。

第一个 GuidSymbol 元素， “guid] [PackageName Pkg”，为包的 GUID。 Visual Studio 使用加载包为 GUID。 通常，它没有子元素。

按照约定，菜单和命令分组在秒 GuidSymbol 元素下， “GUID PackageName [] CmdSet”，并且，位图在第三 GuidSymbol 元素下， “guidImages”。 您不必遵循此约定，但是，每个菜单、组、命令和位图必须是 GuidSymbol 元素的子元素。

在第二个 GuidSymbol 元素，表示设置的包命令，其中是几个 IDSymbol 元素。 每 IDSymbol 元素 映射一个名称为数值，它可能包含菜单，设置为命令的组，或者顺序。 在第三个 GuidSymbol 元素的 IDSymbol 元素表示能用作图标为命令的位图。 由于 GUID/ID 对必须是唯一的。应用程序，不相同 GuidSymbol 元素的两种子可以具有相同的值。

菜单、组和命令

当菜单、组或命令具有 GUID 和 ID 时，可以添加到 IDE。 每个 UI 元素必须具有以下内容:

• 匹配 GuidSymbol 元素的名称 guid 属性 UI 元素定义下的。

• 与关联的 IDSymbol 元素的名称 id 属性。

  同时， guid 和 id 属性由 UI 元素组成 签名 。

• 在其父菜单或组中确定 UI 元素位置的 priority 属性。

• 具有 guid 和 id 属性指定父菜单或组的签名 Parent 元素 。

菜单

每个菜单定义为 Menus 部分的 Menu 元素 。 菜单必须具有 guid、 id和 priority 属性和 Parent 元素、因此以下附加属性和子项:

• 指定的 type 属性菜单是否应显示在 IDE 作为一个菜单或作为工具栏。

• Strings 元素 包含 ButtonText 元素，在 IDE 中指定菜单的标题和 CommandName 元素，指定名称用于访问的 命令 windows 菜单。

• 可选标志。 Command Flag 元素 可以出现在菜单定义更改其外观或行为在 IDE。

，除非它是一个可停靠的元素 (如工具栏，每个 Menu 元素必须具有机组用作其父级。 一个可停靠菜单是其自身的父级。 有关菜单和值的更多信息 type 属性，请参见 Menu 元素 文档。

下面的示例在 工具 菜单旁边显示在 Visual Studio 菜单栏上的菜单，。

<Menu guid="guidTopLevelMenuCmdSet"
id="TopLevelMenu" priority="0x700" type="Menu">
  <Parent guid="guidSHLMainMenu"
          id="IDG_VS_MM_TOOLSADDINS" />
  <Strings>
    <ButtonText>TestMenu</ButtonText>
    <CommandName>TestMenu</CommandName>
  </Strings>
</Menu>

Groups

组是在 .vsct 文件的 Groups 节中定义的项目。 组是容器。 它们不会显示在除为分隔线的 IDE 在菜单。 因此， Group 元素 由其签名、优先级别和父只定义的。

团队可以具有菜单，另一个组或本身作为父级。 但是，父通常是菜单或工具栏。 在前面的示例中的菜单是 IDG_VS_MM_TOOLSADDINS 组的子级，因此，该组是 Visual Studio 菜单栏的子级。 下面的示例中的组是菜单的子级在前面的示例中的。

 <Group guid="guidTopLevelMenuCmdSet" id="MyMenuGroup"
priority="0x0600">
   <Parent guid="guidTopLevelMenuCmdSet" id="TopLevelMenu"/>
 </Group>

由于它是菜单的一部分，本组通常包含命令。 但是，它也可以包含其他菜单。 这是子菜单的定义方式，，如下面的示例所示。

<Menu guid="guidTopLevelMenuCmdSet" id="SubMenu"
priority="0x0100" type="Menu">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup"/>
  <Strings>
    <ButtonText>Sub Menu</ButtonText>
    <CommandName>Sub Menu</CommandName>
  </Strings>
</Menu>

命令

提供对 IDE 的命令定义为 Button 元素 或 Combo 元素。 若要将出现在菜单或工具栏，命令必须具有机组用作其父级。

按钮

按钮。 Buttons 部分定义。 所有菜单项、按钮，或者用户单击执行单个命令的其他组件叫做按钮。 这些按钮类型也可以包含列表功能。 按钮具有指定位图 GUID 和 ID 表示 IDE 中的按钮的相同需要的和可选特性菜单包含，也可以具有 Icon 元素 。 有关按钮及其属性的更多信息，请参见 Buttons 元素 文档。

下面的示例中的按钮是组的子级在前面的示例中的和显示 IDE 作为该组父菜单的菜单项。

<Button guid="guidTopLevelMenuCmdSet" id="cmdidTestCommand" priority="0x0100" type="Button">
  <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" />
  <Icon guid="guidImages" id="bmpPic1" />
  <Strings>
    <CommandName>cmdidTestCommand</CommandName>
    <ButtonText>Test Command</ButtonText>
  </Strings>
</Button>

Combos

Combos 在 Combos 部分定义。 每个 Combo 元素表示 IDE 中的下拉列表框。 列表框可能存在也可能是不可写的用户，根据 type 属性的值组合。 Combos 具有按钮具有相同的组件和行为，也可以具有以下附加属性:

• 指定像素宽度的 defaultWidth 属性。

• 指定列表包含项目在列表框中显示的 idCommandList 属性。 在包含组合的同一 GuidSymbol 节点命令列出必须声明。

下面的示例定义一个组合元素。

<Combos>
  <Combo guid="guidFirstToolWinCmdSet"
         id="cmdidWindowsMediaFilename"
         priority="0x0100" type="DynamicCombo"
         idCommandList="cmdidWindowsMediaFilenameGetList"
         defaultWidth="130">
    <Parent guid="guidFirstToolWinCmdSet"
            id="ToolbarGroupID" />
    <CommandFlag>IconAndText</CommandFlag>
    <CommandFlag>CommandWellOnly</CommandFlag>
    <CommandFlag>StretchHorizontally</CommandFlag>
    <Strings>
      <CommandName>Filename</CommandName>
      <ButtonText>Enter a Filename</ButtonText>
    </Strings>
  </Combo>
</Combos>

位图

与图标时要显示的命令必须包括使用其 GUID 和 ID.，引用位图的 Icon 元素 每个位图定义为 Bitmaps 部分的 Bitmap 元素 。 Bitmap 定义的唯一必选特性。 guid 和 href，指向源文件。 如果源文件是资源条，还需要 usedList 属性，其中列出了条的可用的图像。 有关更多信息，请参见 Bitmap 元素 文档。

父级关系

以下规则管理项目如何调用另一个项作为其父级。

元素	定义在命令表的此部分	包含 (作为父级，或者由 CommandPlacements 部分或二者的位置)	包含 (称为父)
组	Groups 元素， IDE，其他 Vspackage	菜单，组，项目	菜单、组和命令
Menu	Menus 元素， IDE，其他 Vspackage	1 到 n 组	0 到 n 组
工具栏	Menus 元素， IDE，其他 Vspackage	项目	0 到 n 组
Menu Item	Buttons 元素， IDE，其他 Vspackage	1 到 n 组，项目	-0 到 n 组
Button	Buttons 元素， IDE，其他 Vspackage	1 到 n 组，项目
组合	Combos 元素， IDE，其他 Vspackage	1 到 n 组，项目

菜单、命令和组位置

菜单、组或命令可能于多 IDE 中显示的位置。 对于项显示在多个位置，必须向 CommandPlacements 部分 CommandPlacement 元素。 所有菜单、组或命令可以添加为命令的位置。 但是，在中，因为它们不能于多个上下文相关位置，显示工具栏不能按照这种方式确定。

命令位置具有 guid、 id和 priority 属性。 GUID 和 ID 必须与确定的项。 priority 属性管理项目的位置有关其他项。 当 IDE 合并两个具有相同优先级的两个或多个项时，其位置是未定义的，因为 IDE 不保证包资源每次编写同一顺序包时生成。

如果菜单或组于多个位置出现，该菜单或组的所有子级将显示在每个实例。

命令可见性和上下文

如果安装了多个 sharepoint 项目服务，菜单、菜单项和工具栏大量可能干扰 IDE。 使用 可见性绑定 和命令标志，若要避免此问题，可以控制各个 UI 元素的可见性。

可见性约束

可见性绑定的设置为 VisibilityConstraints 部分的 VisibilityItem 元素 。 可见性约束定义目标项目可见的特定 UI 上下文。 本节包括可见的菜单或菜单命令，仅当其中一个定义的上下文处于活动状态时。 如果菜单或命令本节中引用，默认情况下它始终可见。 本节不应用于组。

VisibilityItem 元素必须具有三个属性，如下所示:目标 UI 元素的 guid 和 id 和 context。 context 属性指定目标项何时可见，并执行任何有效的 UI 上下文作为其值。 Visual Studio 的 UI 上下文常数是 VSConstants 类的成员。 每个 VisibilityItem 元素只能接受一个上下文值。 如下面的示例所示，若要将第二个上下文，请创建指向同一项目的秒 VisibilityItem 元素，。

<VisibilityConstraints>
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasSingleProject" />
  <VisibilityItem guid="guidSolutionToolbarCmdSet"
        id="cmdidTestCmd"
        context="UICONTEXT_SolutionHasMultipleProjects" />
</VisibilityConstraints>

命令标志

它们适用以下命令标志会影响菜单和命令可见性。

• AlwaysCreate
  菜单后，即使没有组或按钮。

  有效范围: Menu

• CommandWellOnly
  请应用该标志，如果命令没有出现在顶级菜单，并且希望使其可用于附加 shell 自定义项，例如，将其绑定到密钥。 在安装之后 VSPackage，用户可以打开 选项 对话框中编辑命令安排自定义这些命令在 键盘环境 类别下。 不影响在快捷菜单、工具栏、菜单管理员或子菜单的位置。

  有效范围: Button， Combo

• DefaultDisabled
  默认情况下，命令是禁用的，如果实现命令的 VSPackage 未加载或 QueryStatus 方法未调用。

  有效范围: Button， Combo

• DefaultInvisible
  默认情况下，命令是不可见的，如果实现命令的 VSPackage 未加载或 QueryStatus 方法未调用。

  应将与 DynamicVisibility 标记。

  有效范围: Button， Combo， Menu

• DynamicVisibility
  命令的可见性可以更改通过在 VisibilityConstraints 节包含的 QueryStatus 方法或上下文 GUID。

  适用于显示菜单上的命令，不在工具栏。 ，当 OLECMDF_INVISIBLE 标志。 QueryStatus 方法时，返回顶级工具栏项可以禁用，但是，未隐藏。

  在菜单上，此标志也指示应自动隐藏，而其成员隐藏时。 ，因为顶级菜单已具有此行为，此标志通常被指派到子菜单。

  应将与 DefaultInvisible 标记。

  有效范围: Button， Combo， Menu

• NoShowOnMenuController
  如果具有此标志的菜单中的命令管理员确定，命令没有出现的下拉列表。

  有效范围: Button

有关标志的更多信息，请参见 Command Flag 元素 文档。

一般要求

，它可以显示并启用之前，该命令必须通过以下一系列测试:

• 命令正确定位。

• DefaultInvisible 未设置任何标志。

• 父菜单或工具栏可见。

• 命令不是不可见的原因在于 VisibilityConstraints 元素 部分的上下文项。

• 实现 IOleCommandTarget 接口的 VSPackage 代码显示并启用命令。 接口代码没有截获并对此操作。

• 当用户单击命令时，它成为受上 命令传送算法概述的过程。

调用预定义命令

UsedCommands 元素 启用 Vspackage 对 IDE 提供由其他 Vspackage 或的访问命令。 若要执行该命令 GUID 和 ID 使用的此操作，请创建 UsedCommand 元素 。 这确保了该命令将由 Visual Studio 加载，因此，即使它不是当前 Visual Studio 配置部分。 有关更多信息，请参见 UsedCommand 元素。

接口元素的外观

有关选择并确定的命令元素的注意事项如下:

• Visual Studio 提供基于位置不同的样式显示的许多 UI 元素。

• 是使用 DefaultInvisible 标志的 UI 元素在 IDE 不会显示，除非将由其 QueryStatus 方法的 VSPackage 实现示，也不会与 VisibilityConstraints 部分的特定 UI 上下文。

• 一个成功确定的命令不中显示。 这是因为， IDE 会自动隐藏或基于 VSPackage 的接口显示某些命令，其中 (或没有) 实现。 例如，将自动显示的某些生成接口会导致生成相关的菜单项的 VSPackage 的实现。

• 应用在 UI 元素定义的 CommandWellOnly 标志表示该命令可由自定义只添加。

• 命令可能只可用于某些 UI 上下文，例如，因此，只有当显示对话框时， IDE 在 " 设计 " 视图中。

• 若要导致一些 UI 元素显示在 IDE，则必须实现一个或多个接口或写入一些代码。

请参见

概念

Making Commands Available

其他资源

使用命令、菜单和工具栏的常规任务

Command Table Configuration (.ctc) Files

Command Table Format Reference

Command Routing in VSPackages