Personalizar os recursos de idioma, escala, alto contraste e outros qualificadores

  • Artigo

Este tópico descreve o conceito geral dos qualificadores de recurso, como usá-los e a finalidade de cada nome de qualificador. Consulte ResourceContext.QualifierValues para obter uma tabela de referência de todos os valores de qualificador possíveis.

Seu aplicativo pode carregar ativos e recursos personalizados para contextos de tempo de execução, como linguagem de exibição, alto contraste, fator de escala de exibição e muitos outros. A maneira de fazer isso é nomear as pastas ou arquivos de seus recursos para corresponder aos nomes e valores de qualificador que correspondem a esses contextos. Por exemplo, talvez você queira que seu aplicativo carregue um conjunto diferente de ativos de imagem no modo de alto contraste.

Para obter mais informações sobre a proposta de valor de localização do aplicativo, consulte Globalização e localização.

Nome do qualificador, valor do qualificador e qualificador

Um nome de qualificador é uma chave que mapeia para um conjunto de valores de qualificador. Aqui estão o nome do qualificador e os valores do qualificador para contraste.

Contexto Nome do qualificador Valores de qualificador
A configuração de alto contraste contraste convencional, alta, preta, branca

Você combina um nome de qualificador com um valor de qualificador para formar um qualificador. <qualifier name>-<qualifier value> é o formato de um qualificador. contrast-standard é um exemplo de qualificador.

Portanto, para alto contraste, o conjunto de qualificadores é contrast-standard, contrast-high, contrast-blacke contrast-white. Os nomes e valores de qualificador não diferenciam maiúsculas de minúsculas. Por exemplo, contrast-standard e Contrast-Standard são o mesmo qualificador.

Usar qualificadores em nomes de pastas

Aqui está um exemplo de uso de qualificadores para nomear pastas que contêm arquivos de ativos. Use qualificadores em nomes de pasta se você tiver vários arquivos de ativo por qualificador. Dessa forma, você define o qualificador uma vez no nível da pasta e o qualificador se aplica a tudo dentro da pasta.

\Assets\Images\contrast-standard\<logo.png, and other image files>
\Assets\Images\contrast-high\<logo.png, and other image files>
\Assets\Images\contrast-black\<logo.png, and other image files>
\Assets\Images\contrast-white\<logo.png, and other image files>

Se você nomear suas pastas como no exemplo acima, seu aplicativo usará a configuração de alto contraste para carregar arquivos de recurso da pasta nomeada para o qualificador apropriado. Portanto, se a configuração for Preto de alto contraste, os arquivos de recurso na \Assets\Images\contrast-black pasta serão carregados. Se a configuração for Nenhum (ou seja, o computador não está no modo de alto contraste), os arquivos de recurso na \Assets\Images\contrast-standard pasta serão carregados.

Usar qualificadores em nomes de arquivo

Em vez de criar e nomear pastas, você pode usar um qualificador para nomear os próprios arquivos de recurso. Talvez você prefira fazer isso se tiver apenas um arquivo de recurso por qualificador. Aqui está um exemplo.

\Assets\Images\logo.contrast-standard.png
\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.contrast-black.png
\Assets\Images\logo.contrast-white.png

O arquivo cujo nome contém o qualificador mais apropriado para a configuração é aquele que é carregado. Essa lógica de correspondência funciona da mesma maneira para nomes de arquivo e nomes de pastas.

Referenciar uma cadeia de caracteres ou recurso de imagem por nome

Consulte Referir-se a um identificador de recurso de cadeia de caracteres da marcação XAML, Referir-se a um identificador de recurso de cadeia de caracteres do código e Referenciar uma imagem ou outro ativo da marcação e do código XAML.

Partidas classificatórias reais e neutras

Você não precisa fornecer um arquivo de recurso para cada valor de qualificador. Por exemplo, se você achar que só precisa de um ativo visual para alto contraste e outro para contraste padrão, poderá nomear esses ativos assim.

\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.png

O primeiro nome de arquivo contém o contrast-high qualificador. Esse qualificador é uma correspondência real para qualquer configuração de alto contraste quando o alto contraste está ativado. Em outras palavras, é uma correspondência próxima, por isso é preferível. Uma correspondência real só pode ocorrer se o qualificador contiver um valor real , como este. Nesse caso, high é um valor real para contrast.

