VSPackages 對 IDE 所新增的使用者介面項目

VSPackage 可以新增使用者介面 (UI) 項目、 功能表、 工具列和工具視窗，以 Visual Studio 為例，整合開發環境 (IDE)。

架構原則

在名為一組規則及結構，可讓自訂的 UI 的 VSPackage 指令表架構。 「 命令 」 表架構根據以下的設計原理：

• UI 不應該雜亂或令人混淆。

• UI 應該是動態，而非靜態。

• UI 應該是可自訂的。

• UI 應該會有幫助。

雜亂或令人混淆，應該不是 UI

• 數個 VSPackages 可能會安裝在裝載 (host) 您的 VSPackage Visual Studio 的工作階段中。 當您 VSPackage 加入命令時，它必須不會中斷先前所安裝的 VSPackages，但它也應該讓它的功能可以使用其他的 VSPackages，並讓它們能夠回報提供的功能。

• 每個功能表中，是否使用主要功能表列]、 [子功能表或 [快顯功能表上，存取時可包含其他 VSPackages 所提供的功能表項目。 因此，小心不要 overcrowd UI。 如果要一次顯示太多的指令，可能會造成使用者混淆 UI。

UI 應該是動態，而非靜態

• 命令可以顯示或隱藏在任何時間，取決於基礎資料和目前的使用者活動的狀態。

• 若要變更 UI 項目的標籤，以及它的下拉式方塊或功能表的內容，就必須啟用 VSPackage。

• 若要新增或移除使用 VSPackage 時，可能 UI 項目。

• UI 項目可能需要額外的呼叫來填入它們的值，或偵測其目前狀態為 VSPackage。 這些項目的範例包括最近使用過的 (MRU) 檔案、 下拉式方塊及清單選取器，如色彩或材質。

• 這樣可以改善使用者經驗，在其他 VSPackages 的功能表中加入您的命令。 比方說，如果您提供的命令類似複製，您可以將命令放在每個 VSPackage 其中 複製就會出現。

UI 應該是可自訂

• 任何時候，使用者可以自訂 UI 項目，在您的 VSPackage，比方說，將按鈕加入至工具視窗，或重新排列] 功能表。 不過，在某些情況下，您可能要停用自訂。

• 有些指令可用只能由使用自訂 ； 也就是一個命令可能無法使用功能表或工具列上直到使用者將其加入使用自訂對話方塊。

• 任何時候，使用者可以自訂您的命令，以及使用鍵盤快速鍵的來自 Visual Studio 及其他 VSPackages 的命令的快速鍵。

• 可執行命令，藉由使用命令視窗。 因此，IDE 就必須知道哪一個命令會對應至特定命令的標籤。 這樣的 IDE 優勢使用程序，就是規範化，會移除空格壓縮成單一文字的命令名稱。 比方說的規範化 ' & 開啟舊檔] 是 [開啟舊檔]。

UI 應該會有幫助

• 大部分的 UI 項目會有工具提示。

• 較佳的效能，只有其中一個函式叫用時，才應該載入您 VSPackage。 這就是所謂 「 延遲載入 」。

• 加入 IDE VSPackage 所要求的項目應該當地語系化。

• 您可以使用 Visual Studio 所隨附的點陣圖，或提供您自己。

Visual Studio 的命令表架構

如所述，「 命令 」 表架構支援前述的架構原則。 後面的抽象概念、 資料結構和工具命令資料表架構的要件如下所示：

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

• 描述項目，它的優先順序，相對於其他項目，並修改其行為的旗標的定義來指定每個項目。

• 每個項目都有描述項目的父代的位置。 項目，使其可以出現在 UI 中的多個位置，可以有多重的父系。

  每個命令都必須有一組做為其父系，即使它是唯一的子系，該群組中。 每個標準功能表也必須有父群組。 工具列和工具視窗做為其本身的父系。 群組可以有為 Visual Studio 的功能表列中，其父代，或任何功能表、 工具列或工具視窗。

項目定義的方式

.Vsct 檔案的 XML 格式。 .Vsct 檔案定義之 UI 元素的套件，並判斷這些項目出現在 IDE 中的位置。 每個功能表、 群組或封裝中的命令第一次指派的 GUID 及識別碼在Symbols一節。 接下來在.vsct 檔案、 每個功能表、 指令及群組所識別的 GUID 及識別碼的組合。 下列範例會示範典型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。

注意事項
Visual Studio 的封裝範本會自動產生的 Guid。您也可以建立唯一的 GUID，即可建立 GUID 的工具功能表。

第一個GuidSymbol項目，「 guid [PackageName] 版本程式 」，是封裝本身的 GUID。 這是用來載入封裝 Visual Studio 的 GUID。 一般而言，它並沒有子項目。

依照慣例，功能表和命令進行分組的第二個GuidSymbol項目，「 guid [PackageName] CmdSet"，和點陣圖會在第三個GuidSymbol項目、"guidImages"。 您沒有遵循此慣例，但每個功能表、 群組、 指令及點陣圖必須是子系GuidSymbol項目。

在第二個GuidSymbol項目，表示封裝的命令集，有幾個IDSymbol項目。 每個IDSymbol 項目名稱對應到一個數值，並且可能表示功能表、 群組或命令的命令集的一部份。 IDSymbol中第三個項目GuidSymbol可能會以圖示命令所使用的項目代表點陣圖。 因為 GUID /ID 組都必須是唯一的應用程式中，沒有兩個的子項目相同的GuidSymbol項目可能會有相同的值。

功能表、 群組及指令

功能表、 群組或命令具有 GUID 及識別碼，就可以加至 IDE。 每個 UI 項目必須具有下列事項：

• A guid屬性來符合名稱的GuidSymbol的 UI 項目會定義下的項目。

• id符合名稱的相關聯的屬性IDSymbol項目。

  在一起， guid和id屬性撰寫簽章的 UI 項目。

• A priority屬性來決定其父功能表或群組中的 UI 項目的位置。

• A Parent 項目的guid和id指定父功能表或群組的簽名碼的屬性。

功能表

每個功能表定義成Menu 項目在Menus一節。 功能表必須具有guid， id，和priority屬性，以及Parent項目，而且也下列的其他屬性和子系：

• A type屬性來指定功能表是否顯示在 IDE 中作為一種類型的功能表或工具列。

• A Strings 項目包含ButtonText 項目，會在 IDE 中，指定功能表的標題和CommandName 項目，以指定名稱所使用的命令 ] 視窗來存取功能表。

