Udostępnij za pośrednictwem

Kwalifikatory w narzędziu MRM

  • Artykuł

Indeksator zasobów (i środowisko uruchomieniowe MRT) używają "kwalifikatorów", aby określić konteksty, w których należy użyć danego kandydata zasobu. Każdy zasób ma nazwę i co najmniej jeden kandydat (lub wartości), a każdy kandydat ma zero lub więcej kwalifikatorów. Aby uzyskać więcej informacji na temat nazewnictwa zasobów, zobacz Nazwy zasobów w usłudze MRM.

Na przykład może istnieć zasób ciągu o nazwie powitanie z trzema różnymi kandydatami do trzech różnych lokalizacji:

  • W przypadku języka angielskiego tekst "Hello"
  • Dla języka niemieckiego tekst "Hallo"
  • W języku koreańskim tekst "안녕하세요"

Te kandydatów są dodawane do indeksatora z prawidłowymi kwalifikatorami języka i są one przechowywane w pliku PRI, aby mrT wiedział, którego z nich należy używać w czasie wykonywania. Aby na przykład dodać te trzy ciągi do indeksatora, można użyć:

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

Language jest tylko jednym z możliwych kwalifikatorów; inne typowe kwalifikatory obejmują Skalowanie (do określania obrazów w różnych rozdzielczościach) lub Kontrast (w przypadku różnych ustawień kontrastu). Pełna lista kwalifikatorów znajduje się w temacie ResourceContext.QualifierValues.

Należy pamiętać, że "krótka" forma kwalifikatorów (np. "lang" zamiast "język") nie jest obsługiwana przez interfejsy API MRM; należy użyć długiej postaci. Niemniej jednak funkcje MrmIndexFileAutoQualifiers i MrmIndexResourceContainerAutoQualifiers, które wywnioskują kwalifikatory ze ścieżek plików, obsługują krótkie formularze.

Kwalifikatory są określane jako ciągi w postaci name-value, takich jak language-en lub scale-200. (Wartości kwalifikatora języka mogą również zawierać łączniki, takie jak en-us). Zarówno nazwa, jak i wartość są bez uwzględniania wielkości liter, więc LANGUAGE-EN-US, Language-En-Usi language-en-us są równoważne.

Zwróć uwagę, że błąd polega na określeniu dwóch kandydatów dla tego samego zasobu z tymi samymi kwalifikatorami, ale różnymi wartościami. Niestety ten błąd jest nie wyświetlany, gdy zasoby są dodawane do indeksatora (np. podczas wywoływania MrmIndexString), ale w momencie wygenerowania pliku PRI zostanie zwrócony ERROR_MRM_DUPLICATE_ENTRY, ale nie określi, który zasób spowodował problem.

Na przykład ten fragment kodu zakończy się pomyślnie podczas dodawania zduplikowanego kandydata, ale później podczas generowania pri zakończy się niepowodzeniem:

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

Jeśli dokładnie ten sam kandydat jest dodawany dwa razy (np. w powyższym kodzie, jeśli drugie wywołanie powtarza się "czerwony" zamiast "niebieski"), duplikat zostanie zignorowany i nie zostanie wygenerowany żaden błąd.

Listy kwalifikatora

Kandydaci do zasobów mogą mieć więcej niż jeden kwalifikator. Na przykład pliki obrazów mogą wymagać kandydatów na podstawie skalowania (100%, 200%itp.) i Contrast (standard lub wysoki). Jeśli obraz zawiera tekst, może być również konieczne kwalifikowanie na podstawie Language.

Wiele kwalifikatorów jest określonych w jednym ciągu oddzielonym podkreśleniami. Na przykład kandydat na obraz o wysokim kontraście na poziomie 200% skalowany będzie używać kwalifikatora contrast-high_scale-200. Kolejność, w jakiej kwalifikatory są określone na liście, nie ma znaczenia; Funkcja MRT ma wbudowaną kolejność ważności dla każdego kwalifikatora (np. Language jest ważniejsza niż Scale).

Chociaż nie jest to błąd powtarzania kwalifikatora na liście kwalifikatora (nawet z różnymi wartościami), wszystkie, ale pierwsze zostaną zignorowane.

  • language-en_language-en (określ dwukrotnie angielski — efektywny język to angielski)
  • language-en_language-de (określ angielski, a następnie niemiecki — efektywny język to angielski)
  • language-de_language-en (określ język niemiecki, a następnie angielski — efektywny język to niemiecki)

Jak wspomniano powyżej, jest to błąd podczas dodawania dwóch kandydatów do zasobów z tymi samymi kwalifikatorami, ale różnymi wartościami. Jest to niezależnie od kolejności kwalifikatorów na liście kwalifikatorów.

Kandydaci neutralni

Podczas dodawania kandydatów zasobów do indeksatora można określić ciąg emptry (lub wskaźnik o wartości null) jako kwalifikator, aby wskazać, że kandydat jest "neutralny" i może być zgodny z dowolnym kontekstem. Na przykład nazwa aplikacji wyświetlanej w menu Start może być neutralna, ponieważ nazwy aplikacji nie są zwykle zlokalizowane (i nie zależą od innych elementów, takich jak Skalowanie lub Kontrast). Kandydaci neutralni mogą być używane oprócz konkretnych kandydatów, jeśli jest to konieczne.

Na przykład:

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

Domyślne kwalifikatory

Podczas tworzenia pliku konfiguracji (za pomocą jednej z funkcji MrmCreateConfig...) lub tworzenia indeksatora zasobów (za pośrednictwem jednego z MrmCreateResourceIndexer... funkcji) domyślne są kwalifikatory (takie jak język), które wskazują kandydatów do użycia zasobów, jeśli nie można znaleźć lepszych dopasowań. Jeśli na przykład aplikacja ma zasoby w języku angielskim i francuskim, ale jest uruchomiona w systemie z językiem ustawionym na japoński, język określony jako "domyślny kwalifikator" podczas tworzenia pliku PRI zostanie użyty. Domyślne kwalifikatory określają również, który język i skala powinny być używane do tworzenia głównego pliku PRI podczas korzystania z pakietu autosplit (zobacz MrmPackagingMode, aby uzyskać więcej informacji).

Należy pamiętać, że wszystkie zasoby powinny mieć kandydata określonego z domyślnymi kwalifikatorami (lub neutralnym kandydatem), w przeciwnym razie nie byłoby nic do powrotu w przypadku, gdy nie było najlepszego dopasowania. Należy pamiętać, że niepowodzenie podania kandydata rezerwowego nie jest nie brane pod uwagę błąd (indeksator wygeneruje kandydata na pusty ciąg), ale może to spowodować złe środowisko użytkownika lub błędy aplikacji.