Editor de cores do VSIX

Artigo
10/10/2023

A ferramenta Editor de cores de extensão do Visual Studio pode criar e editar cores personalizadas para o Visual Studio. A ferramenta também pode gerar chaves de recurso de tema para que as cores possam ser usadas no código. Essa ferramenta é útil para criar cores para uma extensão do Visual Studio que oferece suporte a temas. Essa ferramenta pode abrir arquivos .pkgdef e .xml. Os temas do Visual Studio (arquivos .vstheme) podem ser usados com o Editor de Cores de Extensão do Visual Studio alterando a extensão de arquivo para .xml. Além disso, os arquivos .vstheme podem ser importados para um arquivo .xml atual.

VSIX Color Editor Hero

Arquivos de definição de pacote

Arquivos de definição de pacote (.pkgdef) são os arquivos que definem temas. As cores em si são armazenadas em arquivos de .xml de cores do tema, que são compilados em um arquivo .pkgdef. Os arquivos .pkgdef são implantados em locais pesquisáveis do Visual Studio, processados em tempo de execução e mesclados para definir temas.

Fichas coloridas

Um token de cor é composto por quatro elementos:

Nome da categoria: um agrupamento lógico para um conjunto de cores. Use um nome de categoria existente se já houver cores específicas para o elemento de interface do usuário desejado ou grupo de elementos de interface do usuário.
Nome do token: um nome descritivo para o token de cores e conjuntos de tokens. Os conjuntos incluem nomes de token de plano de fundo e primeiro plano (texto), bem como todos os seus estados, e estes devem ser nomeados para que seja fácil identificar os pares e os estados aos quais eles se aplicam.
Valores de cor (ou matizes): necessários para cada tema colorido. Sempre crie valores de cor de plano de fundo e texto em pares. As cores são emparelhadas para plano de fundo/primeiro plano para que a cor do texto (primeiro plano) seja sempre legível em relação à cor de plano de fundo na qual ele é desenhado. Essas cores estão vinculadas e serão usadas juntas na interface do usuário. Se o plano de fundo não se destinar ao uso com texto, não defina uma cor de primeiro plano.
Nome da cor do sistema: para uso em monitores de alto contraste.

Como usar a ferramenta

Tanto quanto possível, e quando apropriado, as cores existentes do Visual Studio devem ser reutilizadas em vez de criar novas. No entanto, para os casos em que nenhuma cor apropriada é definida, cores personalizadas devem ser criadas para manter um tema de extensão compatível.

Criando novos tokens de cores

Para criar cores personalizadas usando o Editor de cores de extensão do Visual Studio, execute estas etapas:

Determine os nomes de categoria e token para os novos tokens de cor.
Escolha os tons que o elemento da interface do usuário usará para cada tema e a cor do sistema para Alto Contraste.
Use o editor de cores para criar novos tokens de cores.
Use as cores em uma extensão do Visual Studio.
Teste as alterações no Visual Studio.

Etapa 1: determine os nomes de categoria e token para os novos tokens de cor.

O esquema de nomenclatura preferencial para um VSColor é [Categoria] [Tipo de interface do usuário] [Estado]. Não use a palavra "cor" em nomes VSColor, pois é redundante.

Os nomes de categoria fornecem agrupamentos lógicos e devem ser definidos da forma mais restrita possível. Por exemplo, o nome de uma única janela de ferramenta pode ser um nome de categoria, mas o nome de uma unidade de negócios inteira ou equipe de projeto não é. Agrupar entradas em categorias ajuda a evitar a confusão entre cores com o mesmo nome.

Um nome de token deve indicar claramente o tipo de elemento e as situações, ou "estado", para as quais a cor será aplicada. Por exemplo, o [tipo de interface do usuário] de uma dica de dados ativa pode ser chamado de "DataTip" e o [Estado] pode ser chamado de "Ativo", resultando em um nome de cor de "DataTipActive". Como as dicas de dados têm texto, uma cor de primeiro plano e de plano de fundo precisa ser definida. Usando um emparelhamento plano de fundo/primeiro plano, o editor de cores criará automaticamente as cores "DataTipActive" para o plano de fundo e "DataTipActiveText" para o primeiro plano.

Se a parte da interface do usuário tiver apenas um estado, a parte [Estado] do nome poderá ser omitida. Por exemplo, se uma caixa de pesquisa tiver uma borda e não houver nenhuma alteração de estado que afete a cor da borda, o nome do token de cor da borda poderá ser simplesmente chamado de "SearchBoxBorder".

Alguns nomes de estado comuns incluem:

Ativa
Inativos
MouseOver
MouseDown
Selecionadas
Focalizado

Exemplos de alguns nomes de token para partes de um controle de item de lista:
ListItem
ListItemBorder
ListItemMouseOver
ListItemMouseOverBorder
ListItemSelected
ListItemSelectedBorder
ListItemDisabled
ListItemDisabledBorder

Etapa 2: Escolha os tons que o elemento da interface do usuário usará para cada tema e a cor do sistema para Alto Contraste.

