針對語言、縮放比例、高對比及其他限定詞量身打造您的資源

  • 發行項

本主題說明資源限定詞的一般概念、其使用方式，以及每個限定詞名稱的用途。 請參閱 ResourceContext.QualifierValues 查看所有可用限定詞值的參照表。

應用程式所載入的資產和資源，可針對顯示語言、高對比、顯示比例因素等多種執行階段脈絡來量身打造。 要達成此目的，您在為資源的資料夾或檔案命名時，必須對照與這些脈絡對應的限定詞名稱和限定詞值。 舉例來說，您可能想讓應用程式以高對比模式載入多組影像資產。

如需有關將您的應用程式當地語系化的價值主張的詳細資訊，請參閱全球化和當地語系化。

限定詞名稱、限定詞值和限定詞

限定詞名稱是與限定詞值組合對應的關鍵。 以下為適用於對比的限定詞名稱和限定詞值。

上下文 限定詞名稱 限定詞值
高對比設定 contrast standard、high、black、white

將限定詞名稱和限定詞值組合起來就會形成限定詞。 <qualifier name>-<qualifier value>是限定詞的格式。 contrast-standard是限定詞的範例。

如為高對比，限定詞的組合就是 contrast-standard、contrast-high、contrast-black 和 contrast-white。 限定詞名稱和限定詞值無需區分大小寫。 舉例來說，contrast-standard 和 Contrast-Standard 是同一個限定詞。

在資料夾名稱使用限定詞

以下為使用限定詞來為包含資產檔案的資料夾命名的範例。 如果您的限定詞指涉多個資產檔案，請在資料夾名稱使用限定詞。 這樣一來，您只需在資料夾層級設定一次限定詞，該限定詞就會套用到資料夾中的全部項目。

\Assets\Images\contrast-standard\<logo.png, and other image files>
\Assets\Images\contrast-high\<logo.png, and other image files>
\Assets\Images\contrast-black\<logo.png, and other image files>
\Assets\Images\contrast-white\<logo.png, and other image files>

如果您按照上述範例命名資料夾，應用程式就會使用高對比設定，從命名為適用限定詞的資料夾載入資源檔案。 因此，如果設定是「高對比黑」，系統就會載入 \Assets\Images\contrast-black 資料夾的資源檔案。 如果設定是「無」(也就是電腦並非高對比模式)，系統就會載入 \Assets\Images\contrast-standard 資料夾的資源檔案。

在檔案名稱使用限定詞

您可以使用限定詞來命名資源檔案本身，無需另外建立與命名資料夾。 如果每個限定詞僅指涉一個資源檔案，建議您這麼做。 以下為範例。

\Assets\Images\logo.contrast-standard.png
\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.contrast-black.png
\Assets\Images\logo.contrast-white.png

檔案名稱包含的限定詞與設定最相符時，系統就會載入該檔案。 這種相符邏輯對於檔案名稱和資料夾名稱都相同。

依照名稱參照字串或影像資源

請參閱參照 XAML 標記的字串資源識別碼、參照程式碼的字串資源識別碼和參照 XAML 標記和程式碼的影像或其他資產。

實際與中性的限定詞相符

您不需要為每個限定詞值都提供資源檔案。 舉例來說，如果您發現高對比只需要一個視覺資產，標準對比也只需要一個，您就可以按照此方法為這些資產命名。

\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.png

第一個檔案名稱包含 contrast-high 限定詞。 高對比設為開啟時，該限定詞在任何高對比設定中皆為實際相符。 換句話說，它是相近的相符，因此是優先選項。 如果限定詞包含實際值，比如此範例，就會構成實際相符。 在此案例中，high 是 contrast 的實際值。

名為 logo.png 的檔案完全沒有適用於它的對比限定詞。 缺少限定詞時是中性值。 如果找不到優先的相符，則系統就會把中性值當作遞補的相符。 在此案例中，如果高對比已關閉，就沒有實際相符。 中性相符是系統能找到的最佳相符，因此會載入資產 logo.png。

如果您將名稱 logo.png 變更為 logo.contrast-standard.png，檔案名稱就會包含實際限定詞值。 高對比關閉時，存在與 logo.contrast-standard.png 的實際相符，它就會成為應載入的資產檔案。 因此，系統會在相同條件下載入相同檔案，但卻是基於不同的相符模式。

如果高對比只需要一組資產，標準對比也只需要一組，您就可以使用資料夾名稱代替檔案名稱。 在此案例中，完全刪去資料夾名稱就會取得中性相符。

\Assets\Images\contrast-high\<logo.png, and other images to load when high contrast theme is not None>
\Assets\Images\<logo.png, and other images to load when high contrast theme is None>

如需詳細了解限定詞相符的運作方式，請參閱資源管理系統。

多個限定詞

您可以將限定詞組合在資料夾和檔案名稱中。 舉例來說，高對比模式開啟，且顯示比例因素為 400 時，您可能是想讓應用程式載入影像資產。 您可以使用巢狀資料夾執行此動作。