O arquivo nomeado logo.png não tem nenhum qualificador de contraste. A ausência de um qualificador é um valor neutro . Se nenhuma correspondência preferencial puder ser encontrada, o valor neutro servirá como uma correspondência de fallback. Neste exemplo, se o alto contraste estiver desativado, não haverá correspondência real. A correspondência neutra é a melhor correspondência que pode ser encontrada e, portanto, o ativo logo.png é carregado.

Se você alterasse o nome de para logo.contrast-standard.png, o nome do logo.png arquivo conteria um valor de qualificador real. Com o alto contraste desativado, haveria uma correspondência real com logo.contrast-standard.png, e esse é o arquivo de ativo que seria carregado. Assim, os mesmos arquivos seriam carregados, sob as mesmas condições, mas por causa de correspondências diferentes.

Se você precisar apenas de um conjunto de ativos para alto contraste e um conjunto para contraste padrão, poderá usar nomes de pasta em vez de nomes de arquivo. Nesse caso, omitir totalmente o nome da pasta fornece a correspondência neutra.

\Assets\Images\contrast-high\<logo.png, and other images to load when high contrast theme is not None>
\Assets\Images\<logo.png, and other images to load when high contrast theme is None>

Para obter mais detalhes sobre como funciona a correspondência de qualificadores, consulte Sistema de Gerenciamento de Recursos.

Vários qualificadores

Você pode combinar qualificadores em nomes de pasta e arquivo. Por exemplo, talvez você queira que seu aplicativo carregue ativos de imagem quando o modo de alto contraste estiver ativado e o fator de escala de exibição for 400. Uma maneira de fazer isso é com pastas aninhadas.

\Assets\Images\contrast-high\scale-400\<logo.png, and other image files>

Para logo.png e os outros arquivos a serem carregados, as configurações devem corresponder a ambos os qualificadores.

Outra opção é combinar vários qualificadores em um nome de pasta.

\Assets\Images\contrast-high_scale-400\<logo.png, and other image files>

Em um nome de pasta, você combina vários qualificadores separados por um sublinhado. <qualifier1>[_<qualifier2>...] é o formato.

Você pode combinar vários qualificadores em um nome de arquivo no mesmo formato.

\Assets\Images\logo.contrast-high_scale-400.png

Dependendo das ferramentas e do fluxo de trabalho que você usa para a criação de ativos ou do que você acha mais fácil de ler e/ou gerenciar, você pode escolher uma única estratégia de nomenclatura para todos os qualificadores ou combiná-los para diferentes qualificadores.

Formulário alternativo

O alternateform qualificador é usado para fornecer uma forma alternativa de um recurso para alguma finalidade especial. Normalmente, isso é usado apenas por desenvolvedores de aplicativos japoneses para fornecer uma cadeia de caracteres furigana para a qual o valor msft-phonetic é reservado (consulte a seção "Suporte Furigana para cadeias de caracteres japonesas que podem ser classificadas" em Como se preparar para localização).

Seu sistema de destino ou seu aplicativo deve fornecer um valor com o qual alternateform os qualificadores são correspondidos. Não use o prefixo msft- para seus próprios valores de qualificador personalizados alternateform .

Configuração

É improvável que você precise do nome do configuration qualificador. Ele pode ser usado para especificar recursos que são aplicáveis somente a um determinado ambiente de tempo de criação, como recursos somente de teste.

O configuration qualificador é usado para carregar um recurso que melhor corresponde ao valor da variável de MS_CONFIGURATION_ATTRIBUTE_VALUE ambiente. Portanto, você pode definir a variável como o valor da cadeia de caracteres que foi atribuído aos recursos relevantes, por exemplo designer, ou test.

Contraste

O contrast qualificador é usado para fornecer recursos que melhor correspondam às configurações de alto contraste.

Personalizado

Seu aplicativo pode definir um valor para o custom qualificador e, em seguida, os recursos que melhor correspondem a esse valor são carregados. Por exemplo, talvez você queira carregar recursos com base na licença do seu aplicativo. Quando seu aplicativo é iniciado, ele verifica sua licença e a usa como o valor do custom qualificador chamando SetGlobalQualifierValue, conforme mostrado no exemplo de código.

public void SetLicenseLevel(BrandID brand)
{
    if (brand == BrandID.Premium)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Premium", ResourceQualifierPersistence.LocalMachine);
    }
    else if (brand == BrandID.Standard)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", " Standard", ResourceQualifierPersistence.LocalMachine);
    }
    else
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Trial", ResourceQualifierPersistence.LocalMachine);
    }
}

