共用方式為

如何使用限定詞命名資源 (HTML)

  • 發行項

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱 最新文件 ]

您可以使用限定詞來命名資源。限定詞可識別內容中應該使用的資源版本。

資源限定詞

您可以自訂檔案和字串資源，支援多種顯示比例、UI 語言、高對比設定以及其他。資源限定詞是資料夾和檔案名稱的修飾詞，用來識別內容中應該使用的特定資源版本。

標準命名慣例為

foldername/qualifiername-value_qualifiername-value/filename.qualifiername-value_qualifiername-value.ext

例如，

Images/en-US/homeregion-USA/logo.scale-100_contrast-white.png

的載入是參考

Images/logo.png

注意  建議您在字串資源檔上標示預設語言 (如 en-US\resources.resw) 並在影像上標示預設比例 (如 logo.scale-100.png)，即使這些檔案不會當地語系化也沒有提供多種解析度影像。

 

整個資料夾的名稱會針對限定詞進行剖析。然後資料夾名稱會與一組限定詞比對，或被視為邏輯檔案路徑的一部分。檔案中副檔名前面的點視為指定限定詞的代表。多個限定詞由底線分隔，而傳統做法是使用限定詞的名稱和值來指定限定詞 (除了用於資料夾名稱時的語言)。

應用程式開發人員可能選擇使用資料夾或檔案名稱來指定一組特定內容的資產，或是根據策略的工作流程和應用程式需求混用兩個策略。

在執行階段會根據每個資源的限定詞及目前的內容，自動選擇正確的資源。例如，您可以提供下列資產：

en-us\logo.scale-100.png
en-us\logo.scale-140.png
fr-fr\logo.scale-100.png
fr-fr\logo.scale-140.png

然後，慣用英文 (美國) 的使用者在比例 140 的顯示器上會看到 en-us\logo.scale-140.png 影像。如需在更複雜遞補案例中選取資源的詳細資料，請參閱資源內容。

這個主題的其他小節會詳述資源基礎結構支援的每個尺寸的限定詞組及它們的可能值。

重要事項  此處所述的格式是用於檔案名稱 (或語言案例中的資料夾名稱) 的限定詞區段內。根據這個大部分是預留位置的格式，一或多個限定詞應全部顯示為資源名稱後、副檔名之前之完整檔案名稱內的區段：name**.qualifiers.**ext 此處的句點 (.)很重要，因為它們是區段之間的語法分隔符號。您無法在任何限定詞的格式內使用點字元。

 

語言 (應用程式)

語言限定詞指定資源的 BCP-47 語言。檔案名稱需要 lang 或 language 限定詞及語言標記，但資料夾只需要語言標記。如需語言清單，請參閱 IANA 語言子標記登錄。

資料夾名稱格式：

  • <Any BCP-47 language tag>
  • lang-<Any BCP-47 language tag>
  • language-<任何 BCP-47 語言標記>

檔案名稱格式：

  • lang-<Any BCP-47 language tag>
  • language-<Any BCP-47 language tag>

範例：

es-MX/resources.resw
language-de-DE/UI.resw
images/logo.lang-fr-FR.png

語言限定詞會比對應用程式語言清單。在執行階段對應用程式語言所做的變更會當作事件傳播 (請參閱 ResourceContext.QualifierValues)。應用程式不需要設定或覆寫語言。

比例

比例限定詞指定資源的縮放比例。通常用於在較高 DPI 裝置上檢視影像或用於縮放應用程式時。資源的比例符合 Windows.Graphics.Display.DisplayProperties.ResolutionScale 的值，或下一個最大的縮放資源。 如果您對一個資源使用目標大小限定詞，則不應使用 targetsize 限定詞。

比例限定詞：

  • scale-80 (僅適用於應用程式資訊清單中指定的資源)
  • scale-100
  • scale-140
  • scale-180 (Windows)
  • scale-240 (Windows Phone)

在執行階段對比例所做的變更會當作事件傳播 (請參閱 ResourceContext.QualifierValues)。

對比

對比限定詞指定系統的對比佈景主題設定。Standard 用於所有高對比佈景主題關閉時。 High 在任何高對比模式中為有效。Black 表示慣用含有黑色背景與白色前景的影像。White 表示慣用含有白色背景與黑色前景的影像。High Contrast #1 和 High Contrast #2 佈景主題設定符合 Black 限定詞值。

contrast-standard
contrast-high
contrast-black
contrast-white

起始點區域

