VSIX 色彩編輯器

發行項
01/13/2024

Visual Studio 延伸模組色彩編輯器工具可以建立和編輯 Visual Studio 的自定義色彩。此工具也可以產生主題資源索引鍵，以便可在程式碼中使用色彩。此工具適用於為支援主題的Visual Studio延伸模組製作色彩。此工具可以開啟 .pkgdef 和 .xml 檔案。 Visual Studio 主題（.vstheme 檔案）可以透過將擴展名變更為 .xml，搭配 Visual Studio 延伸模組色彩編輯器使用。此外，.vstheme 檔案也可以匯入目前的 .xml 檔案。

VSIX Color Editor Hero

套件定義檔案

套件定義（.pkgdef）檔案是定義主題的檔案。色彩本身會儲存在主題色彩 .xml 檔案中，這些檔案會編譯成 .pkgdef 檔案。 .pkgdef 檔案會部署到 Visual Studio 可搜尋的位置、在運行時間處理，並合併在一起以定義主題。

色彩標記

色彩標記是由四個元素所組成：

類別名稱： 一組色彩的邏輯群組。如果有想要的 UI 元素或 UI 元素群組特有的色彩，請使用現有的類別名稱。
令牌名稱： 色彩令牌和令牌集的描述性名稱。集合包括背景和前景（text）令牌名稱及其所有狀態，而且應該命名這些名稱，以便輕鬆地識別其套用的配對和狀態。
色彩值（或色調）： 每個彩色主題都需要。一律在配對中建立背景和文字色彩值。色彩會針對背景/前景配對，因此文字（前景）色彩一律可針對繪製的背景色彩讀取。這些色彩會連結在UI中，並一起使用。如果背景不適合用於文字，請勿定義前景色彩。
系統色彩名稱： 用於高對比度顯示器。

如何使用工具

應盡可能重複使用現有的 Visual Studio 色彩，而不是建立新的色彩。不過，若未定義適當的色彩，應該建立自定義色彩，以保持擴充主題相容。

建立新的色彩標記

若要使用 Visual Studio 擴充功能色彩編輯器建立自定義色彩，請遵循下列步驟：

判斷新色彩標記的類別和令牌名稱。
選擇UI元素將用於每個主題的色調，以及高對比度的系統色彩。
使用色彩編輯器來建立新的色彩標記。
使用 Visual Studio 延伸模組中的色彩。
測試 Visual Studio 中的變更。

步驟 1：判斷新色彩標記的類別和令牌名稱。

VSColor 的慣用命名配置是 [類別] [UI 類型] [State]。請勿在 VSColor 名稱中使用「color」一詞，因為它是多餘的。

類別名稱會提供邏輯群組，而且應該盡可能窄地定義。例如，單一工具視窗的名稱可以是類別名稱，但整個業務單位或專案小組的名稱不是。將專案分組為類別有助於防止具有相同名稱的色彩之間的混淆。

令牌名稱必須清楚指出要套用色彩的專案類型和情況或「狀態」。例如，使用中數據提示的 [UI 類型] 可以命名為 “DataTip”，而 [State] 可以命名為 “Active”，因而產生 “DataTipActive” 的色彩名稱。由於數據提示有文字，因此必須定義前景和背景色彩。藉由使用背景/前景配對，色彩編輯器會自動建立背景的 “DataTipActive” 色彩，並針對前景建立 “DataTipActiveText”。

如果UI片段只有一個狀態， 則可以省略名稱的 [State] 部分。例如，如果搜尋方塊具有框線，而且沒有會影響框線色彩的狀態變更，則框線色彩標記的名稱可以直接稱為 “SearchBoxBorder”。

一些常見的狀態名稱包括：

使用中
非作用中
MouseOver
MouseDown
Selected
焦點

清單專案控制件部分的一些令牌名稱範例：
ListItem
ListItemBorder
ListItemMouseOver
ListItemMouseOverBorder
ListItemSelected
ListItemSelectedBorder
ListItemDisabled
ListItemDisabledBorder

步驟 2：選擇 UI 元素將用於每個主題的色調，以及高對比度的系統色彩。

