通过

定制语言、比例、高对比度和其他限定符的资源

  • 项目

本主题介绍了资源限定符的常规概念、如何使用它们以及每个限定符名称的用途。 有关所有可能的限定符值的引用表，请参阅 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

名称包含最适合设置的限定符的文件是加载的文件。 此匹配逻辑与文件夹名称的文件名的工作方式相同。

按名称引用字符串或图像资源

有关如何按名称引用字符串或图像资源的详细信息，请参阅以下主题：

实际和中性限定符匹配

无需为每个限定符值提供资源文件。 例如，如果你发现只有一个视觉资产用于高对比度，一个用于标准对比度，则可以命名这些资产，如下所示。

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

第一个文件名包含 contrast-high 限定符。 当高对比度处于打开时，该限定符是任何高对比度设置的实际匹配项。 换句话说，这是一个密切的匹配，所以它是首选。 仅当限定符包含实际值时，才会发生实际匹配，就像此值一样。 在本例中， high 是 实际 值 contrast。

命名 logo.png 的文件根本没有对比度限定符。 缺少限定符是一个 中性 值。 如果找不到首选匹配项，则中性值将用作回退匹配。 在此示例中，如果高对比度 处于关闭状态，则不存在实际匹配项。 中 性 匹配是可以找到的最佳匹配项，因此加载资产 logo.png 。

如果要更改其logo.contrast-standard.png名称logo.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>

有关限定符匹配的工作原理的详细信息，请参阅 使用 MRT Core 管理资源。

多个限定符

可以在文件夹和文件名中合并限定符。 例如，你可能希望应用在高对比度模式处于打开状态并且显示比例系数为 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 furigana 字符串（请参阅“如何准备本地化”中的“支持日语字符串的 Furigana”部分）。

目标系统或应用必须提供匹配的限定符的值 alternateform 。 不要将 msft- 前缀用于自己的自定义 alternateform 限定符值。

配置

你不太可能需要 configuration 限定符名称。 它可用于指定仅适用于给定创作时环境的资源，例如仅测试资源。

configuration限定符用于加载最符合环境变量值MS_CONFIGURATION_ATTRIBUTE_VALUE的资源。 因此，可以将变量设置为已分配给相关资源的字符串值，例如 designer，或 test。

对比度

contrast限定符用于提供最匹配高对比度设置的资源。

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 中的布局面板和图像将相应地响应布局方向（请参阅“调整布局和字体”，并支持 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

有关为这两scaletargetsize者限定资源的信息，请参阅限定目标化的图像资源。

TargetSize

targetsize限定符主要用于指定要在文件资源管理器中显示的文件类型关联图标或协议图标。 限定符值表示原始（物理）像素中正方形图像的侧长度。 加载其值与文件资源管理器中的“视图”设置匹配的资源;或者缺少完全匹配时具有下一个最大值的资源。

可以在应用包清单设计器的“视觉资产”选项卡中定义表示应用图标（/Assets/Square44x44Logo.png）的targetsize多个大小的限定符值的资产。

有关为这两scaletargetsize者限定资源的信息，请参阅限定目标化的图像资源。

主题

theme限定符用于提供与默认应用模式设置最匹配的资源，或使用 Application.RequestedTheme 替代应用。

Shell 浅色主题和未着色资源

Windows 10 2019 年 5 月更新为 Windows Shell 引入了一个新的“浅色”主题。 因此，以前显示在深色背景上的某些应用程序资产现在将显示在浅色背景上。 对于以前为任务栏和窗口切换器（Alt+Tab、任务视图等）提供 altform-unplated 资产的应用，应验证它们在浅色背景上是否具有可接受的对比度。

提供特定于浅色主题的资产

想要为 shell 浅色主题提供定制资源的应用可以使用新的备用窗体资源限定符：altform-lightunplated。 此限定符对应现有的 altform-unplated 限定符。

下层注意事项

应用不应将 theme-light 限定符与 altform-unplated 限定符一起使用。 由于为任务栏加载资源的方式，这将导致在 Windows RS5 和早期版本上出现不可预知的行为。 在 Windows 早期版本上，theme-light 版本可能使用不正确。 altform-lightunplated 限定符可避免这一问题。

兼容性行为

为了实现向后兼容，Windows 提供了检测单色图标并检查其是否与预期背景形成对比的逻辑。 如果图标不符合对比度要求，Windows 将查找资产的 contrast-white 版本。 如果没有，Windows 将回退到使用资产的着色版本。

重要的 API