定制语言、比例、高对比度和其他限定符的资源Tailor your resources for language, scale, high contrast, and other qualifiers

本主题介绍了资源限定符的常规概念、如何使用它们以及每个限定符名称的用途。This topic explains the general concept of resource qualifiers, how to use them, and the purpose of each of the qualifier names. 有关所有可能的限定符值的参考表,请参阅 ResourceContext.QualifierValuesSee ResourceContext.QualifierValues for a reference table of all the possible qualifier values.

你的应用可加载按运行时环境(例如显示语言、高对比度、显示比例系数以及许多其他项)定制的资产和资源。Your app can load assets and resources that are tailored to runtime contexts such as display language, high contrast, display scale factor, and many others. 执行此操作的方法是命名资源的文件夹或文件,以匹配与这些环境相对应的限定符名称和限定符值。The way you do this is to name your resources’ folders or files to match the qualifier names and qualifier values that correspond to those contexts. 例如,你可能想让应用在高对比度模式下加载另一组图像资产。For example, you may want your app to load a different set of image assets in high contrast mode.

有关对应用进行本地化的价值主张的详细信息,请参阅全球化和本地化For more info about the value proposition of localizing your app, see Globalization and localization.

限定符名称、限定符值和限定符Qualifier name, qualifier value, and qualifier

限定符名称是映射到一组限定符值的键。A qualifier name is a key that maps to a set of qualifier values. 下面是对比度的限定符名称和限定符值。Here are the qualifier name and qualifier values for contrast.

上下文Context 限定符名称Qualifier name 限定符值Qualifier values
高对比度设置The high contrast setting contrastcontrast standard、high、black、whitestandard, high, black, white

你可以将限定符名称和限定符值结合起来形成限定符。You combine a qualifier name with a qualifier value to form a qualifier. <qualifier name>-<qualifier value> 限定符的格式。<qualifier name>-<qualifier value> is the format of a qualifier. contrast-standard 是一个限定符的示例。contrast-standard is an example of a qualifier.

因此,对于高对比度,限定符集是 contrast-standardcontrast-highcontrast-blackcontrast-whiteSo, for high contrast, the set of qualifiers is contrast-standard, contrast-high, contrast-black, and contrast-white. 限定符名称和限定符值不区分大小写。Qualifier names and qualifier values are not case sensitive. 例如,contrast-standardContrast-Standard 是相同的限定符。For example, contrast-standard and Contrast-Standard are the same qualifier.

在文件夹名称中使用限定符Use qualifiers in folder names

下面是一个使用限定符命名包含资产文件的文件夹的示例。Here is an example of using qualifiers to name folders that contain asset files. 如果每个限定符都有一些资产文件,请在文件夹名称中使用限定符。Use qualifiers in folder names if you have several asset files per qualifier. 这样,你可以在文件夹级别设置一次限定符,限定符便可应用于文件夹内的所有内容。That way, you set the qualifier once at the folder level, and the qualifier applies to everything inside the folder.

\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>

如果你按照上述示例命名文件夹,那么你的应用会使用高对比度设置从针对适当限定符命名的文件夹中加载资源文件。If you name your folders as in the example above, then your app uses the high contrast setting to load resource files from the folder named for the appropriate qualifier. 因此,如果该设置为“高对比度黑色”,则会加载 \Assets\Images\contrast-black 文件夹中的资源文件。So, if the setting is High Contrast Black, then the resource files in the \Assets\Images\contrast-black folder are loaded. 如果该设置为“无”(即,计算机未处于高对比度模式),则会加载 \Assets\Images\contrast-standard 文件夹中的资源文件。If the setting is None (that is, the computer is not in high contrast mode), then the resource files in the \Assets\Images\contrast-standard folder are loaded.

在文件名称中使用限定符Use qualifiers in file names

你可以使用限定符来命名资源文件本身,而不是创建和命名文件夹。Instead of creating and naming folders, you can use a qualifier to name the resource files themselves. 如果每个限定符只有一个资源文件,你可能更喜欢执行此操作。You might prefer to do this if you only have one resource file per qualifier. 此处为一个示例。Here’s an example.

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

加载的文件是名称中包含最适合该设置的限定符的文件。The file whose name contains the qualifier most appropriate for the setting is the one that is loaded. 此匹配逻辑的工作原理对文件名和文件夹名称都相同。This matching logic works the same way for file names as for folder names.

按名称引用字符串或图像资源Reference a string or image resource by name