為UI選擇自訂色彩時，請選取類似的現有UI元素，並使用其色彩作為基底。內建UI元素的色彩已經過檢閱和測試，因此它們在所有主題中看起來都會正確且正常運作。

步驟 3：使用色彩編輯器來建立新的色彩標記。

啟動色彩編輯器，然後開啟或建立新的自定義主題色彩 .xml 檔案。從功能表中選取 [ 編輯 > 新色彩 ]。這會開啟對話框，以指定該類別內的類別和一或多個色彩項目名稱：

選取現有的類別，或選取 [新增類別 ] 以建立新的類別。另一個對話框將會開啟，並建立新的類別名稱：

新的類別接著會在 [ 新增色彩 ] 類別下拉功能表中變成可用。選擇類別之後，針對每個新的色彩標記各輸入一行名稱，並在完成時選取 [建立] ：

色彩值會顯示在背景/前景配對中，“None” 表示尚未定義色彩。注意：如果色彩沒有文字色彩/背景色彩組，則只需要定義背景。

若要編輯色彩標記，請選取該令牌主題（數據行）的色彩專案。以 8 位數 ARGB 格式輸入十六進位色彩值、在儲存格中輸入系統色彩名稱，或使用下拉功能表，透過一組色彩滑桿或系統色彩清單來選取所需的色彩，以新增色彩值。

對於不需要顯示文字的元件，請輸入一個色彩值：背景色彩。否則，請輸入背景和文字色彩的值，並以正斜線分隔。

輸入高對比度的值時，請輸入有效的 Windows 系統色彩名稱。請勿輸入硬式編碼的ARGB值。您可以從色彩值下拉功能表中選取 [背景：系統] 或 [前景：系統]，以檢視有效的系統色彩名稱清單。建立具有文字元件的專案時，請使用正確的背景/文字系統色彩組，或無法讀取文字。

當您完成建立、設定和編輯色彩標記時，請將它們儲存為所需的 .xml 或 .pkgdef 格式。沒有背景或前景集的色彩標記會以 .xml 格式儲存為空白色彩，但以 .pkgdef 格式捨棄。如果您嘗試將空白色彩儲存至 .pkgdef 檔案，對話框將會警告您潛在的色彩遺失。

步驟 4：使用 Visual Studio 擴充功能中的色彩。

定義新的色彩標記之後，請在項目檔中包含 .pkgdef，並將 [建置動作] 設定為 “Content”，並將 [包含在 VSIX 中] 設定為 “True”。

在 Visual Studio 延伸模組色彩編輯器中，選擇 [檔案 > 檢視資源程式代碼] 以檢視用於存取 WPF 型 UI 中自定義色彩的程式代碼。

在專案中的靜態類別中包含此程序代碼。 Microsoft.VisualStudio.Shell 的參考。<VSVersion.0.dll> 必須新增至專案，才能使用 ThemeResourceKey 類型。

namespace MyCustomColors
{
    public static class MyCategory
    {
        #region Autogenerated resource keys
        // These resource keys are generated by Visual Studio Extension Color Editor, and should be replaced when new colors are added to this category.
        public static readonly Guid Category = new Guid("faf7f3f9-9fe5-4dd3-9350-59679617dfbe");

        private static ThemeResourceKey _MyColor1ColorKey;
        private static ThemeResourceKey _MyColor1BrushKey;
        private static ThemeResourceKey _MyColor1TextColorKey;
        private static ThemeResourceKey _MyColor1TextBrushKey;
        public static ThemeResourceKey MyColor1ColorKey { get { return _MyColor1ColorKey ?? (_MyColor1ColorKey = new ThemeResourceKey(Category, "MyColor1", ThemeResourceKeyType.BackgroundColor)); } }
        public static ThemeResourceKey MyColor1BrushKey { get { return _MyColor1BrushKey ?? (_MyColor1BrushKey = new ThemeResourceKey(Category, "MyColor1", ThemeResourceKeyType.BackgroundBrush)); } }
        public static ThemeResourceKey MyColor1TextColorKey { get { return _MyColor1TextColorKey ?? (_MyColor1TextColorKey = new ThemeResourceKey(Category, "MyColor1", ThemeResourceKeyType.ForegroundColor)); } }
        public static ThemeResourceKey MyColor1TextBrushKey { get { return _MyColor1TextBrushKey ?? (_MyColor1TextBrushKey = new ThemeResourceKey(Category, "MyColor1", ThemeResourceKeyType.ForegroundBrush)); } }
        #endregion
    }
}

