共用方式為

VSPackage 如何新增使用者介面元素

VSPackage 可以透過 .vsct 檔案將使用者介面 （UI） 元素，例如功能表、工具列和工具視窗新增至 Visual Studio。

您可以在 Visual Studio 使用者體驗指導方針中找到 UI 元素的設計指導方針。

Visual Studio 命令資料表架構

如前所述，命令表架構支援上述架構原則。 命令表架構的抽象、資料結構和工具背後的原則如下：

  • 項目分為三種基本類型：功能表、命令和群組。 功能表可以在 UI 中公開為功能表、子功能表、工具列或工具視窗。 命令是使用者可以在 IDE 中執行的程式，而且可以公開為功能表項目、按鈕、清單方塊或其他控制項。 群組是功能表和命令的容器。

  • 每個項目都由描述項目、其相對於其他項目的優先順序以及修改其行為的標誌所指定。

  • 每個項目都有一個位置，說明項目的父項。 一個項目可以有多個父項，因此可以出現在 UI 的多個位置。

每個命令都必須有一個群組作為其父項，即使它是該組中唯一的子項也一樣。 每個標準菜單還必須有一個父組。 工具列和工具視窗扮演自己的父項角色。 群組可以將主要 Visual Studio 功能表列或任何功能表、工具列或工具視窗作為其父系。

如何定義項目

.vsct 檔案的格式為 XML。 它會定義套件的 UI 元素，並決定這些元素在 IDE 中的顯示位置。 套件中的每個選單、群組或命令都會先在區段 Symbols 中指派 GUID 和 ID。 在 .vsct 檔案的其餘部分中，每個功能表、命令和群組都會由其 GUID 和識別碼組合來識別。 下列範例顯示在範本中選取功能表命令時，Visual Studio 套件範本所產生的一般Symbols區段。

<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 元素將名稱對應至 GUID，這些 GUID 被 IDE 用於識別軟體包及其各個組件。

備註

GUID 是由 Visual Studio 套件範本自動產生。 您也可以按一下 [工具] 功能表上的 [建立 GUID] 來建立唯一的 GUID。

第一個 GuidSymbol 元素 guid<PackageName>Pkg是套件本身的 GUID。 這是 Visual Studio 用來載入套件的 GUID。 一般而言，它沒有子元素。

依照慣例，功能表和命令會分組在第二個 GuidSymbol 元素下， guid<PackageName>CmdSet而點陣圖會分組在第三個 GuidSymbol 元素 guidImages下。 您不必遵循此慣例，但每個功能表、群組、命令和點陣圖都必須是元素的 GuidSymbol 子系。

在代表套件命令集的第二個 GuidSymbol 元素中，有數個 IDSymbol 元素。 每個 IDSymbol 元素 都會將名稱對應至數值，而且可能代表屬於命令集一部分的功能表、群組或命令。 第三IDSymbol個GuidSymbol元素中的元素代表可用作命令圖示的點陣圖。 因為 GUID/ID 配對在應用程式中必須是唯一的，所以相同 GuidSymbol 元素的兩個子系不得有相同的值。

當功能表、群組或命令具有 GUID 和識別碼時，可以將其新增至 IDE。 每個 UI 元素都必須具有下列項目：

  • 符合GuidSymbol的屬性，該屬性名稱與定義該 UI 元素的元素名稱guid相符。

  • id符合相關聯IDSymbol元素名稱的屬性。

和 屬性一起構成 UI 元素的簽名。

  • 決定 UI 元素在其父級功能表或群組中位置的 priority 屬性。

  • 具有guid和id屬性，指定父功能表或群組簽章的Parent 元素。

每個功能表在Menus區段中定義。 功能表必須具有 guid、id 和 priority 屬性，以及一個 Parent 元素，和下列其他屬性和子項：

  • 指定 type 屬性以確定選單在 IDE 中應顯示為選單或工具列。

  • 包含 ButtonText 元素 和 CommandName 元素 的 Strings 元素，分別指定 IDE 中功能表的標題，及在命令視窗中用來存取功能表的名稱。

  • 選擇性旗標。 CommandFlag 元素可能會出現在功能表定義中，以變更其在 IDE 中的外觀或行為。

每個Menu元素都必須有一個群組作為其父項，除非它是可停駐的元素，例如工具列。 可固定選單是它自己的父項。 如需 type 屬性的選單和值的詳細資訊，請參閱 選單元素 文件。

下列範例顯示顯示在 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 中，除非是功能表上的分界線。 因此， 群組元素 僅由其簽章、優先順序和父元素定義。

群組可以有一個功能表、另一個群組或本身作為父項。 不過，父項通常是功能表或工具列。 先前範例中的功能表是群組的 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>

Commands

