Condividi tramite

Qualificatori in MRM

  • Articolo

L'indicizzatore di risorse (e il runtime MRT) usano "qualificatori" per determinare i contesti in cui deve essere usato un determinato candidato alla risorsa. Ogni risorsa ha un nome e uno o più candidati (o valori) e ogni candidato ha zero o più qualificatori. Per altre info sulla denominazione delle risorse, vedi Nomi delle risorse in MRM.

Ad esempio, potrebbe essere presente una risorsa stringa denominata greeting con tre candidati diversi per tre diverse localizzazioni:

  • Per l'inglese, il testo "Hello"
  • Per il tedesco, il testo "Hallo"
  • Per il coreano, il testo "안녕하세요"

Questi candidati vengono aggiunti all'indicizzatore con i qualificatori di lingua corretti e questi vengono archiviati nel file PRI in modo che MRT sappia quale usare in fase di esecuzione. Ad esempio, per aggiungere queste tre stringhe a un indicizzatore, è possibile usare:

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

Il linguaggio è solo uno dei qualificatori possibili. Altri qualificatori comuni includono Scale (per specificare immagini con risoluzioni diverse) o Contrasto (per impostazioni di contrasto diverse). Un elenco completo dei qualificatori è elencato nell'argomento ResourceContext.QualifierValues .

Si noti che la forma "breve" dei qualificatori (ad esempio "lang" anziché "lingua") non è supportata dalle API MRM. È necessario usare il formato lungo. Tuttavia, le funzioni MrmIndexFileAutoQualifiers e MrmIndexResourceContainerAutoQualifiers che inferiscono qualificatori dai percorsi di file supportano i moduli brevi.

I qualificatori vengono specificati come stringhe nel formato name-value, ad esempio language-en o scale-200. (Valori per un oggetto Il qualificatore di linguaggio può contenere anche trattini, ad esempio en-us.) Sia il nome che il valore non fanno distinzione tra maiuscole e minuscole, quindi LANGUAGE-EN-US, Language-En-Use language-en-us sono tutti equivalenti.

Si noti che è un errore specificare due candidati per la stessa risorsa con gli stessi qualificatori ma valori diversi. Sfortunatamente, questo errore non viene visualizzato quando le risorse vengono aggiunte all'indicizzatore ,ad esempio quando si chiama MrmIndexString, ma al momento della generazione del file PRI, la generazione restituirà ERROR_MRM_DUPLICATE_ENTRY ma non fornirà alcuna indicazione della risorsa che ha causato il problema.

Ad esempio, questo frammento di codice avrà esito positivo quando si aggiunge un candidato duplicato, ma avrà esito negativo in un secondo momento durante la generazione 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 l'esatto candidato viene aggiunto due volte (ad esempio, nel codice precedente, se la seconda chiamata ripetuta "rossa" anziché "blu") il duplicato viene ignorato e non viene generato alcun errore.

Elenchi di qualificatori

I candidati alle risorse possono avere più di un qualificatore. Ad esempio, i file di immagine potrebbero richiedere candidati basati su scala (100%, 200%e così via) e contrasto (standard o alto). Se l'immagine contiene testo, potrebbe anche essere necessario essere qualificati in base alla lingua.

Più qualificatori vengono specificati in una singola stringa, separati da caratteri di sottolineatura. Ad esempio, un'immagine candidata per il contrasto elevato con scala del 200% usa il qualificatore contrast-high_scale-200. L'ordine in cui i qualificatori sono specificati nell'elenco non è rilevante; MRT ha un ordine di importanza predefinito per ogni qualificatore (ad esempio , il linguaggio è più importante di Scale).

Anche se non è un errore ripetere un qualificatore in un elenco qualificatore (anche con valori diversi), tutto ma il primo verrà ignorato.

  • language-en_language-en (specificare due volte l'inglese - la lingua effettiva è inglese)
  • language-en_language-de (specificare l'inglese e il tedesco - la lingua effettiva è inglese)
  • language-de_language-en (specificare il tedesco e quindi l'inglese - la lingua effettiva è il tedesco)

Come indicato in precedenza, è un errore aggiungere due candidati risorsa con gli stessi qualificatori ma valori diversi. Ciò è indipendentemente dall'ordinamento dei qualificatori in un elenco qualificatore.

Candidati neutrali

Quando si aggiungono candidati risorsa all'indicizzatore, è possibile specificare una stringa vuota (o un puntatore Null) come qualificatore per indicare che il candidato è "neutrale" e può corrispondere a qualsiasi contesto. Ad esempio, il nome dell'app visualizzato nel menu Start può essere un candidato neutro perché i nomi delle app non sono in genere localizzati (e non dipendono da altri elementi, ad esempio Scale o Contrast). I candidati neutrali possono essere utilizzati oltre a candidati specifici, se necessario.

Ad esempio:

// 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");

Qualificatori predefiniti

Quando si crea un file di configurazione (tramite una delle funzioni MrmCreateConfig) o si crea un indicizzatore di risorse (tramite una delle funzioni MrmCreateResourceIndexer... ) I qualificatori predefiniti sono i qualificatori (ad esempio la lingua) che indicano i candidati alle risorse da usare se non è possibile trovare corrispondenze migliori. Ad esempio, se un'app dispone di risorse in inglese e francese, ma è in esecuzione nel sistema con la lingua impostata sul giapponese, la lingua specificata come "qualificatore predefinito" al momento della creazione del file PRI verrà usata. I qualificatori predefiniti determinano anche la lingua e la scala da usare per creare il file PRI principale quando si usa la creazione di pacchetti AutoSplit (vedere MrmPackagingMode per altre informazioni).

Si noti che tutte le risorse devono avere un candidato specificato con i qualificatori predefiniti (o un candidato neutro), altrimenti non ci sarebbe nulla a cui eseguire il fallback nel caso in cui non vi fosse una corrispondenza migliore. Si noti che non è possibile fornire un candidato di fallback non è considerato un errore (l'indicizzatore genererà automaticamente un candidato a stringa vuota), ma può comportare un'esperienza utente o bug dell'applicazione scarsi.