XAML 主题资源XAML theme resources

XAML 中的主题资源是一组可应用不同值的资源,具体取决于哪个系统主题处于活动状态。Theme resources in XAML are a set of resources that apply different values depending on which system theme is active. XAML 框架支持三种主题:“浅色”、“深色”和“高对比度”。There are 3 themes that the XAML framework supports: "Light", "Dark", and "HighContrast".

先决条件:本主题假设你已阅读 ResourceDictionary 和 XAML 资源引用Prerequisites: This topic assumes that you have read ResourceDictionary and XAML resource references.

主题资源与Theme resources v. 静态资源static resources

有两个 XAML 标记扩展,可从现有 XAML 资源字典引用 XAML 资源:{StaticResource} 标记扩展{ThemeResource} 标记扩展There are two XAML markup extensions that can reference a XAML resource from an existing XAML resource dictionary: {StaticResource} markup extension and {ThemeResource} markup extension.

将在应用加载时和随后每次在运行时更改主题时,发生 {ThemeResource} 标记扩展评估。Evaluation of a {ThemeResource} markup extension occurs when the app loads and subsequently each time the theme changes at runtime. 这通常是用户更改其设备设置或从更改其当前主题的应用内进行编程更改所引起的。This is typically the result of the user changing their device settings or from a programmatic change within the app that alters its current theme.

相比之下,仅在应用首次加载 XAML 时评估 {StaticResource} 标记扩展In contrast, a {StaticResource} markup extension is evaluated only when the XAML is first loaded by the app. 它未更新。It does not update. 这类似于在应用启动时使用实际运行时值在 XAML 中进行查找和替换。It’s similar to a find and replace in your XAML with the actual runtime value at app launch.

资源字典结构中的主题资源Theme resources in the resource dictionary structure

每个主题资源都是 XAML 文件 themeresources.xaml 的一部分。Each theme resource is part of the XAML file themeresources.xaml. 出于设计目的,themeresources.xaml 在 Windows 软件开发工具包 (SDK) 安装中的 \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK 版本>\Generic 文件夹中提供。For design purposes, themeresources.xaml is available in the \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic folder from a Windows Software Development Kit (SDK) installation. themeresources.xaml 中的资源字典还在同一目录中的 generic.xaml 中重现。The resource dictionaries in themeresources.xaml are also reproduced in generic.xaml in the same directory.

Windows 运行时不使用这些物理文件进行运行时查找。The Windows Runtime doesn't use these physical files for runtime lookup. 这就是它们专门在 DesignTime 文件夹中,并且在默认情况下不复制到应用中的原因。That's why they are specifically in a DesignTime folder, and they aren't copied into apps by default. 这些资源字典在内存中作为 Windows 运行时本身的一部分存在,并且你的应用的对主题资源(或系统资源)的 XAML 资源引用将在运行时在该处进行解析。Instead, these resource dictionaries exist in memory as part of the Windows Runtime itself, and your app's XAML resource references to theme resources (or system resources) resolve there at runtime.

自定义主题资源指南Guidelines for custom theme resources

当定义和使用你自己的自定义主题资源时,请遵循这些指南:Follow these guidelines when you define and consume your own custom theme resources:

注意

如果不遵循这些指南,可能会出现与应用中的主题相关的意外行为。If you don’t follow these guidelines, you might see unexpected behavior related to themes in your app. 有关详细信息,请参阅主题资源疑难解答部分。For more info, see the Troubleshooting theme resources section.

XAML 颜色渐变和依赖于主题的画笔The XAML color ramp and theme-dependent brushes

由“浅色”、“深色”和“高对比度”主题组合的颜色集构成了 XAML 中的 Windows 颜色渐变The combined set of colors for "Light", "Dark", and "HighContrast" themes make up the Windows color ramp in XAML. 无论是想要修改系统主题,还是将系统主题应用到自己的 XAML 元素,了解如何构建颜色资源都非常重要。Whether you want to modify the system themes, or apply a system theme to your own XAML elements, it’s important to understand how the color resources are structured.

有关如何在 Windows 应用中应用颜色的更多信息,请参阅 Windows 应用中的颜色For additional information about how to apply color in your Windows app, please see Color in Windows apps.

浅色和深色主题颜色Light and Dark theme colors