起始點區域限定詞代表使用者的起始點位置。通常是在 Windows 安裝時指定，而且可以從 [控制台] 存取。如果已知一些其他資料提供者的位置，通常會覆寫這個限定詞 (ResourceContext.QualifierValues)。這個值可以是任何有效的 BCP-47 區域標記，也就是任何 iso-3166-1 alpha 2 兩個字母的地區碼，加上一組 iso-3166-1 numeric 三位數的地理代碼，用來組成地區 (請參閱聯合國統計部門 M49 地區碼組合。)請注意，"Selected economic and other groupings" 的代碼不是有效的代碼。

起始點區域格式：

homeregion-<Region Code>

範例：

homeregion-us
homeregion-jp
homeregion-419

起始點區域限定詞符合任何父系組合區域。

目標大小

目標大小限定詞可以指定特定大小 (像素) 的資源。它主要是用來指定在桌面 Windows 檔案總管中顯示的檔案類型關聯圖示或通訊協定圖示。這個限定詞通常用於正方形影像或圖示，並只指定單一影像尺寸。要求資源 (ResourceContext.QualifierValues) 的系統或應用程式必須明確指定目標大小。它沒有預設值。 如果您對一個資源使用目標大小限定詞，則不應使用比例限定詞。

目標大小格式：

targetsize-<any positive integer>

範例：

targetsize-16
targetsize-96

目標大小內容符合下一個最大的限定資源。

配置方向

使用配置限定詞，指定套用特定閱讀順序及文字對齊的方向性資源。 例如，一個影像可能需要建立從右至左語言的鏡像，例如阿拉伯文或希伯來文。 大部分應用程式可以使用自動翻轉機制，在執行階段產生影像的鏡像；不過，這個限定詞是針對不適用簡單翻轉的情況。如需詳細資訊，請參閱如何調整 RTL 語言的配置和當地語系化字型。

配置方向格式：

  • layoutdir-LTR
  • layoutdir-RTL
  • layoutdir-TTBLTR
  • layoutdir-TTBRTL

設定

使用設定限定詞，指定只適用於特定撰寫時間環境的資源，例如僅用於測試的資源。 大部分的應用程式開發人員不應該使用這個限定詞。已經指派給相關資源 (如 test) 的字串值可以設定環境變數 MS_CONFIGURATION_ATTRIBUTE_VALUE。

設定格式：

config-<MS_CONFIGURATION_ATTRIBUTE_VALUE>

範例：

config-test
config-designer

其他形式

其他形式限定詞可以用來為某些特殊用途的資源提供其他形式。 這通常只有日文應用程式開發人員使用，以便提供假名註解字串，其中保留了 msft-phonetic 值。系統或應用程式必須提供一個值，才能在特殊情況下使用這個限定詞。它沒有預設值。對於您自己的自訂值，請不要使用 msft- 前置詞。

其他形式格式：

altform-<Any string between 1 and 16 chars>

範例：

altform-msft-phonetic
altform-myapp-special

DirectX 功能層級

DirectX 功能層級限定詞代表圖形卡的 DirectX 功能層級，這些圖形卡會用來轉譯資源。這通常用於遊戲中使用的 Direct3D 顯示資產。資源的 DirectX 功能層級會符合應用程式在資源內容上明確設定的值。如果沒有具有相同的 DirectX 功能層級值的資源，就會使用具有下一個可用的最低值的資源。

注意  Windows 8.1 開始支援 DirectX 功能層級限定詞。

 

DirectX 功能層級限定詞有兩種可能的格式。支援的值為 DX9、DX10 以及 DX11。

DirectX 功能層級格式

  • DXFeatureLevel-<value>
  • DXFL-<value>

範例：

DXFeatureLevel-DX10
DXFL-DX11

備註

如前所述，如果同一資源案例需要支援多個限定詞模式，可以將限定詞集合內的任何格式合併。限定詞模式之間使用的分隔符號是底線 (_)。例如，以下是明確支援設定、縮放及配置方向之資源檔案的路徑：logo.config-test_scale-100_layoutdir-LTR.png

相關主題

調整成像素密度的指導方針

支援高對比佈景主題

如何管理語言及地區

如何調整 RTL 語言的配置和當地語系化字型

如何準備當地語系化

如何指派自訂圖示給檔案類型

新增圖示、預覽及捷徑功能表

Windows.ApplicationModel.Resources.Core.ResourceContext.QualifierValues

Windows.Graphics.Display.DisplayProperties.ResolutionScale

外部連結

BCP-47 語言標記

IANA 語言子標記登錄

聯合國統計部門 M49 地區碼組合