這可讓您存取 XAML 程式代碼中的色彩，並允許 UI 回應主題變更。

<UserControl x:Class="NewTestProject.TestPackageControl" Name="MyToolWindow"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:ns="clr-namespace:MyCustomColors">
  <Grid>
    <TextBlock Background="{DynamicResource {x:Static ns:MyCategory.MyColor1BrushKey}}"
               Foreground="{DynamicResource {x:Static ns:MyCategory.MyColor1TextBrushKey}}"
      >Sample Text</TextBlock>

  </Grid>
</UserControl>

步驟 5：測試 Visual Studio 中的變更。

色彩編輯器可以暫時將色彩標記套用至 Visual Studio 的執行中實例，以檢視色彩的實時變更，而不需重建延伸模組套件。若要這樣做，請按兩下位於每個主題資料行標頭上的 [將此主題套用至執行Visual Studio 視窗] 按鈕。當 VSIX 色彩編輯器關閉時，此暫時主題將會消失。

VSIX Color Editor Apply

若要永久變更，請在將新色彩新增至 .pkgdef 檔案並撰寫將使用這些色彩的程式代碼之後，重建並重新部署Visual Studio延伸模組。重建 Visual Studio 延伸模組會將新色彩的登錄值合併到其餘主題中。然後重新啟動 Visual Studio、檢視 UI，並確認新色彩是否如預期般顯示。

備註

此工具旨在用於建立預先存在的 Visual Studio 主題的自定義色彩，或用於編輯自定義 Visual Studio 主題的色彩。若要建立完整的自定義 Visual Studio 主題，請從 Visual Studio 擴充功能庫下載 Visual Studio 色彩主題編輯器延伸模組。

範例輸出

XML 色彩輸出

工具所產生的 .xml 檔案會類似這樣：

<Themes>
  <Theme Name="Light" GUID="{de3dbbcd-f642-433c-8353-8f1df4370aba}">
    <Category Name="CategoryName" GUID="{eee9d521-dac2-48d9-9a5e-5c625ba2040c}">
      <Color Name="ColorName1">
        <Background Type="CT_RAW" Source="FFFFFFFF" />
      </Color>
      <Color Name="ColorName2">
        <Background Type="CT_RAW" Source="FFFFFFFF" />
        <Foreground Type="CT_RAW" Source="FF000000" />
      </Color>
      <Color Name="ColorName3">
        <Background Type="CT_RAW" Source="FFFF0000" />
      </Color>
      <Color Name="ColorName4">
        <Background Type="CT_RAW" Source="FF000088" />
        <Foreground Type="CT_RAW" Source="FFFFFFFF" />
      </Color>
    </Category>
  </Theme>
  <Theme Name="Dark" GUID="{1ded0138-47ce-435e-84ef-9ec1f439b749}">...</Theme>
  <Theme Name="Blue" GUID="{a4d6a176-b948-4b29-8c66-53c97a1ed7d0}">...</Theme>
  <Theme Name="HighContrast" GUID="{a5c004b4-2d4b-494e-bf01-45fc492522c7}">...</Theme>
</Themes>

PKGDEF 色彩輸出

工具所產生的 .pkgdef 檔案會如下所示：

