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 架構支援的佈景主題有 3 個:"Light"、"Dark" 和 "HighContrast"。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. 基於設計目的,Windows 軟體開發套件 (SDK) 安裝的 \([Program Files])\[Windows Kits]\[10]\[DesignTime]\[CommonConfiguration]\[Neutral]\[UAP]\<SDK 版本>\[Generic] 資料夾中會提供 themeresources.xaml。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

適用於 "Light"、"Dark" 及 "HighContrast" 佈景主題的色彩組合可在 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 和 Dark 佈景主題色彩Light and Dark theme colors

XAML 架構提供一組已命名的 Color 資源,其中包含針對 "Light" 和 "Dark" 佈景主題量身訂做的值。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.

此表格列出索引鍵、簡單名稱,以及代表色彩的字串 (使用 #aarrggbb 格式),適用於 XAML 架構提供的 "Light" 和 "Dark" 資源。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

Alt 淺色佈景主題

Alt 深色佈景主題

ListList

清單淺色佈景主題

清單深色佈景主題

ChromeChrome

Chrome 淺色佈景主題

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. 不過,當系統的運作 (和 app 的執行) 是使用 "HighContrast" 佈景主題時,有許多 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) 前景Foreground #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. 在 "Light" 和 "Dark" 資源字典中,此筆刷的定義如下:In the "Light" and "Dark" resource dictionaries, this brush is defined like this:

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

在 "HighContrast" 資源字典中,此筆刷的定義如下: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
HighContrastHighContrast 背景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 中文字容器的 Style,特別是針對 TextBlockRichTextBlockThe 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 中的 RunRichTextBlock.Blocks 中的 ParagraphIf 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).

以下是 Button 與套用到它的 TextBlockButtonStyle 資源。Here'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 提供可做為瀏覽 app 之向後瀏覽按鈕的 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. 若要量身打造樣式,您可以在 Button 上明確設定 HeightWidthFontSize 及其他屬性,或者使用 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 提供可做為瀏覽 app 之向後瀏覽按鈕的 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

如果您未遵循使用佈景主題資源的指導方針,可能會看到與您的 App 中佈景主題相關的非預期行為。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.

通常這些類型的問題會在您提供 "Default" 佈景主題和 "HighContrast" 佈景主題以支援高對比案例,然後在應用程式的不同部分使用 "Light" 和 "Dark" 佈景主題時發生。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. 如果您的 app 絕對不會在其視覺化樹狀結構內的元素上設定 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.

若要修正此問題,除了 "HighContrast" 之外,還可以針對 "Light" 和 "Dark" 佈景主題,使用不同的佈景主題字典來取代 "Default" 字典: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.

若要解決此問題,請不要使用 {ThemeResource} 標記延伸,改用 {StaticResource} 標記延伸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>

請注意,仍會在 "HighContrast" 字典中使用 {ThemeResource} 標記延伸,而不是使用 {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. 大多數用於 "HighContrast" 佈景主題的筆刷值都是使用由系統全域控制但對 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.