本主题介绍资源限定符的一般概念、如何使用它们以及每个限定符名称的用途。 如需查看所有可能的限定符值的参考表，请参阅 ResourceContext.QualifierValues。
你的应用可以加载针对运行时上下文定制的资产和资源，例如显示语言、高对比度、 显示比例因子等。 执行此操作的方式是命名资源的文件夹或文件，以匹配与这些上下文对应的限定符名称和限定符值。 例如，你可能希望应用在高对比度模式下加载一组不同的图像资产。
有关本地化应用的价值主张的详细信息，请参阅 全球化和本地化。
限定符名称、限定符值和限定符
限定符名称是一种键，用于映射到一组限定符值。 下面是用于对比度的限定符名称和限定符值。
| 上下文 | 限定符名称 | 限定符值 |
|---|---|---|
| 高对比度设置 | 反差 | 标准，高，黑色，白色 |
将限定符名称与限定符值组合在一起，形成限定符。
<qualifier name>-<qualifier value> 是限定符的格式。
contrast-standard 是限定符的示例。
因此，对于高对比度，限定符集是contrast-standard，contrast-highcontrast-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 文件夹中的资源文件。 如果设置为 None（即计算机不处于高对比度模式），则加载文件夹中的资源文件 \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 限定符。 不要将 msft- 前缀用于自定义的 alternateform 限定符值。
配置
你不太可能会需要 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 字符串。
DX功能级别
你不太可能会需要 dxfeaturelevel 限定符名称。 它的设计初衷是与 Direct3D 游戏资产配合使用，以便加载与当时特定的下层硬件配置相匹配的下层资源。 但是，该硬件配置的普及率现在非常低，因此我们建议不要使用此限定符。
主要区域
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限定符对应于显示语言设置的布局方向。 例如，对于以右到左书写的语言（如阿拉伯语或希伯来语），可能需要对图像进行镜像处理。 如果你设置了它们的FlowDirection属性，UI 中的布局面板和图像将会相应地响应流向（请参阅调整布局和字体，并支持 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限定符主要用于指定要在文件资源管理器中显示的文件类型关联图标或协议图标。 限定符值表示原始（物理）像素中正方形图像的侧长度。 在文件资源管理器中加载与“视图”设置的值相匹配的资源；如果没有完全匹配，则加载具有最接近且较大值的资源。
可以在应用包清单设计器的“视觉资产”选项卡中定义表示应用图标（/Assets/Square44x44Logo.png）的targetsize多个大小的限定符值的资产。
有关使 scale 和 targetsize符合资格的资源的信息，请参阅 使图像资源符合目标尺寸的要求。
主题
theme 限定符用于提供与默认应用模式设置最匹配的资源，或者当应用程序重写设置为 Application.RequestedTheme时提供的资源。
Shell 浅色主题和未着色的资源
Windows 10 2019 年 5 月更新为 Windows Shell 引入了新的“浅色”主题。 因此，以前在深色背景上显示的某些应用程序资产现在将显示在浅色背景上。 对于为任务栏和窗口切换器（如 Alt+Tab、任务视图等）提供 altform-unplated 资产的应用程序，应验证它们在浅色背景上是否具有可接受的对比度。
提供与浅色主题相关的特定资源
为 Shell 浅色主题提供定制资源的应用程序可以使用新的替代形式资源限定符：altform-lightunplated。 此限定符镜像现有的 altform-unplated 限定符。
下层注意事项
应用不应将 theme-light 限定符与 altform-unplated 限定符一起使用。 由于任务栏的资源加载方式，这将在 RS5 和更早版本的 Windows 上导致不可预知的行为。 在早期版本的 Windows 上，主题灯版本可能不正确使用。
altform-lightunplated限定符可避免此问题。
兼容性行为
为了向后兼容，Windows 包括检测单色图标的逻辑，并检查它是否与预期背景形成对比。 如果图标无法满足对比度要求，Windows 将查找资产的对比度白色版本。 如果这不可用，Windows 将回退到使用资产的印版版本。