\Assets\Images\contrast-high\scale-400\<logo.png, and other image files>

如要讓 logo.png 和其他檔案載入，設定必須與兩個限定詞都相符。

另一個選項是將多個限定詞組合在一個資料夾名稱中。

\Assets\Images\contrast-high_scale-400\<logo.png, and other image files>

您可以在資料夾名稱中組合多個限定詞，以底線分隔。 格式為 <qualifier1>[_<qualifier2>...]。

您可以使用相同格式，將多個限定詞組合在檔案名稱中。

\Assets\Images\logo.contrast-high_scale-400.png

視您建立資產時使用的工具和工作流程而定，或以您讀取和/或管理的最簡單方法而定，您可以選擇針對所有限定詞使用單一命名策略，或將不同限定詞組合起來。

AlternateForm

alternateform 限定詞係在某些特別用途中，用於提供資源的替代格式。 這種限定詞通常只有日本的應用程式開發人員會用來提供振假名字串，這類字串會保留值 msft-phonetic (請參閱如何為當地語系化做準備中的「針對可排序的日文字串支援振假名」)。

您的目標系統或應用程式必須依據相符的 alternateform 限定詞來提供值。 請勿在您的自訂 alternateform 限定詞值使用 msft- 前置詞。

組態

您不太可能需要 configuration 限定詞名稱。 它可指定的資源僅適用於特定的編寫階段環境，例如僅供測試的資源。

configuration 限定詞係用於載入與 MS_CONFIGURATION_ATTRIBUTE_VALUE 環境變數的值達成最佳相符的資源。 因此，您可以將變數設為已經指派給相關資源的字串值，例如 designer 或 test。

對比

contrast 限定詞係用於提供與高對比設定達成最佳相符的資源。

自訂

您的應用程式可以為 custom 限定詞設定一個值，然後載入與該值最相符的資源。 例如，您可能想要根據應用程式的授權載入資源。 當您的應用程式啟動時，它會檢查其授權並透過呼叫 SetGlobalQualifierValue 將其用做 custom 限定詞的值，如程式碼範例所示。

public void SetLicenseLevel(BrandID brand)
{
    if (brand == BrandID.Premium)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Premium", ResourceQualifierPersistence.LocalMachine);
    }
    else if (brand == BrandID.Standard)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", " Standard", ResourceQualifierPersistence.LocalMachine);
    }
    else
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Trial", ResourceQualifierPersistence.LocalMachine);
    }
}

在這個案例中，您將指定包含限定詞 custom-premium、custom-standard 和 custom-trial 的資源名稱。

DeviceFamily

您不太可能需要 devicefamily 限定詞名稱。 您可以盡可能避免使用它，因為有一些技術可以改用，更方便且更健全。 這些技術在偵測應用程式執行的平台和版本自適應程式碼中進行了描述。

但做為最後的手段，可以使用 devicefamily 限定詞來命名包含 XAML 檢視的資料夾 (XAML 檢視是包含 UI 配置和控制項的 XAML 檔案)。

\devicefamily-desktop\<MainPage.xaml, and other markup files to load when running on a desktop computer>
\devicefamily-mobile\<MainPage.xaml, and other markup files to load when running on a phone>

或者，您可以命名檔案。

\MainPage.devicefamily-desktop.xaml
\MainPage.devicefamily-mobile.xaml

無論哪種情況，每個 MainPage.[<qualifier>].xaml 複本都共用一個共同 MainPage.xaml.cs，它在您的專案中的名稱、位置和內容保持不變。

您也可以使用 devicefamily 限定詞來命名資源檔 (.resw)，或資料夾。 例如，當您的應用程式在行動裝置系列上執行時，UI 元素 <TextBlock x:Uid="DeviceFriendlyName"/> 將使用您的 Resources.devicefamily-mobile.resw 檔案中定義的文字和前台資源 (如果它包含)。

<data name="DeviceFriendlyName.Foreground">
    <value>Red</value>
</data>
<data name="DeviceFriendlyName.Text">
    <value>Mobile device</value>
</data>

有關使用資源文件的更多資訊，請參閱將 UI 字串當地語系化。

DXFeatureLevel

您不太可能需要 dxfeaturelevel 限定詞名稱。 它的設計是用於搭配 Direct3D 遊戲資產，以便在特定的降級硬體組態中載入相符的降級資源。 不過該硬體組態的普及率極低，因此我們建議您不要使用此限定詞。

HomeRegion

homeregion 限定詞對應使用者的國家或地區設定。 它代表使用者的住家位置。 任何有效的 BCP-47 地區標籤都是可用的值。 組成地區的值是任何 ISO 3166-1 alpha-2 雙字母地區代碼，加上一組三位元的 ISO 3166-1 數字地理代碼 (請參閱聯合國統計部門的 M49 地區代碼組成)。 「所選經濟與其它分組」的代碼無效。

語言