Ao escolher cores personalizadas para a interface do usuário, selecione um elemento de interface do usuário existente semelhante e use suas cores como base. As cores dos elementos da interface do usuário in-the-box passaram por revisão e teste, portanto, parecerão apropriadas e se comportarão corretamente em todos os temas.

Passo 3: Use o editor de cores para criar novos tokens de cores.

Inicie o editor de cores e abra ou crie um novo arquivo de cores de tema personalizado .xml. Selecione Editar > nova cor no menu. Isso abre uma caixa de diálogo para especificar a categoria e um ou mais nomes para entradas de cores dentro dessa categoria:

Selecione uma categoria existente ou selecione Nova categoria para criar uma nova categoria . Outra caixa de diálogo será aberta, criando um novo nome de categoria:

A nova categoria ficará disponível no menu suspenso Nova categoria Cor . Depois de escolher uma categoria, insira um nome por linha para cada novo token de cor e selecione "Criar" quando terminar:

Os valores de cor são mostrados em pares de fundo/primeiro plano, com "Nenhum" indicando que a cor não foi definida. Nota: se uma cor não tiver um par de cores de texto/cor de fundo, então apenas o plano de fundo precisa ser definido.

Para editar um token de cor, selecione uma entrada de cor para o tema (coluna) desse token. Adicione o valor de cor digitando um valor de cor hexadecimal no formato ARGB de 8 dígitos, inserindo um nome de cor do sistema na célula ou usando o menu suspenso para selecionar a cor desejada por meio de um conjunto de controles deslizantes de cores ou uma lista de cores do sistema.

Para componentes que não precisam exibir texto, insira apenas um valor de cor: a cor do plano de fundo. Caso contrário, insira valores para a cor do plano de fundo e do texto, separados por uma barra para frente.

Ao inserir valores para Alto Contraste, insira nomes de cores válidos do sistema Windows. Não insira valores ARGB codificados. Você pode exibir uma lista de nomes de cores válidos do sistema selecionando "Plano de fundo: Sistema" ou "Primeiro plano: Sistema" nos menus suspensos de valor de cor. Ao criar elementos que tenham componentes de texto, use o par de cores do sistema de texto/plano de fundo correto ou o texto pode estar ilegível.

Quando terminar de criar, definir e editar os tokens de cores, salve-os no formato .xml ou .pkgdef desejado. Os tokens de cores sem um plano de fundo nem um conjunto de primeiro plano serão salvos como cores vazias em .xml formato, mas descartados no formato .pkgdef. Uma caixa de diálogo avisará sobre a possível perda de cor se você tentar salvar cores vazias em um arquivo .pkgdef.

Etapa 4: Use as cores em uma extensão do Visual Studio.

Depois de definir os novos tokens de cor, inclua o .pkgdef no arquivo de projeto com "Build Action" definido como "Content" e "Include in VSIX" definido como "True".

No Editor de cores de extensão do Visual Studio, escolha Código de recurso de exibição de arquivo > para exibir o código que é usado para acessar as cores personalizadas na interface do usuário baseada em WPF.

Inclua esse código em uma classe estática no projeto. Uma referência a Microsoft.VisualStudio.Shell.<VSVersion.0>.dll precisa ser adicionado ao projeto para usar o tipo 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
    }
}

Isso permite o acesso às cores no código XAML e permite que a interface do usuário responda às alterações de tema.

<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>

Etapa 5: Testar as alterações no Visual Studio.

O editor de cores pode aplicar temporariamente tokens de cores às instâncias em execução do Visual Studio para exibir alterações em tempo real nas cores sem recriar o pacote de extensão. Para fazer isso, clique no botão "Aplicar este tema à execução de janelas do Visual Studio" localizado no cabeçalho de cada coluna de tema. Esse tema temporário irá desaparecer quando o VSIX Color Editor for fechado.

VSIX Color Editor Apply

Para tornar as alterações permanentes, recrie e reimplante a extensão do Visual Studio depois de adicionar as novas cores ao arquivo .pkgdef e escrever o código que usará essas cores. A reconstrução da extensão do Visual Studio mesclará os valores do Registro para as novas cores no restante dos temas. Em seguida, reinicie o Visual Studio, exiba a interface do usuário e verifique se as novas cores aparecem conforme o esperado.

Observações

Essa ferramenta destina-se a ser usada para criar cores personalizadas para os temas preexistentes do Visual Studio ou para editar as cores de um tema personalizado do Visual Studio. Para criar temas personalizados completos do Visual Studio, baixe a extensão Editor de Temas de Cores do Visual Studio na Galeria de Extensões do Visual Studio.

Saída de exemplo

Saída de cores XML

O arquivo .xml gerado pela ferramenta será semelhante a este:

<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>

Saída de cores PKGDEF

O arquivo .pkgdef gerado pela ferramenta será semelhante a este:

[$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:...

Wrapper de chaves de recurso C#

As chaves de recurso de cor geradas pela ferramenta serão semelhantes a esta:

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
    }
}

Wrapper de dicionário de recursos WPF

As chaves ResourceDictionary coloridas geradas pela ferramenta serão semelhantes a esta:

<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>

Compartilhar via

Editor de cores do VSIX

Como usar a ferramenta

Observações

Saída de exemplo

Recursos adicionais