XAML 框架提供了一个已命名的 Color 资源集,其中包含的值专为“浅色”和“深色”主题而定制。The XAML framework provides a set of named Color resources with values that are tailored for the "Light" and "Dark" themes. 用于引用这些内容的键遵循以下命名格式:System[Simple Light/Dark Name]ColorThe keys you use to reference these follow the naming format: System[Simple Light/Dark Name]Color.

针对 XAML 框架提供的“浅色”和“深色”资源,此表列出了该颜色的键、简单名称和字符串表示形式(使用 #aarrggbb 格式)。This table lists the key, simple name, and string representation of the color (using the #aarrggbb format) for the "Light" and "Dark" resources provided by the XAML framework. 该键用于引用应用中的资源。The key is used to reference the resource in an app. 将“简单浅色/深色名称”用作我们后面介绍的画笔命名约定的一部分。The "Simple light/dark name" is used as part of the brush naming convention that we explain later.

Key 简单浅色/深色名称Simple light/dark name 轻型Light 深色Dark
SystemAltHighColorSystemAltHighColor AltHighAltHigh #FFFFFFFF#FFFFFFFF #FF000000#FF000000
SystemAltLowColorSystemAltLowColor AltLowAltLow #33FFFFFF#33FFFFFF #33000000#33000000
SystemAltMediumColorSystemAltMediumColor AltMediumAltMedium #99FFFFFF#99FFFFFF #99000000#99000000
SystemAltMediumHighColorSystemAltMediumHighColor AltMediumHighAltMediumHigh #CCFFFFFF#CCFFFFFF #CC000000#CC000000
SystemAltMediumLowColorSystemAltMediumLowColor AltMediumLowAltMediumLow #66FFFFFF#66FFFFFF #66000000#66000000
SystemBaseHighColorSystemBaseHighColor BaseHighBaseHigh #FF000000#FF000000 #FFFFFFFF#FFFFFFFF
SystemBaseLowColorSystemBaseLowColor BaseLowBaseLow #33000000#33000000 #33FFFFFF#33FFFFFF
SystemBaseMediumColorSystemBaseMediumColor BaseMediumBaseMedium #99000000#99000000 #99FFFFFF#99FFFFFF
SystemBaseMediumHighColorSystemBaseMediumHighColor BaseMediumHighBaseMediumHigh #CC000000#CC000000 #CCFFFFFF#CCFFFFFF
SystemBaseMediumLowColorSystemBaseMediumLowColor BaseMediumLowBaseMediumLow #66000000#66000000 #66FFFFFF#66FFFFFF
SystemChromeAltLowColorSystemChromeAltLowColor ChromeAltLowChromeAltLow #FF171717#FF171717 #FFF2F2F2#FFF2F2F2
SystemChromeBlackHighColorSystemChromeBlackHighColor ChromeBlackHighChromeBlackHigh #FF000000#FF000000 #FF000000#FF000000
SystemChromeBlackLowColorSystemChromeBlackLowColor ChromeBlackLowChromeBlackLow #33000000#33000000 #33000000#33000000
SystemChromeBlackMediumLowColorSystemChromeBlackMediumLowColor ChromeBlackMediumLowChromeBlackMediumLow #66000000#66000000 #66000000#66000000
SystemChromeBlackMediumColorSystemChromeBlackMediumColor ChromeBlackMediumChromeBlackMedium #CC000000#CC000000 #CC000000#CC000000
SystemChromeDisabledHighColorSystemChromeDisabledHighColor ChromeDisabledHighChromeDisabledHigh #FFCCCCCC#FFCCCCCC #FF333333#FF333333
SystemChromeDisabledLowColorSystemChromeDisabledLowColor ChromeDisabledLowChromeDisabledLow #FF7A7A7A#FF7A7A7A #FF858585#FF858585
SystemChromeHighColorSystemChromeHighColor ChromeHighChromeHigh #FFCCCCCC#FFCCCCCC #FF767676#FF767676
SystemChromeLowColorSystemChromeLowColor ChromeLowChromeLow #FFF2F2F2#FFF2F2F2 #FF171717#FF171717
SystemChromeMediumColorSystemChromeMediumColor ChromeMediumChromeMedium #FFE6E6E6#FFE6E6E6 #FF1F1F1F#FF1F1F1F
SystemChromeMediumLowColorSystemChromeMediumLowColor ChromeMediumLowChromeMediumLow #FFF2F2F2#FFF2F2F2 #FF2B2B2B#FF2B2B2B
SystemChromeWhiteColorSystemChromeWhiteColor ChromeWhiteChromeWhite #FFFFFFFF#FFFFFFFF #FFFFFFFF#FFFFFFFF
SystemListLowColorSystemListLowColor ListLowListLow #19000000#19000000 #19FFFFFF#19FFFFFF
SystemListMediumColorSystemListMediumColor ListMediumListMedium #33000000#33000000 #33FFFFFF#33FFFFFF

浅色主题Light theme

深色主题Dark theme

基本Base

基本浅色主题

基本深色主题

AltAlt

备用浅色主题

备用深色主题

列表List

列表浅色主题

列表深色主题

镶边Chrome

镶边浅色主题

镶边深色主题

Windows 系统高对比度颜色Windows system high-contrast colors

除了 XAML 框架提供的资源集,还存在派生自 Windows 系统调色板的颜色值集。In addition to the set of resources provided by the XAML framework, there's a set of color values derived from the Windows system palette. 这些颜色并不特定于 Windows 运行时或 Windows 应用。These colors are not specific to the Windows Runtime or Windows apps. 然而,当使用“高度对比”主题运行系统(并且应用正在运行)时,许多 XAML Brush 资源都将使用这些颜色。However, many of the XAML Brush resources consume these colors when the system is operating (and the app is running) using the "HighContrast" theme. XAML 框架提供这些系统范围的颜色作为键控资源。The XAML framework provides these system-wide colors as keyed resources. 这些键遵循以下命名格式:SystemColor[name]ColorThe keys follow the naming format: SystemColor[name]Color.

此表列出了 XAML 提供的系统范围的颜色,可作为派生自 Windows 系统调色板的资源对象。This table lists the system-wide colors that XAML provides as resource objects derived from the Windows system palette. “轻松使用名称”列显示了如何在 Windows 设置 UI 中向颜色添加标签。The "Ease of Access name" column shows how color is labeled in the Windows settings UI. “简单的高对比度名称”列中使用一个词描述如何在 XAML 常用控件中应用该颜色。The "Simple HighContrast name" column is a one word description of how the color is applied across the XAML common controls. 它将用作我们后面介绍的画笔命名约定的一部分。It's used as part of the brush naming convention that we explain later. 如果系统未以高对比度运行,则“初始默认设置”列会显示你已得到的值。The "Initial default" column shows the values you'd get if the system is not running in high contrast at all.

Key 轻松使用名称Ease of Access name 简单的高对比度名称Simple HighContrast name 初始默认设置Initial default
SystemColorButtonFaceColorSystemColorButtonFaceColor 按钮文本(背景)Button Text (background) 背景Background #FFF0F0F0#FFF0F0F0
SystemColorButtonTextColorSystemColorButtonTextColor 按钮文本(前景)Button Text (foreground) ForegroundForeground #FF000000#FF000000
SystemColorGrayTextColorSystemColorGrayTextColor 禁用的文本Disabled Text 禁用Disabled #FF6D6D6D#FF6D6D6D
SystemColorHighlightColorSystemColorHighlightColor 选定文本(背景)Selected Text (background) 突出显示Highlight #FF3399FF#FF3399FF
SystemColorHighlightTextColorSystemColorHighlightTextColor 选定文本(前景)Selected Text (foreground) HighlightAltHighlightAlt #FFFFFFFF#FFFFFFFF
SystemColorHotlightColorSystemColorHotlightColor 超链接Hyperlinks HyperlinkHyperlink #FF0066CC#FF0066CC
SystemColorWindowColorSystemColorWindowColor 背景Background PageBackgroundPageBackground #FFFFFFFF#FFFFFFFF
SystemColorWindowTextColorSystemColorWindowTextColor 文本Text PageTextPageText #FF000000#FF000000

通过“轻松使用设置中心”,Windows 提供不同的高对比度主题,并且支持用户设置特定颜色以用于其高对比度设置,如此处所示。Windows provides different high-contrast themes, and enables the user to set the specific colors to for their high-contrast settings through the Ease of Access Center, as shown here. 因此,无法提供一个明确的高对比颜色值列表。Therefore, it's not possible to provide a definitive list of high-contrast color values.

Windows 高对比度设置 UI

有关支持高对比度主题的详细信息,请参阅高对比度主题For more info about supporting high-contrast themes, see High-contrast themes.

系统主题色System accent color

除了系统高对比度主题颜色外,通过使用键 SystemAccentColor,系统主题色还会作为特定的颜色资源提供。In addition to the system high-contrast theme colors, the system accent color is provided as a special color resource using the key SystemAccentColor. 在运行时,该资源获取用户已在 Windows 个性化设置中指定为主题色的颜色。At runtime, this resource gets the color that the user has specified as the accent color in the Windows personalization settings.

备注

虽然可能会覆盖系统颜色资源,但这是遵循用户的颜色选择(特别是对于高对比度设置而言)的最佳做法。While it’s possible to override the system color resources, it’s a best practice to respect the user’s color choices, especially for high-contrast settings.

依赖于主题的画笔Theme-dependent brushes

使用前面部分中所示的颜色资源来设置系统主题资源字典中的 SolidColorBrush 资源的 Color 属性。The color resources shown in the preceding sections are used to set the Color property of SolidColorBrush resources in the system theme resource dictionaries. 你可以使用画笔资源将颜色应用到 XAML 元素中。You use the brush resources to apply the color to XAML elements. 画笔资源的键遵循以下命名格式:SystemControl[Simple HighContrast name][Simple light/dark name]BrushThe keys for the brush resources follow the naming format: SystemControl[Simple HighContrast name][Simple light/dark name]Brush. 例如,SystemControlBackgroundAltHighBrushFor example, SystemControlBackgroundAltHighBrush.

让我们看一下如何在运行时确定此画笔的颜色值。Let’s look at how the color value for this brush is determined at run-time. 在“浅色”和“深色”资源字典中,定义此画笔,如下所示:In the "Light" and "Dark" resource dictionaries, this brush is defined like this:

<SolidColorBrush x:Key="SystemControlBackgroundAltHighBrush" Color="{StaticResource SystemAltHighColor}"/>

在“高对比度”资源字典中,定义此画笔,如下所示:In the "HighContrast" resource dictionary, this brush is defined like this:

<SolidColorBrush x:Key="SystemControlBackgroundAltHighBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>

当将此画笔应用到 XAML 元素时,其颜色在运行时由当前主题决定,如此表中所示。When this brush is applied to a XAML element, its color is determined at run-time by the current theme, as shown in this table.

主题Theme 颜色简单名称Color simple name 颜色资源Color resource 运行时值Runtime value
轻型Light AltHighAltHigh SystemAltHighColorSystemAltHighColor #FFFFFFFF#FFFFFFFF
深色Dark AltHighAltHigh SystemAltHighColorSystemAltHighColor #FF000000#FF000000
高对比度HighContrast 背景Background SystemColorButtonFaceColorSystemColorButtonFaceColor 在设置中指定的按钮背景的颜色。The color specified in settings for the button background.

你可以使用 SystemControl[Simple HighContrast name][Simple light/dark name]Brush 命名方案确定要应用到你自己的 XAML 元素的画笔。You can use the SystemControl[Simple HighContrast name][Simple light/dark name]Brush naming scheme to determine which brush to apply to your own XAML elements.

备注

并非[简单的高对比度名称][简单的浅色/深色名称]的每个组合都作为画笔资源提供 。Not every combination of [Simple HighContrast name][Simple light/dark name] is provided as a brush resource.

XAML 类型渐变The XAML type ramp

themeresources.xaml 文件将定义若干个资源,这些资源定义可应用到 UI 中的文本容器(特别是 TextBlockRichTextBlock)的 StyleThe themeresources.xaml file defines several resources that define a Style that you can apply to text containers in your UI, specifically for either TextBlock or RichTextBlock. 它们不是默认的隐式样式。These are not the default implicit styles. 通过它们,你可以更轻松地创建匹配字体指南中记录的 Windows 类型渐变的 XAML UI 定义。They are provided to make it easier for you to create XAML UI definitions that match the Windows type ramp documented in Guidelines for fonts.

这些样式用于你要应用到整个文本容器的文本属性。These styles are for text attributes that you want applied to the whole text container. 如果你仅想要将样式应用到该文本部分,请在容器中的文本元素上(例如 TextBlock.Inlines 中的 Run 上或 RichTextBlock.Blocks 中的 Paragraph 上)设置属性。If you want styles applied just to sections of the text, set attributes on the text elements within the container, such as on a Run in TextBlock.Inlines or on a Paragraph in RichTextBlock.Blocks.

当应用于 TextBlock 时,这些样式如下所示:The styles look like this when applied to a TextBlock:

文本块样式

<TextBlock Text="Header" Style="{StaticResource HeaderTextBlockStyle}"/>
<TextBlock Text="SubHeader" Style="{StaticResource SubheaderTextBlockStyle}"/>
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>
<TextBlock Text="SubTitle" Style="{StaticResource SubtitleTextBlockStyle}"/>
<TextBlock Text="Base" Style="{StaticResource BaseTextBlockStyle}"/>
<TextBlock Text="Body" Style="{StaticResource BodyTextBlockStyle}"/>
<TextBlock Text="Caption" Style="{StaticResource CaptionTextBlockStyle}"/>

有关如何在应用中使用 Windows 类型渐变的指南,请参阅 Windows 应用中的版式For guidance on how to use the Windows type ramp in your app, see Typography in Windows apps.

BaseTextBlockStyleBaseTextBlockStyle

TargetTypeTextBlockTargetType: TextBlock

为所有其他 TextBlock 容器样式提供常用属性。Supplies the common properties for all the other TextBlock container styles.

<!-- Usage -->
<TextBlock Text="Base" Style="{StaticResource BaseTextBlockStyle}"/>

<!-- Style definition -->
<Style x:Key="BaseTextBlockStyle" TargetType="TextBlock">
    <Setter Property="FontFamily" Value="Segoe UI"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="TextTrimming" Value="None"/>
    <Setter Property="TextWrapping" Value="Wrap"/>
    <Setter Property="LineStackingStrategy" Value="MaxHeight"/>
    <Setter Property="TextLineBounds" Value="Full"/>
</Style>

HeaderTextBlockStyleHeaderTextBlockStyle

<!-- Usage -->
<TextBlock Text="Header" Style="{StaticResource HeaderTextBlockStyle}"/>

<!-- Style definition -->
<Style x:Key="HeaderTextBlockStyle" TargetType="TextBlock"
       BasedOn="{StaticResource BaseTextBlockStyle}">
    <Setter Property="FontSize" Value="46"/>
    <Setter Property="FontWeight" Value="Light"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

SubheaderTextBlockStyleSubheaderTextBlockStyle

<!-- Usage -->
<TextBlock Text="SubHeader" Style="{StaticResource SubheaderTextBlockStyle}"/>

<!-- Style definition -->
<Style x:Key="SubheaderTextBlockStyle" TargetType="TextBlock" 
       BasedOn="{StaticResource BaseTextBlockStyle}">
    <Setter Property="FontSize" Value="34"/>
    <Setter Property="FontWeight" Value="Light"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

TitleTextBlockStyleTitleTextBlockStyle

<!-- Usage -->
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>

<!-- Style definition -->
<Style x:Key="TitleTextBlockStyle" TargetType="TextBlock" 
       BasedOn="{StaticResource BaseTextBlockStyle}">
    <Setter Property="FontWeight" Value="SemiLight"/>
    <Setter Property="FontSize" Value="24"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

SubtitleTextBlockStyleSubtitleTextBlockStyle

<!-- Usage -->
<TextBlock Text="SubTitle" Style="{StaticResource SubtitleTextBlockStyle}"/>

<!-- Style definition -->
<Style x:Key="SubtitleTextBlockStyle" TargetType="TextBlock" 
       BasedOn="{StaticResource BaseTextBlockStyle}">
    <Setter Property="FontWeight" Value="Normal"/>
    <Setter Property="FontSize" Value="20"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

BodyTextBlockStyleBodyTextBlockStyle

<!-- Usage -->
<TextBlock Text="Body" Style="{StaticResource BodyTextBlockStyle}"/>

<!-- Style definition -->
<Style x:Key="BodyTextBlockStyle" TargetType="TextBlock" 
       BasedOn="{StaticResource BaseTextBlockStyle}">
    <Setter Property="FontWeight" Value="Normal"/>
    <Setter Property="FontSize" Value="14"/>
</Style>

CaptionTextBlockStyleCaptionTextBlockStyle

<!-- Usage -->
<TextBlock Text="Caption" Style="{StaticResource CaptionTextBlockStyle}"/>

<!-- Style definition -->
<Style x:Key="CaptionTextBlockStyle" TargetType="TextBlock" 
       BasedOn="{StaticResource BaseTextBlockStyle}">
    <Setter Property="FontSize" Value="12"/>
    <Setter Property="FontWeight" Value="Normal"/>
</Style>

BaseRichTextBlockStyleBaseRichTextBlockStyle

TargetTypeRichTextBlockTargetType: RichTextBlock

为所有其他 RichTextBlock 容器样式提供常用属性。Supplies the common properties for all the other RichTextBlock container styles.

<!-- Usage -->
<RichTextBlock Style="{StaticResource BaseRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BaseRichTextBlockStyle" TargetType="RichTextBlock">
    <Setter Property="FontFamily" Value="Segoe UI"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="TextTrimming" Value="None"/>
    <Setter Property="TextWrapping" Value="Wrap"/>
    <Setter Property="LineStackingStrategy" Value="MaxHeight"/>
    <Setter Property="TextLineBounds" Value="Full"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

BodyRichTextBlockStyleBodyRichTextBlockStyle

<!-- Usage -->
<RichTextBlock Style="{StaticResource BodyRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BodyRichTextBlockStyle" TargetType="RichTextBlock" BasedOn="{StaticResource BaseRichTextBlockStyle}">
    <Setter Property="FontWeight" Value="Normal"/>
</Style>

注意:  RichTextBlock 样式不具有 TextBlock 包含的所有文本渐变样式,主要原因是适用于“RichTextBlock”的基于块的文档对象模型使对个别文本元素设置属性更为简单。Note:  The RichTextBlock styles don't have all the text ramp styles that TextBlock does, mainly because the block-based document object model for RichTextBlock makes it easier to set attributes on the individual text elements. 同样,使用 XAML 内容属性设置 TextBlock.Text 将出现以下情况:没有要设置样式的文本元素,因此你必须设置容器样式。Also, setting TextBlock.Text using the XAML content property introduces a situation where there is no text element to style and thus you'd have to style the container. 对于"RichTextBlock",这不是问题,因为其文本内容始终位于特定的文本元素(例如 Paragraph)中,你可能会在该元素中为页面标头、页面子标头和类似文本渐变定义应用 XAML 样式。That isn't an issue for RichTextBlock because its text content always has to be in specific text elements like Paragraph, which is where you might apply XAML styles for page header, page subheader and similar text ramp definitions.

其他命名样式Miscellaneous Named styles

还存在一组额外的键控 Style 定义,可供你向 Button 应用不同于其默认隐式样式的样式。There's an additional set of keyed Style definitions you can apply to style a Button differently than its default implicit style.

TextBlockButtonStyleTextBlockButtonStyle

TargetTypeButtonBaseTargetType: ButtonBase

当你需要显示用户可以点击以进行操作的文本时,请将此样式应用到 ButtonApply this style to a Button when you need to show text that a user can click to take action. 使用当前主题色设置该文本的样式以在交互时进行区分,并且该文本具有非常适用于文本的焦点矩形。The text is styled using the current accent color to distinguish it as interactive and has focus rectangles that work well for text. HyperlinkButton 的隐式样式不同,“TextBlockButtonStyle”不会为文本添加下划线。Unlike the implicit style of a HyperlinkButton, the TextBlockButtonStyle does not underline the text.

该模板还设置显示文本的样式以使用 SystemControlHyperlinkBaseMediumBrush(适用于“PointerOver”状态)、SystemControlHighlightBaseMediumLowBrush(适用于“Pressed”状态)和 SystemControlDisabledBaseLowBrush(适用于“Disabled”状态)。The template also styles the presented text to use SystemControlHyperlinkBaseMediumBrush (for "PointerOver" state), SystemControlHighlightBaseMediumLowBrush (for "Pressed" state) and SystemControlDisabledBaseLowBrush (for "Disabled" state).

下面介绍向其应用了“TextBlockButtonStyle”资源的 ButtonHere's a Button with the TextBlockButtonStyle resource applied to it.

<Button Content="Clickable text" Style="{StaticResource TextBlockButtonStyle}"
        Click="Button_Click"/>

它的外观如下所示:It looks like this:

按钮的样式看起来像文本

TargetTypeButtonTargetType: Button

Style 提供的适用于 Button 的完整模板可能是适用于导航应用的导航后退按钮。This Style provides a complete template for a Button that can be the navigation back button for a navigation app. 默认尺寸是 40 x 40 像素。The default dimensions are 40 x 40 pixels. 要定制样式,可明确设置 HeightWidthFontSize 和“Button”上的其他属性,也可以使用 BasedOn 创建一个派生的样式。To tailor the styling you can either explicitly set the Height, Width, FontSize, and other properties on your Button or create a derived style using BasedOn.

下面介绍向其应用了“NavigationBackButtonNormalStyle”资源的 ButtonHere's a Button with the NavigationBackButtonNormalStyle resource applied to it.

<Button Style="{StaticResource NavigationBackButtonNormalStyle}" />

它的外观如下所示:It looks like this:

看起来像后退按钮样式的按钮

TargetTypeButtonTargetType: Button

Style 提供的适用于 Button 的完整模板可能是适用于导航应用的导航后退按钮。This Style provides a complete template for a Button that can be the navigation back button for a navigation app. 它与“NavigationBackButtonNormalStyle”类似,但尺寸为 30 x 30 像素。It's similar to NavigationBackButtonNormalStyle, but its dimensions are 30 x 30 pixels.

下面是一个应用了“NavigationBackButtonSmallStyle”资源的 ButtonHere's a Button with the NavigationBackButtonSmallStyle resource applied to it.

<Button Style="{StaticResource NavigationBackButtonSmallStyle}" />

主题资源疑难解答Troubleshooting theme resources

如果你不遵循使用主题资源指南,你可能会看到与你的应用中的主题相关的意外行为。主题If you don’t follow the guidelines for using theme resources, you might see unexpected behavior related to themes in your app.

例如,当你打开浅色主题的浮出控件时,深色主题的应用的某些部分也会更改,就好像在浅色主题中一样。For example, when you open a light-themed flyout, parts of your dark-themed app also change as if they were in the light theme. 或者如果你导航至浅色主题的页面,然后再导航回来,此时原始的深色主题页面(或部分页面)看起来仍像在浅色主题中一样。Or if you navigate to a light-themed page and then navigate back, the original dark-themed page (or parts of it) now looks as though it is in the light theme.

通常,在提供“默认”主题和“高对比度”主题以支持高对比度方案,然后在你的应用的不同部分中使用“浅色”和“深色”主题时,会发生这些类型的问题。Typically, these types of issues occur when you provide a "Default" theme and a "HighContrast" theme to support high-contrast scenarios, and then use both "Light" and "Dark" themes in different parts of your app.

例如,考虑此主题字典定义:For example, consider this theme dictionary definition:

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemBaseHighColor}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

