Adapte seus recursos para idioma, escala, alto contraste e outros qualificativos

2025-06-10

Este tópico explica o conceito geral de qualificadores de recursos, como usá-los e a finalidade de cada um dos nomes de qualificadores. 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 adaptados a contextos de tempo de execução, como linguagem de exibição, alto contraste, fator de escala de exibiçãoe muitos outros. A maneira de fazer isso é nomear as pastas ou arquivos de seus recursos para corresponder aos nomes de qualificador 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 mais informações sobre a proposta de valor da localização da sua aplicação, veja a seção Globalização e localização.

Nome do qualificador, valor associado e qualificador

Um nome de qualificador é uma chave de mapeamento para um conjunto de valores de qualificador. Aqui estão o nome do qualificador e os valores do qualificador para comparação.

Contexto	Nome do qualificador	Valores dos qualificadores
A configuração de alto contraste	contraste	padrão, alto, preto, branco

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.

Assim, para alto contraste, o conjunto de qualificadores é contrast-standard, contrast-high, contrast-blacke contrast-white. Os nomes e os valores dos qualificadores não são sensíveis a maiúsculas e 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 pastas se você tiver vários arquivos de ativos 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 recursos da pasta nomeada para o qualificador apropriado. Assim, se a configuração for Alto Contraste Preto, os arquivos de recursos na pasta \Assets\Images\contrast-black serão carregados. Se a definição for Nenhum (ou seja, o computador não está no modo de alto contraste), então os arquivos de recursos na pasta \Assets\Images\contrast-standard 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. Você pode preferir 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 é o que é carregado. Essa lógica de correspondência funciona da mesma maneira para nomes de arquivos e para nomes de pastas.

Fazer referência a uma cadeia de caracteres ou recurso de imagem pelo nome

Consulte um identificador de recurso de cadeia de caracteres da marcação XAML, um identificador de recurso de cadeia de caracteres do código, e faça referência a uma imagem ou outro ativo da marcação XAML e do código.

Jogos de qualificação reais e neutros

Você não precisa fornecer um arquivo de recurso para cada valor qualificador do . Por exemplo, se você achar que só precisa de um ativo visual para alto contraste e outro para contraste padrão, então você pode 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 de real para qualquer configuração de alto contraste quando o alto contraste é em. Em outras palavras, é uma partida próxima, então é preferível. Uma correspondência real de só pode ocorrer se o qualificador incluir um valor real de, como neste caso. Neste caso, é um valor de real para .

O arquivo nomeado logo.png não tem nenhum qualificador de contraste nele. A ausência de um qualificador é um valor neutro. Se nenhuma correspondência preferida 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 de é a melhor correspondência possível de encontrar e, portanto, o ativo é então carregado.

Se alterares o nome de logo.png para logo.contrast-standard.png, então o nome do ficheiro conterá um valor qualificador real de logo.contrast-standard.png. Com o alto contraste desligado, haveria uma correspondência exata com logo.contrast-standard.png, e esse é o arquivo de recurso 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 pastas em vez de nomes de arquivos. Nesse caso, omitir o nome da pasta inteiramente lhe dará 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.

Qualificadores múltiplos

Você pode combinar qualificadores em nomes de pastas e arquivos. Por exemplo, talvez queira que a sua aplicação carregue ativos de imagem quando o modo de alto contraste estiver ativo 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 que logo.png e os outros arquivos sejam carregados, as definiçõ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 com 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. Isso geralmente é usado apenas por desenvolvedores de aplicativos japoneses para fornecer uma string 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).

O seu sistema de destino ou o seu aplicativo devem fornecer um valor com os quais os qualificadores alternateform são comparados. Não utilize o prefixo msft- para os seus próprios valores personalizados do qualificador alternateform.

Configuração

É improvável que precises do nome qualificador configuration. Pode ser usado para especificar recursos que são aplicáveis apenas a um determinado ambiente de criação, como recursos de teste apenas.