language 限定詞對應顯示語言設定。 任何有效的 BCP-47 語言標籤都是可用的值。 如需語言清單，請參閱 IANA 語言子標籤登錄。

如果您想讓應用程式支援其他顯示語言，且您的程式碼或 XAML 標記中有字串常值，請將程式碼/標記中的這些字串移到資源檔案 (.resw)。 您可以接著針對應用程式支援的每一種語言建立該資源檔案的翻譯複本。

您通常會使用 language 限定詞來命名包含資源檔案 (.resw) 的資料夾。

\Strings\language-en\Resources.resw
\Strings\language-ja\Resources.resw

您可以刪去 language 限定詞中的 language- 部分 (也就是限定詞名稱)。 此動作無法對其他限定詞類型執行，且僅適用於資料夾名稱。

\Strings\en\Resources.resw
\Strings\ja\Resources.resw

您可以使用 language 限定詞來命名資源檔案本身，無需另外命名資料夾。

\Strings\Resources.language-en.resw
\Strings\Resources.language-ja.resw

請參閱將 UI 字串當地語系化以詳細了解如何使用字串資源讓應用程式可當地語系化，以及如何參照應用程式中的字串資源。

LayoutDirection

layoutdirection 限定詞對應顯示語言設定的配置方向。 舉例來說，針對阿拉伯語或希伯來語這類由右至左書寫的語言，影像可能需要鏡像處理。 如果 UI 配置面板和影像的 FlowDirection 屬性設定正確，就會適當地回應配置方向 (請參閱調整配置與字型，並支援 RTL)。 不過，layoutdirection 限定詞適用於簡單的翻轉並不足夠的情況，它可讓您以更通用的方式回應特定閱讀順序和文字對齊的方向。

調整

Windows 會根據個別顯示器的 DPI (每英吋點數) 及裝置的檢視距離，自動選取比例因素。 請參閱有效像素和比例因素。 您必須建立數個建議尺寸的影像 (至少有 100、200 和 400)，以便讓 Windows 選擇理想尺寸，或使用最接近的尺寸並加以縮放。 這樣一來，Windows 就能識別哪個實體檔案包含與顯示比例因素相符的正確影像尺寸，您也能使用 scale 限定詞。 資源的縮放比例與值 DisplayInformation.ResolutionScale 相符，或下一個最大的縮放後資源相符。

以下為在資料夾層級設定限定詞的範例。

\Assets\Images\scale-100\<logo.png, and other image files>
\Assets\Images\scale-200\<logo.png, and other image files>
\Assets\Images\scale-400\<logo.png, and other image files>

此範例是在檔案層級設定。

\Assets\Images\logo.scale-100.png
\Assets\Images\logo.scale-200.png
\Assets\Images\logo.scale-400.png

如需限定資源的 scale 和 targetsize 的相關資訊，請參閱限定影像資源的 targetsize。

TargetSize

targetsize 限定詞主要用於指定要在檔案總管顯示的檔案類型關聯圖示或通訊協定圖示。 其限定詞值代表方形影像的 raw (實體) 像素邊長。 資源的值如與檔案總管的檢視設定相符，系統就會載入資源；如果找不到精確相符，則會載入擁有下一個最大值的資源。

您可以在應用程式套件資訊清單設計工具的 [視覺資產] 索引標籤定義資產，讓它們代表應用程式圖示 (/Assets/Square44x44Logo.png) 的數種 targetsize 限定詞值尺寸。

如需限定資源的 scale 和 targetsize 的相關資訊，請參閱限定影像資源的 targetsize。

佈景主題

theme 限定詞會提供與預設應用程式模式設定達成最佳相符的資源，或者使用 Application.RequestedTheme 來覆寫應用程式設定。

殼層淺色主題與無表層資源

Windows 10 的 2019 年 10 月更新版推出了新的 Windows Shell「淺色」主題。 因為如此，有些之前顯示為在深色背景的應用程式資產自此就顯示在淺色背景上。 應用程式如果為工作列和視窗切換工具 (Alt+Tab、工作檢視等) 提供 altform-unplated 資產，您必須確認它們在淺色背景上採用容許的對比。

為淺色主題提供特定資產

如果想讓應用程式為殼層淺色主題提供量身打造的資源，您可使用新的替代格式資源限定詞：altform-lightunplated 此限定詞會對現有 altform-unplated 限定詞進行鏡像處理。

降級考量

應用程式不應將 theme-light 限定詞與 altform-unplated 限定詞搭配使用。 基於資源載入工作列的方式，這麼做會使 RS5 和舊版的 Windows 發生不預期行為。 在舊版的 Windows，淺色主題的版本可能會有使用錯誤的情形。 altform-lightunplated 限定詞會避免這種問題。

相容性行為

為了向下相容，Windows 採納的邏輯會偵測單色圖示，並確認它與預期背景是否呈對比。 如果圖示不符合對比要求，Windows 會尋找該資產的「對比白」版本。 如果該版本也不存在，Windows 會以資產的有表層版本來遞補。

重要 API