从直观上来说这看起来准确无误。Intuitively, this looks correct. 你想要在处于高对比度下时更改 myBrush 所指向的颜色,但在不处于高对比度下时,你依赖于 {ThemeResource} 标记扩展,以确保 myBrush 针对你的主题指向正确的颜色。You want to change the color pointed to by myBrush when in high-contrast, but when not in high-contrast, you rely on the {ThemeResource} markup extension to make sure that myBrush points to the right color for your theme. 如果你的应用从未在可视化树内的元素上设置 FrameworkElement.RequestedTheme,这通常会按预期工作。If your app never has FrameworkElement.RequestedTheme set on elements within its visual tree, this will typically work as expected. 但是,在开始设置可视化树的不同部分的主题时,你的应用会立即出现问题。However, you run into problems in your app as soon as you start to re-theme different parts of your visual tree.

与大多数其他 XAML 类型不同,产生该问题的原因是画笔是共享的资源。The problem occurs because brushes are shared resources, unlike most other XAML types. 如果你在 XAML 子树(具有可引用相同画笔资源的不同主题)中具有 2 个元素,则当框架遍历每个子树以更新其 {ThemeResource} 标记扩展表达式时,将在其他子树中反映对已共享画笔资源的更改,这不是你预期的结果。If you have 2 elements in XAML sub-trees with different themes that reference the same brush resource, then as the framework walks each sub-tree to update its {ThemeResource} markup extension expressions, changes to the shared brush resource are reflected in the other sub-tree, which is not your intended result.