• 選擇性的旗標。 A CommandFlag 項目可能會出現在功能表定義中，以變更其外觀或行為，在 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>

Group

「 群組 」 是項目中定義的Groups .vsct 檔的區段。 群組是直接的容器。 它們不會出現在 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一節。 任何功能表項目、 按鈕或其他使用者來執行單一命令的項目會被視為一個按鈕。 某些按鈕型別也可以包含清單功能。 按鈕有相同的必要和選擇性的屬性包含功能表，而且還可以讓Icon 項目 ，指定的 GUID 及識別碼表示在 IDE 中的按鈕的點陣圖。 如需有關按鈕和其屬性的詳細資訊，請參閱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屬性的組合。 組合具有相同的項目，而按鈕的行為，而且也可以有下列額外的屬性：

• A 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 及識別碼。 每一個點陣圖定義成Bitmap 項目在Bitmaps一節。 唯一的必要屬性，如Bitmap定義是guid和href，指向原始程式檔。 如果原始程式檔的資源帶， usedList 屬性也是必要的若要列出可用的映像在區域中。 如需詳細資訊，請參閱 Bitmap 項目 文件。

父代設定

下列規則可控制如何項目可以呼叫做為其父系的另一個項目。

項目	在命令表裡的這一節中定義	可能包含 (父代，或在置於CommandPlacements ] 區段中，或兩者)	可能包含 (簡稱為父代)
Group	Groups 項目IDE、 其他 VSPackages	功能表上，一個群組，本身的項目	功能表、 群組及指令
Menu	Menus 項目IDE、 其他 VSPackages	1 到 n 群組	0 到 n 群組
Toolbar	Menus 項目IDE、 其他 VSPackages	位於項目	0 到 n 群組
Menu Item	Buttons 項目IDE、 其他 VSPackages	1 到 n 群組，本身的項目	-0 到 n 群組
Button	Buttons 項目IDE、 其他 VSPackages	1 到 n 群組，本身的項目
組合	Combos 項目IDE、 其他 VSPackages	1 到 n 群組，本身的項目

功能表、 指令及群組的位置

功能表、 群組或命令可以出現在 IDE 中的多個位置中。 在多個位置中顯示項目，必須先新增至CommandPlacements一節為CommandPlacement 項目。 命令位置可以加入任何功能表、 群組或命令。 然而，工具列無法定位在這種方式因為它們不會出現在多個即時線上的位置。

命令的安置地方有guid， id，以及priority屬性。 GUID 及識別碼必須符合的所在位置的項目。 priority屬性負責控制其他項目與相關項目的位置。 當 IDE 會合併兩個或多個具有相同優先順序的項目時，因為 IDE 並不保證封裝會讀取資源的相同順序該套件僅建立每次他們的安置地方會定義。

如果功能表或群組會出現在多個位置，該功能表或群組的所有子系會在每個執行個體。

命令的可視性和內容

多個 VSPackages 安裝時，大量的功能表、 功能表項目和工具列可能會弄亂 IDE。 若要避免這個問題，您可以控制個別的 UI 項目的可見性，藉由使用可見性的條件約束和命令旗標。