提供給 IDE 的命令會定義為 Button 元素 或 Combo 元素。 若要顯示在功能表或工具列上，指令必須有一個群組作為其父系。

Buttons

按鈕在區 Buttons 段中定義。 使用者按一下以執行單一命令的任何功能表項目、按鈕或其他元素都被視為按鈕。 某些按鈕類型還可以包含清單功能。 按鈕具有與功能表相同的必要和選擇性屬性，也可以有 Icon 元素 ，以指定代表 IDE 中按鈕之點陣圖的 GUID 和識別碼。 如需按鈕及其屬性的詳細資訊，請參閱 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 部分中定義。 每個 Combo 元素都代表 IDE 中的下拉式清單方塊。 清單方塊可能可由使用者寫入，也可能無法寫入，這取決於組合方塊的屬性值 type。 組合具有與按鈕相同的元素和行為，也可以具有以下附加屬性：

  • 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>
點陣圖

將與圖示一起顯示的命令必須包含一個 Icon 元素，該元素使用其 GUID 和 ID 來引用點陣圖。 每個點陣圖都會定義為區段中的Bitmaps。 定義的唯一 Bitmap 必要屬性是 guid 和 href，它指向來源檔。 如果來源檔案是資源條，則也需要 usedList 屬性，以列出條帶中的可用映像。 如需詳細資訊，請參閱 點陣圖元素 文件。

育兒

下列規則會控管專案如何呼叫另一個專案作為其父項。

元素 在命令表的此部分中定義 可以被包含（作為父項、在 CommandPlacements 區段中的位置，或同時具備這兩者） 其可能包含（稱為父項）
群體 Groups 元素、IDE 和其他 VSPackages 菜單、群組、項目本身 功能表、群組和命令
菜單 選單元素、IDE、其他 VSPackage 1至 n 組 0 到 n 組
工具列 選單元素、IDE、其他 VSPackage 物品本身 0 到 n 組
選單項目 Buttons 元素、IDE 以及其他 VSPackages 1 到 n 組，項目本身 -0 到 n 組
Button Buttons 元素、IDE、其他 VSPackage 1 到 n 組，項目本身
組合圖 Combos 元素、IDE、其他 VSPackage 1 到 n 組，項目本身

功能表、群組或命令可以出現在 IDE 中的多個位置。 若要讓項目出現在多個位置，必須將項目新增為 CommandPlacementsCommandPlacement 元素。 任何功能表、群組或命令都可以新增為命令配置。 不過，工具列無法以這種方式定位，因為它們無法出現在多個內容相關位置。

指令放置具有屬性 guid、id和priority。 GUID 和識別碼必須符合所定位項目的 GUID 和識別碼。 屬性 priority 會控管項目相對於其他項目的放置。 當 IDE 合併兩個或多個具有相同優先順序的項目時，它們的位置會未定義，因為 IDE 不保證每次建置套件時都會以相同的順序讀取套件資源。

如果功能表或群組出現在多個位置，則該功能表或群組的所有子項都會出現在每個實例中。

命令可見性和內容

安裝多個 VSPackage 時，大量的功能表、功能表項目和工具列可能會使 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， ， ComboMenu

DynamicVisibility您可以使用QueryStatus方法或VisibilityConstraints節中包含的內容 GUID 來變更命令的可見度。

適用於呈現在選單上，而非工具列上的指令。 最上層工具列項目可以被停用，但無法隱藏，當從 QueryStatus 方法傳回 OLECMDF_INVISIBLE 旗標時。

在菜單上，此旗標也表示當其成員被隱藏時，它應該自動隱藏。 此旗標通常會指派給子功能表，因為最上層功能表已經有此行為。

應該與 DefaultInvisible 標誌結合使用。

適用於： Button， ， ComboMenu

NoShowOnMenuController 如果具有此旗標的命令位於功能表控制器上，則該命令不會出現在下拉式清單中。

適用於： Button

如需命令旗標的詳細資訊，請參閱 CommandFlag 元素 檔。

一般需求

您的指令必須通過下列一系列測試，才能顯示及啟用：

  • 指令位置正確。

  • DefaultInvisible旗標未設定。

  • 父功能表或工具列可見。

  • 命令之所以不可見，是因為在 VisibilityConstraints 元素 區段中的內容項目。

  • 實作 IOleCommandTarget 介面的 VSPackage 程式碼將顯示並啟用您的命令。 沒有介面程式碼攔截它並對其採取行動。

  • 當使用者按一下您的指令時，它會受到 路由演算法中概述的程式的約束。

呼叫預先定義的命令

UsedCommands 元素可讓 VSPackage 存取其他 VSPackage 或 IDE 所提供的命令。 若要這樣做，請建立具有要使用的命令 GUID 和識別碼的 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 中，您必須實作一或多個介面，或撰寫一些程式碼。

相關內容

  • Last updated on