若要解决此问题,除了“高对比度”以外,还使用“浅色”和“深色”主题的单独主题字典替换“默认”字典:To fix this, replace the "Default" dictionary with separate theme dictionaries for both "Light" and "Dark" themes in addition to "HighContrast":

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemBaseHighColor}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemBaseHighColor}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

但是,如果其中任何资源在继承属性(如 Foreground)中引用,则仍会发生这些问题。However, problems still occur if any of these resources are referenced in inherited properties like Foreground. 你的自定义控件模板可能使用 {ThemeResource} 标记扩展指定元素的前景色,但当框架将继承的值传播到子元素时,它可以直接引用由 {ThemeResource} 标记扩展表达式解决的资源。Your custom control template might specify the foreground color of an element using the {ThemeResource} markup extension, but when the framework propagates the inherited value to child elements, it provides a direct reference to the resource that was resolved by the {ThemeResource} markup extension expression. 这将在框架处理主题更改时导致问题,因为它遍历控件的可视化树。This causes problems when the framework processes theme changes as it walks your control's visual tree. 它将重新计算 {ThemeResource} 标记扩展表达式以获取新的画笔资源,但尚未将该引用传播到你的控件的子元素;这种情况将在以后发生(例如在下一个测量阶段期间)。It re-evaluates the {ThemeResource} markup extension expression to get a new brush resource but doesn’t yet propagate this reference down to the children of your control; this happens later, such as during the next measure pass.