O configuration qualificador é usado para carregar um recurso que melhor corresponde ao valor da variável de MS_CONFIGURATION_ATTRIBUTE_VALUE ambiente. Assim, você pode definir a variável para 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 são carregados que melhor correspondem a esse valor. 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 usa isso como o valor para o qualificador de custom 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 precises do nome qualificador devicefamily. Você pode e deve evitar usá-lo sempre que possível, porque existem técnicas que você pode usar em vez disso que são muito mais convenientes e robustas. Essas técnicas são descritas em Detetando a plataforma em que a sua aplicação está sendo executada e Código de versão adaptável.

Mas, como último recurso, é possível usar os qualificadores devicefamily para nomear as pastas que contêm as suas vistas XAML (uma vista XAML é um ficheiro XAML que contém o layout e os controlos da interface de utilizador).

\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 partilha o mesmo MainPage.xaml.cs, que permanece inalterado no 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 sendo executado na família de dispositivos móveis, o elemento <TextBlock x:Uid="DeviceFriendlyName"/> da 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 da interface do usuário.

DXFeatureLevel

É improvável que precises do nome qualificador dxfeaturelevel. Ele foi projetado para ser usado com ativos de jogos 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.

Região Principal

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

Língua

Um language qualificador corresponde à configuração de idioma de exibição. Os valores incluem qualquer etiqueta de idioma BCP-47 válida . Para obter uma lista de línguas, consulte o registo de subtags de língua IANA.

Se você quiser que seu aplicativo ofereça suporte a diferentes idiomas 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ê pode fazer uma cópia traduzida desse Arquivo de Recursos para cada idioma compatível com seu aplicativo.

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 parte language- de um qualificador language (ou seja, o nome do qualificador). Você não pode fazer isso com os outros tipos de qualificadores; e você só pode fazê-lo 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.

Direção de Layout

Um qualificador layoutdirection corresponde à direção do layout da configuração de 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 na sua interface do utilizador responderão à direção do layout adequadamente se definir a sua propriedade FlowDirection (consulte Ajustar layout e fontes e suportar RTL). No entanto, o qualificador layoutdirection é para casos em que a simples inversão não é adequada, permitindo responder à direcionalidade da ordem de leitura específica e ao alinhamento de texto de maneiras mais gerais.

Escala

O Windows seleciona automaticamente um fator de escala para cada monitor com base em seu DPI (pontos por polegada) e na distância de visualização do dispositivo. Veja 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 mais próximo e dimensioná-lo. 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 recurso com a escala imediatamente superior.

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 scale e targetsize, consulte Qualificar um recurso de imagem para o tamanho-alvo.

Tamanho do alvo

O qualificador targetsize é usado principalmente para especificar ícones de associação de tipo de arquivo ou ícones de protocolo a serem exibidos no Explorador de Arquivos. O valor do qualificador representa o comprimento lateral 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 o valor qualificador de targetsize em vários tamanhos para o ícone da aplicação (/Assets/Square44x44Logo.png) na guia Ativos Visuais do editor de manifesto do pacote de aplicações.

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

Tema

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

Tema claro do shell e recursos não revestidos

O Windows 10 May 2019 Update introduziu um novo tema "light" para o Shell do Windows. 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 aplicações que forneceram ativos altform não prateados para a barra de tarefas e os alternadores de janela (Alt+Tab, Modo de exibição de Tarefas, etc.), deve-se verificar se eles têm contraste aceitável em um plano de fundo claro.

Fornecendo recursos específicos de temas leves

As aplicações que desejam fornecer um recurso personalizado para o tema light shell podem usar um novo qualificador alternativo de recurso: altform-lightunplated. Este qualificador reflete o qualificador altform-unplated existente.

Considerações de nível inferior

As aplicações não devem usar o qualificador theme-light com o qualificador altform-unplated. 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 qualificador altform-lightunplated evita esse problema.

Comportamento de compatibilidade

Para compatibilidade com versões anteriores, o Windows inclui lógica para detetar í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 padrão do recurso.