[$RootKey$\Themes\{de3dbbcd-f642-433c-8353-8f1df4370aba}\CategoryName]
"Data"=hex:78,00,00,00,0b,00,00,00,01,00,00,00,21,d5,e9,ee,c2,da,d9,48,9a,5e,5c,62,5b,a2,04,0c,04,00,00,00,0a,00,00,00,43,6f,6c,6f,72,4e,61,6d,65,31,01,ff,ff,ff,ff,00,0a,00,00,00,43,6f,6c,6f,72,4e,61,6d,65,32,01,ff,ff,ff,ff,01,00,00,00,ff,0a,00,00,00,43,6f,6c,6f,72,4e,61,6d,65,33,01,ff,00,00,ff,00,0a,00,00,00,43,6f,6c,6f,72,4e,61,6d,65,34,01,00,00,88,ff,01,ff,ff,ff,ff
[$RootKey$\Themes\{1ded0138-47ce-435e-84ef-9ec1f439b749}\CategoryName]
"Data"=hex:...
[$RootKey$\Themes\{a4d6a176-b948-4b29-8c66-53c97a1ed7d0}\CategoryName]
"Data"=hex:...
[$RootKey$\Themes\{a5c004b4-2d4b-494e-bf01-45fc492522c7}\CategoryName]
"Data"=hex:...

C# 資源索引鍵包裝函式

工具所產生的色彩資源索引鍵會類似這樣：

namespace MyNamespace
{
    public static class MyColors
    {
        #region Autogenerated resource keys
        // These resource keys are generated by Visual Studio Extension Color Editor, and should be replaced when new colors are added to this category.

        public static string ColorName1ColorKey { get { return "ColorName1ColorKey"; } }
        public static string ColorName1BrushKey { get { return "ColorName1BrushKey"; } }

        public static string ColorName2ColorKey { get { return "ColorName2ColorKey"; } }
        public static string ColorName2BrushKey { get { return "ColorName2BrushKey"; } }
        public static string ColorName2TextColorKey { get { return "ColorName2TextColorKey"; } }
        public static string ColorName2TextBrushKey { get { return "ColorName2TextBrushKey"; } }

        public static string ColorName3ColorKey { get { return "ColorName4ColorKey"; } }
        public static string ColorName3BrushKey { get { return "ColorName4BrushKey"; } }
        public static string ColorName3TextColorKey { get { return "ColorName4TextColorKey"; } }
        public static string ColorName3TextBrushKey { get { return "ColorName4TextBrushKey"; } }
        #endregion
    }
}

WPF 資源字典包裝函式

工具所產生的色彩 ResourceDictionary 索引鍵會如下所示：

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:colors="clr-namespace:MyNamespace">

  <SolidColorBrush x:Key="{x:Static colors:MyColors.ColorName1BrushKey}" Color="#FFFFFFFF" />
  <Color x:Key="{x:Static colors:MyColors.ColorName1ColorKey}" A="255" R="255" G="255" B="255" />

  <SolidColorBrush x:Key="{x:Static colors:MyColors.ColorName2BrushKey}" Color="#FFFFFFFF" />
  <Color x:Key="{x:Static colors:MyColors.ColorName2ColorKey}" A="255" R="255" G="255" B="255" />
  <SolidColorBrush x:Key="{x:Static colors:MyColors.ColorName2TextBrushKey}" Color="#FF000000" />
  <Color x:Key="{x:Static colors:MyColors.ColorName2TextColorKey}" A="255" R="0" G="0" B="0" />

  <SolidColorBrush x:Key="{x:Static colors:MyColors.ColorName3BrushKey}" Color="#FFFF0000" />
  <Color x:Key="{x:Static colors:MyColors.ColorName3ColorKey}" A="255" R="255" G="0" B="0" />

  <SolidColorBrush x:Key="{x:Static colors:MyColors.ColorName4BrushKey}" Color="#FF000088" />
  <Color x:Key="{x:Static colors:MyColors.ColorName4ColorKey}" A="255" R="0" G="0" B="136" />
  <SolidColorBrush x:Key="{x:Static colors:MyColors.ColorName4TextBrushKey}" Color="#FFFFFFFF" />
  <Color x:Key="{x:Static colors:MyColors.ColorName4TextColorKey}" A="255" R="255" G="255" B="255" />
</ResourceDictionary>

共用方式為

VSIX 色彩編輯器

如何使用工具

備註

範例輸出

其他資源