可見性的條件約束

可視性限制已設為VisibilityItem 項目在VisibilityConstraints一節。 可見性條件約束定義特定的目標項目是可見的 UI 內容。 使用只有其中一個已定義的內容中時，會顯示功能表或這一節中所包含的指令。 如果這一節中並未參考功能表或指令，它永遠預設為可見。 本節不會套用至群組。

VisibilityItem項目必須要有三種屬性，如下所示： guid和id的目標 UI 項目，以及context。 context屬性會指定當目標項目將會顯示，並會使用任何有效的 UI 內容當做它的值。 UI 內容的常數 Visual Studio 屬於VSConstants類別。 每個VisibilityItem項目可以採取只能有一個內容值。 若要套用第二個內容，建立第二個VisibilityItem指向相同的項目，如下列範例所示的項目。

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

命令旗標

下列的命令旗標，可能會影響功能表和命令的兩個套的可視性。

• AlwaysCreate
  即使它附帶沒有群組或按鈕，就會建立功能表。

  有效期間:Menu

• CommandWellOnly
  套用這個旗標如果命令沒有出現在最上層的功能表上，而您想要使用其他的殼層自訂項目，例如，繫結至索引鍵。 在安裝 VSPackage 之後，使用者可以自訂這些命令開啟選項 對話方塊，然後編輯 [命令放置在 鍵盤環境類別。 不會影響在快顯功能表、 工具列、 功能表控制器或子功能表上的位置。

  適用於： Button，Combo

• DefaultDisabled
  預設情況下，如果實作命令 VSPackage 並不會載入，或尚未呼叫 QueryStatus 方法，會停用命令。

  適用於： Button，Combo

• DefaultInvisible
  預設情況下，該命令不可見的如果實作命令 VSPackage 並不會載入，或尚未呼叫 QueryStatus 方法。

  應該要結合DynamicVisibility旗標。

  Valid for: Button, Combo,Menu

• DynamicVisibility
  可以使用 QueryStatus 方法或內容中所包含的 GUID 變更命令的可見性VisibilityConstraints一節。

  套用至顯示在功能表中，不是在工具列上的命令。 可以停用，但不是能隱藏 OLECMDF_INVISIBLE 旗標從 QueryStatus 方法傳回時最上層的工具列項目。

  在功能表中，這個旗標也表示它應該會自動隱藏時要隱藏其成員。 這個旗標通常會指派給子功能表，因為最上層功能表已經有這個問題。

  應該要結合DefaultInvisible旗標。

  Valid for: Button, Combo,Menu

• NoShowOnMenuController
  如果是具有這個旗標定位在功能表控制器上，該命令不在下拉式清單中。

  有效期間:Button

如需有關命令旗標的詳細資訊，請參閱CommandFlag 項目文件。

一般需求

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

• 命令是正確的位置。

• DefaultInvisible未設定旗標。

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

• 命令不看不見的內容中的功能表項目因為VisibilityConstraints 項目一節。

• VSPackage 實作程式碼， IOleCommandTarget介面顯示，並讓您的命令。 沒有介面程式碼會攔截它，並在其上動作。

• 當使用者按一下命令時，它會變成受制於所述的程序命令的路由演算法。

呼叫預先定義的命令

UsedCommands 項目 VSPackages 可讓其他的 VSPackages 或 IDE 提供存取命令。 若要執行這項操作，建立UsedCommand 項目具有 GUID 並要使用的命令 ID。 這樣可以確保命令將會影響 Visual Studio，即使它不是目前的 Visual Studio 組態的一部分。 如需詳細資訊，請參閱 UsedCommand 項目。

介面項目外觀

選取並將命令的項目定位的考量如下所示：

• Visual Studio提供了許多的 UI 項目顯示的方式會取決於位置。

• UI 項目所定義的使用DefaultInvisible旗標不會顯示在 IDE 中之後才顯示受到其 VSPackage 實作的任何一QueryStatus方法，或在特定的 UI 內容相關聯VisibilityConstraints一節。

• 成功地定位的命令可能無法顯示。 這是因為 IDE 會自動隱藏或顯示一些命令，取決於 VSPackage (或沒有) 的介面實作。 比方說，一些 VSPackage 的實作建立介面的原因與組建相關的功能表項目，會自動顯示。

• 套用CommandWellOnly命令可以加入僅供自訂的 UI 項目的定義中的旗標表示。

• IDE 是在 [設計] 檢視時，會顯示對話方塊時，才可能只適用於特定 UI 內容，例如，執行命令。

• 若要使特定的 UI 項目，要顯示在 IDE 中，您必須實作一或多個介面，或撰寫一些程式碼。

請參閱

概念

Making Commands Available

其他資源

一般工作的命令、 功能表和工具列

Command Table Configuration (.ctc) Files

Command Table Format Reference

Command Routing in VSPackages