Como nomear recursos usando qualificadores (HTML)

Artigo
01/29/2016

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente ]

Você pode dar nome aos recursos usando qualificadores. Os qualificadores identificam o contexto em que uma versão de um recurso deve ser usada.

Qualificadores de recursos

Você pode personalizar os recursos de arquivo e cadeia de caracteres para dar suporte a várias escalas de exibição, idiomas da interface do usuário, configurações de alto contraste e muito mais. Os qualificadores de recursos são modificadores de pasta e nome de arquivo que identificam o contexto em que uma determinada versão de um recurso deve ser usada.

A convenção de nomenclatura padrão é

foldername/qualifiername-value_qualifiername-value/filename.qualifiername-value_qualifiername-value.ext

Por exemplo,

Images/en-US/homeregion-USA/logo.scale-100_contrast-white.png

é carregada fazendo referência a

Images/logo.png

Observação Recomendamos que você marque o idioma padrão nos arquivos de recursos de cadeia de caracteres (como en-US\resources.resw) e a escala padrão nas imagens (como logo.scale-100.png), mesmo que não seja preciso localizar esses arquivos nem fornecer imagens com várias resoluções.

Nomes de pastas inteiros são analisados para ver se há qualificadores. Os nomes de pastas são relacionados a um conjunto de qualificadores ou são considerados parte do caminho de arquivos lógico. O segmento pontilhado no arquivo imediatamente anterior à extensão do arquivo é considerado um token que indica os qualificadores. Vários qualificadores são separados por um caractere de sublinhado, e os qualificadores são tradicionalmente especificados com seus nomes e valores (com exceção do idioma quando usados em um nome de pasta).

Os desenvolvedores de aplicativos podem optar por usar nomes de pasta ou de arquivo para especificar ativos para um determinado conjunto de contextos ou uma combinação das duas estratégias, dependendo do fluxo de trabalho e das necessidades do aplicativo.

O recurso correto é automaticamente escolhido na hora da execução, com base no qualificador de cada recurso e no contexto atual. Por exemplo, você pode fornecer os seguintes ativos:

en-us\logo.scale-100.png
en-us\logo.scale-140.png
fr-fr\logo.scale-100.png
fr-fr\logo.scale-140.png

Em seguida, um usuário que preferir inglês (Estados Unidos) em uma exibição com escala 140 verá a imagem en-us\logo.scale-140.png. Para obter detalhes sobre a seleção de recursos em cenários mais complexos de fallback, veja Contexto de recursos.

As demais seções deste tópico contêm informações detalhadas sobre o conjunto de qualificadores e seus possíveis valores para cada dimensão compatível com a infraestrutura do recurso.

Importante Os formatos descritos aqui são para dentro do segmento qualificador de um nome de arquivo (ou do nome de pasta no caso de idiomas). Um ou mais qualificadores devem aparecer como um segmento dentro do nome de arquivo completo que vem depois do nome do recurso, e antes da extensão do arquivo, de acordo com esse formato basicamente de espaços reservados: name**.qualifiers.**ext. Os pontos (.) aqui são importantes porque eles fornecem o separador de sintaxe entre os segmentos. Você não pode usar um caractere de ponto de outra forma dentro de qualquer um dos formatos de qualificador.

Idioma (aplicativo)

O qualificador de idioma especifica o idioma BCP-47 do recurso. Os nomes de arquivo requerem o qualificador lang ou language junto com a marca de idioma, mas as pastas precisam apenas da marca de idioma. Para obter uma lista de idiomas, veja Registro da submarca de idioma IANA.

Formatos de nome de pasta:

<Any BCP-47 language tag>
lang-<Any BCP-47 language tag>
language-<Qualquer marca de idioma BCP-47>

Formatos de nome de arquivo:

lang-<Any BCP-47 language tag>
language-<Any BCP-47 language tag>

Exemplos:

es-MX/resources.resw
language-de-DE/UI.resw
images/logo.lang-fr-FR.png

O qualificador de idioma é comparado à lista de idiomas do aplicativo. As alterações no idioma do aplicativo em tempo de execução são propagadas como eventos (veja ResourceContext.QualifierValues). Um aplicativo não precisa definir ou substituir o idioma.

Escala

O qualificador de escala especifica o fator de escala do recurso. Ele costuma ser usado para imagens visualizadas em um dispositivo com DPI alta ou quando o aplicativo é visualizado com zoom. A escala de um recurso corresponde ao valor de Windows.Graphics.Display.DisplayProperties.ResolutionScale ou ao próximo recurso com a maior dimensão. Se você usar o qualificador de escala em um recurso, não deverá usar o qualificador targetsize.

Qualificadores de escala:

scale-80 (válido somente para recursos especificados no manifesto do aplicativo)
scale-100
scale-140
scale-180 (Windows)
scale-240 (Windows Phone)

As alterações na escala na hora da execução são propagadas como eventos (veja ResourceContext.QualifierValues).

Contraste

O qualificador de contraste especifica a configuração do tema de contraste do sistema. Standard é usado quando todos os temas de alto contraste estão desativados. High é válido em qualquer modo de alto contraste. Black representa quando as imagens com tela de fundo preta e primeiro plano branco são preferenciais. White representa quando as imagens com tela de fundo branca e primeiro plano preto são preferenciais. As configurações de tema High Contrast #1 e High Contrast #2 correspondem ao valor de qualificador Black.