因此,在遍历控件可视化树以响应主题更改后,该框架将遍历子项并更新对其设置的任何 {ThemeResource} 标记扩展表达式,或在其属性上设置的对象。As a result, after walking the control visual tree in response to a theme change, the framework walks the children and updates any {ThemeResource} markup extension expressions set on them, or on objects set on their properties. 在此情况下会发生问题;框架将遍历画笔资源,并且因为它使用 {ThemeResource} 标记扩展指定其颜色,因此它将重新计算。This is where the problem occurs; the framework walks the brush resource and because it specifies its color using a {ThemeResource} markup extension, it's re-evaluated.

此时,框架看起来已被你的主题字典污染,因为它现在具有的资源来自从另一个字典设置其颜色的一个字典。At this point, the framework appears to have polluted your theme dictionary because it now has a resource from one dictionary that has its color set from another dictionary.

若要解决此问题,请使用 {StaticResource} 标记扩展而不是 {ThemeResource} 标记扩展To fix this problem, use the {StaticResource} markup extension instead of {ThemeResource} markup extension. 通过应用指南,主题字典如下所示:With the guidelines applied, the theme dictionaries look like this:

<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource SystemBaseHighColor}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource SystemBaseHighColor}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

请注意,{ThemeResource} 标记扩展仍在“HighContrast”字典而不是 {StaticResource} 标记扩展中使用。Notice that the {ThemeResource} markup extension is still used in the "HighContrast" dictionary instead of {StaticResource} markup extension. 此情况属于在指南中的前面部分所给定的异常情况。This situation falls under the exception given earlier in the guidelines. 用于“高对比度”主题的大多数画笔值使用由系统全局控制的颜色选择,但会作为特别命名的资源暴露给 XAML(名称中带有“SystemColor”前缀)。Most of the brush values that are used for the "HighContrast" theme are using color choices that are globally controlled by the system, but exposed to XAML as a specially-named resource (those prefixed with ‘SystemColor’ in the name). 系统使用户可以通过“轻松访问中心”设置应该用于其高对比度设置的特定颜色。The system enables the user to set the specific colors that should be used for their high contrast settings through the Ease of Access Center. 这些颜色选择将应用于特殊命名的资源中。Those color choices are applied to the specially-named resources. 当 XAML 框架检测到画笔在系统级别上发生更改时,它也将使用相同的主题更改事件更新这些画笔。The XAML framework uses the same theme changed event to also update these brushes when it detects they’ve changed at the system level. 这就是在此处使用 {ThemeResource} 标记扩展的原因。This is why the {ThemeResource} markup extension is used here.