共用方式為

MRM 中的限定符

  • 發行項

資源索引器（和 MRT 執行時間）會使用「限定符」來判斷應該使用指定資源候選項目的內容。 每個資源都有一個名稱和一或多個候選專案（或值），而且每個候選專案都有零或多個限定符。 如需命名資源的詳細資訊，請參閱 MRM 中的資源名稱。

例如，可能有一個名為 greeting 的字串資源，其中包含三個不同的當地語系化候選專案：

  • 針對英文，文字 “Hello”
  • 對於德文，文字 “Hallo”
  • 對於韓文，文字 “안녕하세요”

這些候選專案會新增至具有正確語言限定符的索引器，這些候選專案會儲存在 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 */ }

語言 只是其中一個可能的限定符;其他通用限定符包括 Scale （用於指定不同解析度的影像）或 對比 （針對不同的對比設定）。 限定符的完整清單會列在 ResourceContext.QualifierValues 主題中。

請注意，MRM API 不支援限定符的「簡短」形式（例如「lang」而非「語言」;您必須使用長格式。 不過，從檔案路徑推斷限定符的 MrmIndexFileAutoQualifiers 和 MrmIndexResourceContainerAutoQualifiers 函式確實支持簡短形式。

限定符元會以 格式 name-value指定為字串，例如 language-en 或 scale-200。 （的 值語言 限定元也可能包含連字元，例如 en-us。名稱和值都不區分大小寫，因此 LANGUAGE-EN-US、 Language-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);

如果新增完全相同的候選專案兩次（例如，在上述程式代碼中，如果第二個呼叫重複的「紅色」而不是使用“blue”），則會忽略重複專案，而且不會產生任何錯誤。

限定符清單

資源候選專案可以有多個限定符。 例如，圖像檔可能需要以縮放比例（100%、200%等）和對比（標準或高）為基礎的候選專案。 如果影像包含文字，它可能也需要根據語言來限定。

在單一字串中指定多個限定符，並以底線分隔。 例如，縮放比例為 200% 的高對比度影像候選專案會使用限定符 contrast-high_scale-200。 清單中指定限定符的順序並不重要;MRT 對於每個限定符都有內建的重要性順序（例如 Language 比 Scale 更重要）。

雖然在限定符清單中重複限定符並非錯誤（即使有不同的值），但除了第一個值外，也會忽略全部。

  • language-en_language-en （指定英文兩次 - 有效語言為英文）
  • language-en_language-de （指定英文然後德文 - 有效語言為英文）
  • language-de_language-en （指定德文然後英文 - 有效語言為德文）

如上所述，新增兩個具有相同限定符但不同值的資源候選專案是錯誤的。 這與限定符清單中的限定符順序無關。

中性候選專案

將資源候選專案新增至索引器時，您可以將空置字串（或 Null 指標）指定為限定符，以指出候選專案為「中性」，而且可以符合任何內容。 例如，[開始] 功能表 中顯示的應用程式名稱可能是中性候選專案，因為應用程式名稱通常不會當地語系化（而且它們不相依於縮放或對比等其他專案）。 如有需要，除了特定候選專案之外，也可以使用中性候選專案。

例如：

// 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... 函式）時，defaultQualifiers 是限定符（例如語言），指出找不到更好的相符專案時要使用的資源候選專案。 例如，如果應用程式具有英文和法文的資源，但它是在系統上執行且語言設定為日文，則會使用 PRI 檔案時指定為「預設限定符」的語言。 預設限定符也會決定在使用 AutoSplit 封裝時，應該使用哪個語言和縮放比例來建立主要 PRI 檔案（如需詳細資訊，請參閱 MrmPackagingMode）。

請注意，所有資源 都應該 指定具有預設限定符的候選專案（或中性候選專案），否則如果沒有任何最佳比對，則不會回復任何專案。 請注意，無法提供後援候選 專案不會 被視為錯誤（索引器會為您產生空字串候選專案），但可能會導致使用者體驗或應用程式錯誤不佳。