contrast-standard
contrast-high
contrast-black
contrast-white

Região residencial

O qualificador de região residencial representa a localização residencial do usuário. Normalmente é especificado na instalação do Windows e pode ser acessado pelo Painel de Controle. Geralmente, esse qualificador (ResourceContext.QualifierValues) é substituído quando há algum outro provedor de dados para a localização. O valor pode ser qualquer marca de região BCP-47 válida, 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 para regiões compostas iso-3166-1 numeric (veja a seção sobre a Norma de composição de códigos de região M49 da Divisão de Estatísticas das Nações Unidas.) Observe que os códigos para "Indicadores econômicos selecionados e outros agrupamentos" não são válidos.

Formato de região residencial:

homeregion-<Region Code>

Exemplos:

homeregion-us
homeregion-jp
homeregion-419

O qualificador de região residencial corresponde a qualquer região composta pai.

Tamanho do alvo

O qualificador targetsize pode ser usado para especificar recursos de um determinado tamanho (em pixels). É usado principalmente para especificar ícones de associação de tipo de arquivo ou ícones de protocolo exibidos no Windows Explorer da área de trabalho. Esse qualificador costuma ser usado para imagens ou ícones quadrados e especifica uma única dimensão de imagem. O sistema ou aplicativo que solicita o recurso (ResourceContext.QualifierValues) deve especificar explicitamente um tamanho de alvo. Não há um padrão. Se usar o qualificador targetsize em um recurso, você não deve usar o qualificador de escala.

Formato de targetsize:

targetsize-<any positive integer>

Exemplos:

targetsize-16
targetsize-96

O contexto de tamanho do alvo corresponde ao próximo recurso com a maior qualificação.

Direção do layout

Use o qualificador de layout para especificar os recursos que aplicam o direcionamento de alinhamento de texto e ordem de leitura específicos. Por exemplo, uma imagem pode precisar ser espelhada para um idioma com leitura da direita para a esquerda como árabe ou hebraico. A maioria dos aplicativos pode usar mecanismos de inversão automática para espelhar imagens na hora da execução; porém, esse qualificador é para os casos em que a simples inversão não é adequada. Para saber mais, veja Como ajustar o layout para idiomas com leitura da direita para a esquerda e localizar fontes.

Formato de direção do layout:

layoutdir-LTR
layoutdir-RTL
layoutdir-TTBLTR
layoutdir-TTBRTL

Configuração

Use o qualificador de configuração para especificar os recursos aplicáveis apenas a um determinado ambiente em tempo de criação, como recursos somente de teste. Não é usado pela maioria dos desenvolvedores de aplicativos. A variável de ambiente MS_CONFIGURATION_ATTRIBUTE_VALUE poderá ser definida para o valor de cadeia de caracteres que foi atribuído aos recursos relevantes (como test).

Formato de configuração:

config-<MS_CONFIGURATION_ATTRIBUTE_VALUE>

Exemplos:

config-test
config-designer

Forma alternativa

O qualificador de forma alternativa pode ser usado para fornecer uma forma alternativa de um recurso para alguma finalidade específica. Normalmente é usado apenas por desenvolvedores de aplicativos em japonês para fornecer uma cadeia de caracteres furigana, para a qual é reservado o valor msft-phonetic. O sistema ou aplicativo deve fornecer um valor para usar esse qualificador em determinadas situações. Não há um padrão. Não use o prefixo msft- para seus próprios valores personalizados.

Formato de forma alternativo:

altform-<Any string between 1 and 16 chars>

Exemplos:

altform-msft-phonetic
altform-myapp-special

Nível de recursos do DirectX

O qualificador de nível de recurso DirectX representa o nível de recurso DirectX de adaptadores gráficos que serão usados para renderizar o recurso. Ele é geralmente usado para ativos de exibição Direct3D usados em jogos. O nível de recurso DirectX de um recurso corresponderá a um valor definido explicitamente em um Contexto de Recurso pelo aplicativo. Se um recurso com exatamente o mesmo valor de nível de recurso DirectX não estiver disponível, será usado o recurso com o próximo valor mais baixo disponível.

Observação O qualificador de nível de recurso DirectX tem suporte a partir do Windows 8.1.

Há dois formatos possíveis para o qualificador de nível de recurso DirectX. Os valores com suporte são DX9, DX10 e DX11.

Formato de nível de recurso DirectX

DXFeatureLevel-<value>
DXFL-<value>

Exemplos:

DXFeatureLevel-DX10
DXFL-DX11

Comentários

Como mencionado anteriormente, qualquer um desses formatos dentro do conjunto de qualificadores podem ser combinados caso haja necessidade de dar suporte a vários padrões de qualificador para o mesmo cenário de recurso. O separador a ser usado entre os padrões de qualificador é o caractere de sublinhado (_). Por exemplo, aqui está um caminho para um arquivo de recurso que dá suporte a configuração, escala e direção do layout explicitamente: logo.config-test_scale-100_layoutdir-LTR.png