如何使用限定符命名资源 (HTML)

项目
01/28/2016

[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅最新文档 ]

你可以使用限定符命名资源。限定符会标识应使用某个资源版本的上下文。

资源限定符

你可以调整文件和字符串资源，以支持多种显示比例、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 3 位地理代码（请参阅联合国统计司 M49 区域代码组合。）注意，"选定的经济体和其他分组"的代码是无效的。

主区域格式：

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

配置

使用配置限定符指定仅适用于给定编写环境的资源，如仅用于测试的资源。大部分应用开发人员不应使用此限定符。环境变量 MS_CONFIGURATION_ATTRIBUTE_VALUE 可设置为已分配给相关资源的字符串值（如 test）。

配置格式：

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 功能级别值恰好相同的资源，则使用具有第二低值的资源。

注意 DirectX 功能级别限定符从 Windows 8.1 开始受支持。

DirectX 功能级别限定符可能有两种格式。支持的值包括 DX9、DX10 和 DX11。

DirectX 功能级别格式

DXFeatureLevel-<value>
DXFL-<value>

示例：

DXFeatureLevel-DX10
DXFL-DX11

备注

如前所述，如果对于同一资源方案需要支持多种限定符模式，则限定符集内的任意格式都可以结合使用。要在限定符模式之间使用的分隔符为下划线 (_)。例如，下面是明确支持配置、缩放和布局方向的资源文件的路径：logo.config-test_scale-100_layoutdir-LTR.png