Nesse cenário, você daria aos seus recursos nomes que incluem os qualificadores custom-premium, custom-standarde custom-trial.

Família de dispositivos

É improvável que você precise do nome do devicefamily qualificador. Você pode e deve evitar usá-lo sempre que possível, pois existem técnicas que você pode usar que são muito mais convenientes e robustas. Essas técnicas são descritas em Detectando a plataforma em que seu aplicativo está sendo executado e Código adaptável de versão.

Mas, como último recurso, é possível usar qualificadores devicefamily para nomear pastas que contêm suas exibições XAML (uma exibição XAML é um arquivo XAML que contém layout e controles da interface do usuário).

\devicefamily-desktop\<MainPage.xaml, and other markup files to load when running on a desktop computer>
\devicefamily-mobile\<MainPage.xaml, and other markup files to load when running on a phone>

Ou você pode nomear arquivos.

\MainPage.devicefamily-desktop.xaml
\MainPage.devicefamily-mobile.xaml

Em ambos os casos, cada cópia de MainPage.[<qualifier>].xaml compartilha um , MainPage.xaml.cscomum que permanece inalterado em seu projeto em termos de nome, localização e conteúdo.

Você também pode usar um qualificador devicefamily para nomear um arquivo de recursos (.resw) ou pasta. Por exemplo, quando seu aplicativo estiver em execução na família de dispositivos móveis, o elemento <TextBlock x:Uid="DeviceFriendlyName"/> de interface do usuário usará os recursos de texto e primeiro plano definidos em seu Resources.devicefamily-mobile.resw arquivo se ele contiver

<data name="DeviceFriendlyName.Foreground">
    <value>Red</value>
</data>
<data name="DeviceFriendlyName.Text">
    <value>Mobile device</value>
</data>

Para obter mais informações sobre como usar um arquivo de recursos, consulte Localizar suas cadeias de caracteres de interface do usuário.

DXFeatureLevel

É improvável que você precise do nome do dxfeaturelevel qualificador. Ele foi projetado para ser usado com ativos de jogo Direct3D, para fazer com que os recursos de nível inferior sejam carregados para corresponder a uma configuração de hardware de nível inferior específica da época. Mas a prevalência dessa configuração de hardware agora é tão baixa que recomendamos que você não use esse qualificador.

HomeRegião

O homeregion qualificador corresponde à configuração do usuário para país ou região. Ele representa o local de residência do usuário. Os valores incluem qualquer marca de região BCP-47 válida. Ou seja, qualquer código de região de duas letras ISO 3166-1 alfa-2, mais o conjunto de códigos geográficos numéricos de três dígitos ISO 3166-1 para regiões compostas (consulte a composição de códigos de região da Divisão de Estatística das Nações Unidas M49). Os códigos para "agrupamentos econômicos e outros selecionados" não são válidos.

Idioma

Um language qualificador corresponde à configuração do idioma de exibição. Os valores incluem qualquer marca de idioma BCP-47 válida. Para obter uma lista de idiomas, consulte o registro de submarcas de idiomas da IANA.

Se você quiser que seu aplicativo dê suporte a diferentes linguagens de exibição e tiver literais de cadeia de caracteres em seu código ou em sua marcação XAML, mova essas cadeias de caracteres para fora do código/marcação e para um Arquivo de Recursos (.resw). Em seguida, você poderá fazer uma cópia traduzida desse arquivo de recursos para cada idioma ao qual o aplicativo dê suporte.

Normalmente, você usa um language qualificador para nomear as pastas que contêm seus arquivos de recursos (.resw).

\Strings\language-en\Resources.resw
\Strings\language-ja\Resources.resw

Você pode omitir a language- parte de um language qualificador (ou seja, o nome do qualificador). Você não pode fazer isso com os outros tipos de qualificadores; e você só pode fazer isso em um nome de pasta.

\Strings\en\Resources.resw
\Strings\ja\Resources.resw

Em vez de nomear pastas, você pode usar language qualificadores para nomear os próprios arquivos de recursos.

\Strings\Resources.language-en.resw
\Strings\Resources.language-ja.resw

Consulte Localizar suas cadeias de caracteres da interface do usuário para obter mais informações sobre como tornar seu aplicativo localizável usando recursos de cadeia de caracteres e como fazer referência a um recurso de cadeia de caracteres em seu aplicativo.

LayoutDirection

