Квалификаторы в MRM
Индексатор ресурсов (и среда выполнения MRT) использует квалификаторы для определения контекстов, в которых должен использоваться данный кандидат ресурсов. Каждый ресурс имеет имя и один или несколько кандидатов (или значений), а каждый кандидат имеет ноль или несколько квалификаторов. Дополнительные сведения об именовании ресурсов см. в статье "Имена ресурсов" в MRM.
Например, может быть строковый ресурс с именем приветствия с тремя разными кандидатами для трех разных локализаций:
- Для английского языка текст "Hello"
- Для немецкого языка текст "Холло"
- Для корейского языка текст "안녕하세요"
Эти кандидаты добавляются в индексатор с правильными квалификаторами языка, и они хранятся в файле PRI, чтобы MRT знал, какой из них следует использовать во время выполнения. Например, чтобы добавить эти три строки в индексатор, можно использовать следующее:
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 */ }
Язык является только одним из возможных квалификаторов; другие распространенные квалификаторы включают масштабирование (для указания изображений с разными разрешениями) или Контрастности (для различных параметров контрастности). Полный список квалификаторов указан в разделе ResourceContext.QualifierValues.
Обратите внимание, что "короткая" форма квалификаторов (например, lang вместо языка) не поддерживается API MRM; необходимо использовать длинную форму. Тем не менее функции MrmIndexFileAutoQualifiers и MrmIndexResourceContainerAutoQualifiers, которые выводили квалификаторы из путей к файлам, поддерживают короткие формы.
Квалификаторы указываются в виде строк в форме name-value, например language-en или scale-200.
(Значения для a Квалификатор языка также может содержать дефисы, например en-us.) Имя и значение не учитывает регистр, поэтому LANGUAGE-EN-USLanguage-En-Usи language-en-us все эквивалентны.
Обратите внимание, что это ошибка, чтобы указать двух кандидатов для одного ресурса с одинаковыми квалификаторами, но разными значениями. К сожалению, эта ошибка не возникает при добавлении ресурсов в индексатор (например, при вызове MrmIndexString), но во время создания файла PRI поколение вернет ERROR_MRM_DUPLICATE_ENTRY но не указывает, какой ресурс вызвал проблему.
Например, этот фрагмент кода будет выполнен успешно при добавлении дубликата кандидата, но завершится сбоем позже во время создания 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);
Если один и тот же кандидат добавляется дважды (например, в приведенном выше коде, если второй вызов повторил "красный" вместо использования "синий") дубликат игнорируется и ошибка не возникает.
Списки квалификатора
Кандидаты ресурсов могут иметь несколько квалификатора. Например, файлы изображений могут потребовать кандидатов на основе масштаба (100%, 200 %, т. д.) и Контрастности (стандартная или высокая). Если изображение содержит текст, оно также может быть квалифицировано на основе языка.
Несколько квалификаторов указываются в одной строке, разделенной подчеркиванием. Например, кандидат изображения для высокой контрастности в масштабе 200 % будет использовать квалификатор contrast-high_scale-200. Порядок, в котором квалификаторы указаны в списке, не имеет значения; MRT имеет встроенный порядок важности для каждого квалификатора (например , язык более важен, чем масштаб).
Хотя это не ошибка повторять квалификатор в списке квалификатора (даже с разными значениями), все, но первое будет игнорироваться.
language-en_language-en(укажите английский дважды — эффективный язык — английский)language-en_language-de(укажите английский, немецкий — эффективный язык — английский)language-de_language-en(укажите немецкий, то английский — эффективный язык — немецкий)
Как отмечалось выше, это ошибка добавления двух кандидатов ресурсов с одинаковыми квалификаторами, но разными значениями. Это независимо от порядка квалификаторов в списке квалификаторов.
Нейтральные кандидаты
При добавлении кандидатов ресурсов в индексатор можно указать строку эмптри (или пустой указатель) в качестве квалификатора, чтобы указать, что кандидат является "нейтральным" и может соответствовать любому контексту. Например, имя приложения, отображаемое в меню , может быть нейтральным кандидатом, так как имена приложений обычно не локализованы (и не зависят от других вещей, таких как масштабирование или контрастность). Нейтральные кандидаты можно использовать в дополнение к конкретным кандидатам при желании.
Например:
// 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");
Квалификаторы по умолчанию
При создании файла конфигурации (с помощью одной из функций MrmCreateConfig...) или создании индексатора ресурсов (с помощью одной из функций MrmCreateResourceIndexer...) значения по умолчанию являются квалификаторами (например, языком), которые указывают на использование кандидатов ресурсов, если нет лучших совпадений. Например, если приложение имеет ресурсы на английском и французском языках, но оно выполняется на системе с набором языков на японском языке, язык, указанный как "квалификатор по умолчанию" при создании файла PRI будет использоваться. Квалификаторы по умолчанию также определяют, какой язык и масштаб следует использовать для создания основного файла PRI при использовании упаковки AutoSplit (дополнительные сведения см. в разделе MrmPackagingMode).
Обратите внимание, что все ресурсы должны иметь кандидат, указанный с квалификаторами по умолчанию (или нейтральным кандидатом), в противном случае не было бы ничего, чтобы вернуться в случае, если не было лучшего совпадения. Обратите внимание, что не удается предоставить резервный кандидат не считается ошибкой (индексатор создаст пустой строковый кандидат для вас), но это может привести к плохому интерфейсу пользователя или ошибкам приложений.