Compartilhar via

Qualificadores em MRM

  • Artigo

O Indexador de Recursos (e o runtime do MRT) usa "qualificadores" para determinar os contextos nos quais um determinado candidato a recurso deve ser usado. Cada recurso tem um nome e um ou mais candidatos (ou valores), e cada candidato tem zero ou mais qualificadores. Para obter mais informações sobre como nomear recursos, consulte Nomes de recursos no MRM.

Por exemplo, pode haver um recurso de cadeia de caracteres chamado greeting com três candidatos diferentes para três localizações diferentes:

  • Para inglês, o texto "Hello"
  • Para o alemão, o texto "Hallo"
  • Para coreano, o texto "안녕하세요"

Esses candidatos são adicionados ao Indexador com os qualificadores de idioma corretos e são armazenados no arquivo PRI para que o MRT saiba qual usar em runtime. Por exemplo, para adicionar essas três cadeias de caracteres a um indexador, pode-se usar:

    HRESULT hr{};
    hr = MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hello", L"language-en");
    hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hallo", L"language-de");
    hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"안녕하세요", L"language-ko");
    if (FAILED(hr)) { /* error handling */ }

Idioma é apenas um dos qualificadores possíveis; outros qualificadores comuns incluem Escala (para especificar imagens em diferentes resoluções) ou Contraste (para diferentes configurações de contraste). Uma lista completa de qualificadores está listada no tópico ResourceContext.QualifierValues.

Observe que a forma "curta" dos qualificadores (por exemplo, "lang" em vez de "language") não é suportada pelas APIs do MRM; você deve usar a forma longa. No entanto, as funções MrmIndexFileAutoQualifiers e MrmIndexResourceContainerAutoQualifiers que inferem qualificadores de caminhos de arquivo dão suporte aos formulários curtos

Os qualificadores são especificados como strings no formato name-value, como language-en ou scale-200. (Os valores para um qualificador de idioma também pode conter hífens, como en-us.) Tanto o nome quanto o valor não diferenciam maiúsculas de minúsculas, portanto LANGUAGE-EN-US, Language-En-Use language-en-us são todos equivalentes.

Observe que é um erro especificar dois candidatos para o mesmo recurso com os mesmos qualificadores, mas valores diferentes. Infelizmente, esse erro não é exibido quando os recursos são adicionados ao indexador (por exemplo, ao chamar MrmIndexString), mas no momento em que o arquivo PRI é gerado, a geração retornará ERROR_MRM_DUPLICATE_ENTRY mas não fornecerá nenhuma indicação de qual recurso causou o problema.

Por exemplo, este snippet de código será bem-sucedido ao adicionar um candidato duplicado, mas falhará posteriormente durante a geração de PRI:

// Add "color = red". Returns S_OK, since all arguments are valid.
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"red", L"language-en"); 
// Add "color = blue". Returns S_OK, since all arguments are valid (in isolation).
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"blue", L"language-en"); 

// Fails with ERROR_MRM_DUPLICATE_ENTRY since there are two English candidates for "strings/color" 
// ("red" and "blue"). 
hr = MrmCreateResourceFile(indexer, MrmPackagingModeStandaloneFile, MrmPackagingOptionsNone, fileName);

Se exatamente o mesmo candidato for adicionado duas vezes (por exemplo, no código acima, se a segunda chamada repetir "vermelho" em vez de usar "azul"), a duplicata será ignorada e nenhum erro será gerado.

Listas de qualificadores

Os candidatos a recursos podem ter mais de um qualificador. Por exemplo, os arquivos de imagem podem precisar de candidatos com base em Escala (100%, 200%, etc.) e Contraste (padrão ou alto). Se a imagem contiver texto, ela também pode precisar ser qualificada com base no idioma.

Vários qualificadores são especificados em uma única cadeia de caracteres, separados por sublinhados. Por exemplo, uma imagem candidata para alto contraste em escala de 200% usaria o qualificador contrast-high_scale-200. A ordem em que os qualificadores são especificados na lista não importa; O MRT tem uma ordem interna de importância para cada qualificador (por exemplo, Idioma é mais importante do que a Escala).

Embora não seja um erro repetir um qualificador em uma lista de qualificadores (mesmo com valores diferentes), todos, exceto o primeiro, serão ignorados.

  • language-en_language-en (especifique o inglês duas vezes, o idioma efetivo é o inglês)
  • language-en_language-de (especifique inglês e depois alemão, o idioma efetivo é o inglês)
  • language-de_language-en (especifique alemão e inglês, o idioma efetivo é alemão)

Conforme observado acima, é um erro adicionar dois candidatos a recursos com os mesmos qualificadores, mas valores diferentes. Isso independentemente da ordem dos qualificadores em uma lista de qualificadores.

Candidatos neutros

Ao adicionar candidatos de recursos ao indexador, você pode especificar uma cadeia de caracteres emptry (ou ponteiro nulo) como o qualificador para indicar que o candidato é "neutro" e pode corresponder a qualquer contexto. Por exemplo, o nome do aplicativo mostrado no menu Iniciar pode ser um candidato neutro porque os nomes de aplicativos normalmente não são localizados (e não dependem de outras coisas, como Escala ou Contraste). Candidatos neutros podem ser usados além de candidatos específicos, se desejado.

Por exemplo:

// The name of the app is the same, regardless of language, scale, etc.
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppName", L"Contoso Widgets", nullptr); 

// The name of the publisher is always "Contoso Inc." except in Australia, where it is "Contoso PTY LTD".
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso Inc.", nullptr); 
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso PTY LTD", L"homeregion-au");

Qualificadores padrão

Ao criar um arquivo de configuração (por meio de uma das funções MrmCreateConfig... ) ou criar um Indexador de Recursos (por meio de uma das funções MrmCreateResourceIndexer... ) Os defaultQualifiers são os qualificadores (como idioma) que indicam os candidatos a recursos a serem usados se nenhuma correspondência melhor puder ser encontrada. Por exemplo, se um aplicativo tiver recursos em inglês e francês, mas estiver em execução no sistema com o idioma definido como japonês, o idioma especificado como o "qualificador padrão" quando o arquivo PRI foi criado será usado. Os qualificadores padrão também determinam qual idioma e escala devem ser usados para criar o arquivo PRI principal ao usar o empacotamento AutoSplit (consulte MrmPackagingMode para obter mais informações).

Observe que todos os recursos devem ter um candidato especificado com os qualificadores padrão (ou um candidato neutro), caso contrário, não haveria nada para recorrer caso não houvesse a melhor correspondência. Observe que a falha em fornecer um candidato de fallback não é considerada um erro (o indexador gerará um candidato de cadeia de caracteres vazia para você), mas pode resultar em uma experiência de usuário ruim ou bugs no aplicativo.