Um layoutdirection qualificador corresponde à direção do layout da configuração do idioma de exibição. Por exemplo, uma imagem pode precisar ser espelhada para um idioma da direita para a esquerda, como árabe ou hebraico. Os painéis de layout e as imagens em sua interface do usuário responderão à direção do layout adequadamente se você definir a propriedade FlowDirection (consulte Ajustar layout e fontes e dar suporte a RTL). No entanto, o qualificador é para casos em que a layoutdirection inversão simples não é adequada e permite que você responda à direcionalidade da ordem de leitura específica e ao alinhamento do texto de maneiras mais gerais.

Escala

O Windows seleciona automaticamente um fator de escala para cada exibição com base em seu DPI (pontos por polegada) e na distância de exibição do dispositivo. Consulte Pixels efetivos e fator de escala. Você deve criar suas imagens em vários tamanhos recomendados (pelo menos 100, 200 e 400) para que o Windows possa escolher o tamanho perfeito ou usar o tamanho e dimensioná-lo mais próximos. Para que o Windows possa identificar qual arquivo físico contém o tamanho correto da imagem para o fator de escala de exibição, use um scale qualificador. A escala de um recurso corresponde ao valor de DisplayInformation.ResolutionScale ou ao próximo recurso de maior escala.

Aqui está um exemplo de como definir o qualificador no nível da pasta.

\Assets\Images\scale-100\<logo.png, and other image files>
\Assets\Images\scale-200\<logo.png, and other image files>
\Assets\Images\scale-400\<logo.png, and other image files>

E este exemplo o define no nível do arquivo.

\Assets\Images\logo.scale-100.png
\Assets\Images\logo.scale-200.png
\Assets\Images\logo.scale-400.png

Para obter informações sobre como qualificar um recurso para ambos e scale targetsize, consulte Qualificar um recurso de imagem para targetsize.

Tamanho do alvo

O targetsize qualificador é usado principalmente para especificar ícones de associação de tipo de arquivo ou ícones de protocolo a serem mostrados no Explorador de Arquivos. O valor do qualificador representa o comprimento do lado de uma imagem quadrada em pixels brutos (físicos). O recurso cujo valor corresponde à configuração Exibir no Explorador de Arquivos é carregado; ou o recurso com o próximo maior valor na ausência de uma correspondência exata.

Você pode definir ativos que representam vários tamanhos de valor de targetsize qualificador para o Ícone do Aplicativo (/Assets/Square44x44Logo.png) na guia Ativos Visuais do designer de manifesto do pacote do aplicativo.

Para obter informações sobre como qualificar um recurso para ambos e scale targetsize, consulte Qualificar um recurso de imagem para targetsize.

Tema

O theme qualificador é usado para fornecer recursos que melhor correspondam à configuração padrão do modo de aplicativo ou à substituição do aplicativo usando Application.RequestedTheme.

Tema de luz do shell e recursos não revestidos

A atualização do Windows 10 de maio de 2019 introduziu um novo tema "claro" para o Windows Shell. Como resultado, alguns ativos de aplicativo que antes eram mostrados em um plano de fundo escuro agora serão mostrados em um plano de fundo claro. Para aplicativos que fornecem ativos não platados altform para a barra de tarefas e alternadores de janela (Alt+Tab, Exibição de Tarefas etc.), você deve verificar se eles têm contraste aceitável em um plano de fundo claro.

Fornecimento de ativos específicos do tema de luz

Os aplicativos que desejam fornecer um recurso personalizado para o tema de luz do shell podem usar um novo qualificador de recurso de formulário alternativo: altform-lightunplated. Esse qualificador espelha o qualificador existente sem placa altform.

Considerações de nível inferior

Os aplicativos não devem usar o theme-light qualificador com o altform-unplated qualificador. Isso causará um comportamento imprevisível no RS5 e em versões anteriores do Windows devido à maneira como os recursos são carregados para a barra de tarefas. Em versões anteriores do Windows, a versão theme-light pode ser usada incorretamente. O altform-lightunplated qualificador evita esse problema.

Comportamento de compatibilidade

Para compatibilidade com versões anteriores, o Windows inclui lógica para detectar ícones monocromáticos e verificar se ele contrasta com o plano de fundo pretendido. Se o ícone não atender aos requisitos de contraste, o Windows procurará uma versão branca de contraste do ativo. Se isso não estiver disponível, o Windows voltará a usar a versão platinada do ativo.

APIs importantes