请参阅引用 XAML 标记中的字符串资源标识符引用代码中的字符串资源标识符以及引用 XAML 标记和代码中的图像或其他资产See Refer to a string resource identifier from XAML markup, Refer to a string resource identifier from code, and Reference an image or other asset from XAML markup and code.

实际与中性限定符匹配项Actual and neutral qualifier matches

你无需为每个限定符值都提供资源文件。You don’t need to provide a resource file for every qualifier value. 例如,如果你发现高对比度和标准对比度都只需要一个视觉资产,则可以按如下所示命名这些资产。For example, if you find that you only need one visual asset for high contrast and one for standard contrast, then you can name those assets like this.

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

第一个文件名包含 contrast-high 限定符。The first file name contains the contrast-high qualifier. 当高对比度处于打开状态时,该限定符是任何高对比度设置的实际匹配项。That qualifier is an actual match for any high contrast setting when high contrast is on. 换言之,它是一个接近的匹配项,因此是首选。In other words, it's a close match so it’s preferred. 仅当限定符包含实际值时,才存在实际匹配项,就像上述示例中一样。An actual match can only occur if the qualifier contains an actual value, as this one does. 在该示例中,highcontrast实际值。In this case, high is an actual value for contrast.

名为 logo.png 的文件自身根本没有对比度限定符。The file named logo.png has no contrast qualifier on it at all. 限定符缺少一个中性值。The absence of a qualifier is a neutral value. 如果找不到首选匹配项,则中性值可用作回退匹配项。If no preferred match can be found, then the neutral value serves as a fallback match. 在此示例中,如果高对比度处于关闭状态,则没有实际匹配项。In this example, if high contrast is off, then there is no actual match. 中性匹配项是可以找到的最佳匹配项,因此会加载资产 logo.pngThe neutral match is the best match that can be found, and so the asset logo.png is loaded.

如果你要将 logo.png 的名称更改为 logo.contrast-standard.png,则文件名将包含实际限定符值。If you were to change the name of logo.png to logo.contrast-standard.png, then the file name would contain an actual qualifier value. 关闭高对比度后,将存在 logo.contrast-standard.png 的实际匹配项,这是将加载的资产文件。With high contrast off, there would be an actual match with logo.contrast-standard.png, and that’s the asset file that would be loaded. 因此,将在相同条件下加载相同文件,但却是因为不同的匹配项而加载。So, the same files would be loaded, under the same conditions, but because of different matches.

如果只需要一组资产用于高对比度,一组资产用于标准对比度,则可以使用文件夹名称而不是文件名。If you only need one set of assets for high contrast and one set for standard contrast, then you can use folder names instead of file names. 在此情况下,彻底忽略文件夹名称可为你提供中性匹配项。In this case, omitting the folder name entirely gives you the neutral match.

\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>

有关限定符匹配的工作原理的更多详细信息,请参阅资源管理系统For more details on how qualifier matching works, see Resource Management System.

多个限定符Multiple qualifiers

你可以在文件夹名称和文件名中合并限定符。You can combine qualifiers in folder and file names. 例如,你可能希望应用在高对比度模式处于打开状态并且显示比例系数为 400 时加载图像资产。For example, you may want your app to load image assets when high contrast mode is on and the display scale factor is 400. 执行此操作的一种方法是使用嵌套文件夹。One way to do this is with nested folders.

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

对于 logo.png 以及要加载的其他文件,设置必须与两个限定符都匹配。For logo.png and the other files to be loaded, the settings must match both qualifiers.

另一个选项是在一个文件夹名称中合并多个限定符。Another option is to combine multiple qualifiers in one folder name.

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

在文件夹名称中,你可以合并用下划线分隔的多个限定符。In a folder name, you combine multiple qualifiers separated with an underscore. <qualifier1>[_<qualifier2>...] 格式为。<qualifier1>[_<qualifier2>...] is the format.

你可以用相同格式在文件名中合并多个限定符。You can combine multiple qualifiers in a file name in the same format.

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

根据用于创建资产的工具和工作流,或者根据你所发现的最容易阅读和/或管理的内容,你可以为所有限定符选择单个命名策略,也可以针对不同限定符合并它们。Depending on the tools and workflow you use for asset-creation, or on what you find easiest to read and/or manage, you can either choose a single naming strategy for all qualifiers, or you can combine them for different qualifiers.

AlternateFormAlternateForm

alternateform 限定符用于为某些特殊用途提供资源的替代形式。The alternateform qualifier is used to provide an alternate form of a resource for some special purpose. 这通常仅供日语应用开发人员使用,用于提供保留 msft-phonetic 值所针对的假名注音字符串(请参阅如何为本地化做好准备中的“支持可存储的日语字符串的假名注音”部分。This is typically used only by Japanese app developers to provide a furigana string for which the value msft-phonetic is reserved (see the section “Support Furigana for Japanese strings that can be sorted” in How to prepare for localization).

你的目标系统或应用必须提供匹配 alternateform 限定符所依据的值。Either your target system or your app must provide a value against which alternateform qualifiers are matched. 请不要将 msft- 前缀用于自己的自定义 alternateform 限定符值。Do not use the msft- prefix for your own custom alternateform qualifier values.

配置Configuration

需要 configuration 限定符名称的可能性较低。It’s unlikely that you’ll need the configuration qualifier name. 它可用于指定仅适用于给定的创作时环境的资源,例如仅用于测试的资源。It can be used to specify resources that are applicable only to a given authoring-time environment, such as test-only resources.

configuration 限定符用于加载与 MS_CONFIGURATION_ATTRIBUTE_VALUE 环境变量的值最佳匹配的资源。The configuration qualifier is used to load a resource that best matches the value of the MS_CONFIGURATION_ATTRIBUTE_VALUE environment variable. 因此,你可以将变量设置为已分配给相关资源的字符串值,例如 designertestSo, you can set the variable to the string value that has been assigned to the relevant resources, for example designer, or test.

与此示例Contrast

contrast 限定符用于提供与高对比度设置最佳匹配的资源。The contrast qualifier is used to provide resources that best match high contrast settings.

自定义Custom

你的应用可以为 custom 限定符设置值,以后系统会加载与该值最佳匹配的资源。Your app can set a value for the custom qualifier, and then resources are loaded that best match that value. 例如,你可能希望根据你的应用许可证来加载资源。For example, you may want to load resources based on your app’s license. 当你的应用启动时,它会检查其许可证,并将其用作 custom 限定符的值,所采用的方法是调用 SetGlobalQualifierValue,如代码示例中所示。When your app launches, it checks its license and uses that as the value for the custom qualifier by calling SetGlobalQualifierValue, as shown in the code example.

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-premiumcustom-standardcustom-trial 限定符的名称。In this scenario, you would then give your resources names that include the qualifiers custom-premium, custom-standard, and custom-trial.

DeviceFamilyDeviceFamily

需要 devicefamily 限定符名称的可能性较低。It’s unlikely that you’ll need the devicefamily qualifier name. 你可以并且应该尽可能避免使用它,因为可以改用更加方便和可靠的方法。You can and should avoid using it whenever possible because there are techniques that you can use instead that are much more convenient and robust. 检测正运行应用的平台版本自适应代码中介绍了这些方法。Those techniques are described in Detecting the platform your app is running on and Version adaptive code.

但是,万不得已时,可以使用 devicefamily 限定符来命名包含 XAML 视图的文件夹(XAML 视图是包含 UI 布局和控件的 XAML 文件)。But as a last resort it is possible to use devicefamily qualifiers to name folders that contain your XAML views (a XAML view is a XAML file that contains UI layout and controls).

\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>

或者,你可以命名文件。Or you can name files.

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

在任一情况下,MainPage.[<qualifier>].xaml 的每个副本都共享一个在你的项目中名称、位置和内容保持不变的通用 MainPage.xaml.csIn either case each copy of MainPage.[<qualifier>].xaml shares a common MainPage.xaml.cs, which remains unchanged in your project in terms of name, location, and contents.

你还可以使用 devicefamily 限定符命名资源文件 (.resw) 或文件夹。You can also use a devicefamily qualifier to name a Resources File (.resw), or folder. 例如,当你的应用在移动设备系列上运行时,UI 元素 <TextBlock x:Uid="DeviceFriendlyName"/> 将使用 Resources.devicefamily-mobile.resw 文件中定义的文本和前台资源,条件是该文件包含以下内容For example, when your app is running on the mobile device family, the UI element <TextBlock x:Uid="DeviceFriendlyName"/> will use the text and foreground resources defined in your Resources.devicefamily-mobile.resw file if it contains

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

有关使用资源文件的详细信息,请参阅本地化你的 UI 字符串For more on using a Resources File, see Localize your UI strings.

DXFeatureLevelDXFeatureLevel

需要 dxfeaturelevel 限定符名称的可能性较低。It’s unlikely that you’ll need the dxfeaturelevel qualifier name. 它旨在与 Direct3D 游戏资产配合使用,以导致加载下层资源,从而与当时的特定下层硬件配置匹配。It was designed to be used with Direct3D game assets, to cause downlevel resources to be loaded to match a particular downlevel hardware configuration of the time. 但是,该硬件配置的普及程度现在非常低,因此我们建议你不要使用此限定符。But the prevalence of that hardware configuration is now so low that we recommend you don’t use this qualifier.

HomeRegionHomeRegion

homeregion 限定符对应于用户的国家或地区设置。The homeregion qualifier corresponds to the user’s setting for country or region. 它表示用户的主位置。It represents the home location of the user. 值包括任何有效的 BCP-47 区域标记Values include any valid BCP-47 region tag. 即,任何 ISO 3166 1 alpha-2 双字母区域代码,以及所构成区域的一组 ISO 3166-1 数字三位数地理代码(请参阅联合国统计部门 M49 区域代码构成)。That is, any ISO 3166-1 alpha-2 two-letter region code, plus the set of ISO 3166-1 numeric three-digit geographic codes for composed regions (see United Nations Statistic Division M49 composition of region codes). “选定的经济组织和其他组织”的代码无效。Codes for "Selected economic and other groupings" are not valid.

语言Language

language 限定符对应于显示语言设置。A language qualifier corresponds to the display language setting. 值包括任何有效的 BCP-47 语言标记Values include any valid BCP-47 language tag. 有关语言的列表,请参阅 IANA 语言子标记注册表For a list of languages, see the IANA language subtag registry.

如果你希望应用支持其他显示语言,并且你的代码或 XAML 标记中有字符串文本,则从代码/标记内将这些字符串移到资源文件 (.resw) 中。If you want your app to support different display languages, and you have string literals in your code or in your XAML markup, then move those strings out of the code/markup and into a Resources File (.resw). 然后,你可以针对应用支持的每种语言制作该资源文件的翻译副本。You can then make a translated copy of that Resources File for each language that your app supports.

你通常使用 language 限定符来命名包含资源文件 (.resw) 的文件夹。You typically use a language qualifier to name the folders that contain your Resources Files (.resw).

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

你可以忽略 language 限定符的 language- 部分(即,限定符名称)。You can omit the language- part of a language qualifier (that is, the qualifier name). 你不能对其他类型的限定符执行此操作;只能在文件夹名称中进行此操作。You can’t do this with the other kinds of qualifiers; and you can only do it in a folder name.

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

你可以使用 language 限定符来命名资源文件本身,而不是命名文件夹。Instead of naming folders, you can use language qualifiers to name the Resources Files themselves.

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

有关使用字符串资源使你的应用可本地化,以及如何在应用中引用字符串资源的详细信息,请参阅本地化你的 UI 字符串See Localize your UI strings for more information on making your app localizable by using string resources, and how to reference a string resource in your app.

LayoutDirectionLayoutDirection

layoutdirection 限定符对应于显示语言设置的布局方向。A layoutdirection qualifier corresponds to the layout direction of the display language setting. 例如,像阿拉伯语或希伯来语这样从右到左阅读的语言,可能需要镜像图像。For example, an image may need to be mirrored for a right-to-left language such as Arabic or Hebrew. 如果设置了 FlowDirection 属性,则 UI 中的布局面板和图像将相应地响应布局方向(请参阅调整布局和字体并支持 RTL)。Layout panels and images in your UI will respond to layout direction appropriately if you set their FlowDirection property (see Adjust layout and fonts, and support RTL). 但是,layoutdirection 限定符适用于简单翻转无法满足要求的情况,可以采用更常规的方式响应特定阅读顺序和文本对齐的方向性。However, the layoutdirection qualifier is for cases where simple flipping isn't adequate, and it allows you to respond to the directionality of specific reading order and text alignment in more general ways.

缩放Scale

Windows 会根据其 DPI(每英寸点数)和设备的观看距离自动为每个显示器选择一个缩放比例。Windows automatically selects a scale factor for each display based on its DPI (dots-per-inch) and the viewing distance of the device. 请参阅有效像素和缩放比例See Effective pixels and scale factor. 你应该创建多个建议大小(至少包括 100、200 和 400)的图像,使 Windows 可以选择理想的大小或使用最近大小并进行缩放。You should create your images at several recommended sizes (at least 100, 200, and 400) so that Windows can either choose the perfect size or can use the nearest size and scale it. 这样一来,Windows 可以识别哪个物理文件包含适合显示比例系数的正确大小的图像,你使用 scale 限定符。So that Windows can identify which physical file contains the correct size of image for the display scale factor, you use a scale qualifier. 资源的比例与 DisplayInformation.ResolutionScale 或下一个最大比例资源的值匹配。The scale of a resource matches the value of DisplayInformation.ResolutionScale, or the next-largest-scaled resource.

下面是在文件夹级别设置限定符的示例。Here’s an example of setting the qualifier at the folder level.

\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>

此示例在文件级别对其进行设置。And this example sets it at the file level.

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

有关限定资源的 scaletargetsize 的信息,请参阅限定图像资源的目标大小For info about qualifying a resource for both scale and targetsize, see Qualify an image resource for targetsize.

TargetSizeTargetSize

targetsize 限定符主要用于指定要在文件资源管理器中显示的文件类型关联图标协议图标The targetsize qualifier is primarily used to specify file type association icons or protocol icons to be shown in File Explorer. 限定符值表示以原始(物理)像素为单位的正方形图像的边长。The qualifier value represents the side length of a square image in raw (physical) pixels. 系统会加载其值与文件资源管理器中的“视图”设置匹配的资源;或者在缺少完全匹配的情况下加载具有下一个最大值的资源。The resource whose value matches the View setting in File Explorer is loaded; or the resource with the next-largest value in the absence of an exact match.

你可以在应用程序包清单设计器的“可见资产”选项卡中定义资产,以表示应用图标 (/Assets/Square44x44Logo.png) 的 targetsize 限定符值的一些大小。You can define assets that represent several sizes of targetsize qualifier value for the App Icon (/Assets/Square44x44Logo.png) in the Visual Assets tab of the app package manifest designer.

有关限定资源的 scaletargetsize 的信息,请参阅限定图像资源的目标大小For info about qualifying a resource for both scale and targetsize, see Qualify an image resource for targetsize.

主题Theme

theme 限定符用于提供与默认应用模式设置最匹配的资源,或使用 Application.RequestedTheme 的应用替代。The theme qualifier is used to provide resources that best match the default app mode setting, or your app’s override using Application.RequestedTheme.

Shell light 主题和未着色资源Shell light theme and unplated resources

Windows 10 5 月2019版更新为 windows Shell 引入了新的 "轻型" 主题。The Windows 10 May 2019 Update introduced a new "light" theme for the Windows Shell. 因此,以前在深色背景上显示的某些应用程序资产现在会显示在浅色背景上。As a result, some application assets that were previously shown on a dark background will now be shown on a light background. 对于为任务栏和窗口切换器提供了 altform-未着色资产的应用的应用 (Alt + Tab、任务视图等) ,你应验证它们在浅色背景上是否可接受对比度。For apps that apps that provided altform-unplated assets for the taskbar and window switchers (Alt+Tab, Task View, etc), you should verify that they have acceptable contrast on a light background.

提供轻度主题特定资产Providing light theme specific assets

需要为 shell 轻型主题提供定制资源的应用可以使用新的替代形式资源限定符: altform-lightunplatedApps that want to provide a tailored resource for shell light theme can use a new alternate form resource qualifier: altform-lightunplated. 此限定符镜像现有的 altform-未着色限定符。This qualifier mirrors the existing altform-unplated qualifier.

下层注意事项Downlevel considerations

应用不应将 theme-light 限定符与限定符一起使用 altform-unplatedApps should not use the theme-light qualifier with the altform-unplated qualifier. 这将导致 RS5 和早期版本的 Windows 上出现不可预测的行为,原因是为任务栏加载资源的方式。This will cause unpredictable behavior on RS5 and earlier versions of Windows due to the way resources are loaded for the Taskbar. 在较早版本的 windows 上,可能会错误地使用主题浅版本。On earlier versions of windows, the theme-light version may be used incorrectly. altform-lightunplated限定符可避免此问题。The altform-lightunplated qualifier avoids this issue.

兼容性行为Compatibility behavior

为了向后兼容,Windows 包含了用于检测单色图标的逻辑,并检查它是否与预期的背景进行了对比。For backwards compatibility, Windows includes logic to detect a monochromatic icons and check whether it contrasts with the intended background. 如果图标无法满足对比度要求,则 Windows 将查找资产的 "对比度-白色" 版本。If the icon fails to meet contrast requirements, Windows will look for a contrast-white version of the asset. 如果不可用,则 Windows 将回退到使用 plated 版本的资产。If that’s not available, Windows will fall back to using the plated version of the asset.

重要的 APIImportant APIs