HandyControl 原生控件指南：TextBlock 文本块样式体系与 BasedOn 扩展实践

• UI组件
• 桌面应用

TextBlock是 WPF 中使用频率最高的基础控件之一，而 HandyControl 在native_controls原生控件分类下为其内置了一套完整、可复用的文本样式体系。本文围绕 HandyControl 仓库中 TextBlock 文本块文档 展开，系统讲解TextBlockBaseStyle与TextBlockBoldBaseStyle两类基础样式的设计原则、全部预设样式的字号与配色映射，以及如何基于它们用BasedOn快速派生业务自定义样式，最终让你的文本在不同场景下保持统一的视觉层级与主题联动。

样式体系概览与文件位置

HandyControl 的 TextBlock 样式遵循“基础样式 + 派生样式”的两级结构，集中定义在两个资源字典中：

• 基础样式：TextBlockBaseStyle.xaml，定义TextBlockBaseStyle、TextBlockBoldBaseStyle以及hc:HighlightTextBlock的HighlightTextBlockBaseStyle；
• 派生样式：TextBlock.xaml，基于上述基础样式定义全部预设的 TextBlock 样式。

在合并后的主题文件 Theme.xaml（约第 1343-3421 行）中可以看到这些样式被整体内联合并；而 Theme_40.txt 与 Theme_GE45.txt 则记录了样式文件的合并清单，其中明确包含Styles\Base\TextBlockBaseStyle.xaml与Styles\TextBlock.xaml。也就是说，无论你引用Theme.xaml还是按需引用单独的样式文件，都能拿到同一套样式定义。

基础样式：TextBlockBaseStyle 与 TextBlockBoldBaseStyle

官方文档明确提示：这两个基础样式不推荐直接使用，应当始终被其它样式以BasedOn的方式继承使用。之所以这样设计，是因为基础样式承担了“统一默认值”的职责，直接使用会让你的 XAML 失去派生扩展的余地，也不利于主题统一。

查看 TextBlockBaseStyle.xaml 的源码，可以确认基础样式共设置了三个默认属性：

<Style x:Key="TextBlockBaseStyle" TargetType="TextBlock"> <Setter Property="VerticalAlignment" Value="Center"/> <Setter Property="HorizontalAlignment" Value="Center"/> <Setter Property="Foreground" Value="{DynamicResource PrimaryTextBrush}"/> </Style> <Style x:Key="TextBlockBoldBaseStyle" BasedOn="{StaticResource TextBlockBaseStyle}" TargetType="TextBlock"> <Setter Property="FontWeight" Value="Bold"/> </Style>

这里的前景色使用了DynamicResource而非StaticResource，意味着文本颜色会随 HandyControl 的皮肤（如SkinDefault、SkinDark、SkinViolet，见 Themes 目录）动态切换，这是整个样式体系与主题联动的关键机制。

预设样式清单：字号与配色映射

基于两类基础样式，TextBlock.xaml 一共派生出了 17 个预设样式，可按用途分为三组：

标题层级组（控制字号）

语义配色组（控制前景色）

默认样式

以上字号资源统一定义在 Fonts.xaml：

<system:Double x:Key="LargeFontSize">24</system:Double> <system:Double x:Key="HeadFontSize">20</system:Double> <system:Double x:Key="SubHeadFontSize">16</system:Double> <system:Double x:Key="TextFontSize">12</system:Double>

而配色画刷定义在 Brushes.xaml：其中PrimaryBrush、DangerBrush、WarningBrush、InfoBrush、SuccessBrush均为从左到右的LinearGradientBrush（浅色 → 深色渐变），PrimaryTextBrush、SecondaryTextBrush、ThirdlyTextBrush、AccentBrush为SolidColorBrush。理解了这两份资源定义，你就知道为什么默认组的语义样式能呈现出比普通单色更丰富的视觉效果。

案例：完整可运行的样式演示

官方文档给出了一个可以直接复制运行的演示案例，把三组样式依次渲染在一列上，非常适合用于快速目检每种样式效果。原文案例如下（稍作整理）：

<StackPanel> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockLargeBold" Style="{StaticResource TextBlockLargeBold}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockLarge" Style="{StaticResource TextBlockLarge}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockHeaderBold" Style="{StaticResource TextBlockTitleBold}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockHeader" Style="{StaticResource TextBlockTitle}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockSubHeaderBold" Style="{StaticResource TextBlockSubTitleBold}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockSubHeader" Style="{StaticResource TextBlockSubTitle}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultBold" Style="{StaticResource TextBlockDefaultBold}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefault" Style="{StaticResource TextBlockDefault}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultAccent" Style="{StaticResource TextBlockDefaultAccent}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultSecLight" Style="{StaticResource TextBlockDefaultSecLight}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultThiLight" Style="{StaticResource TextBlockDefaultThiLight}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultPrimary" Style="{StaticResource TextBlockDefaultPrimary}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultDanger" Style="{StaticResource TextBlockDefaultDanger}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultWarning" Style="{StaticResource TextBlockDefaultWarning}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultInfo" Style="{StaticResource TextBlockDefaultInfo}"/> <TextBlock HorizontalAlignment="Left" Margin="5" Text="TextBlockDefaultSuccess" Style="{StaticResource TextBlockDefaultSuccess}"/> </StackPanel>

注意案例中的Text只是展示用文本，样式由Style="{StaticResource ...}"决定；例如Text="TextBlockHeader"对应TextBlockTitle样式，Text="TextBlockSubHeaderBold"对应TextBlockSubTitleBold。这个案例在仓库中也有对应的真实演示页面 TextBlockDemo.xaml，它使用hc:UniformSpacingPanel（Orientation="Vertical"、Spacing="5"）加hc:ScrollViewer（IsInertiaEnabled="True"）承载同样的样式列表，放在TransitioningContentControl中用于演示切换动画，可作为实际工程化写法的参考。

基于 BasedOn 的扩展实践

官方对基础样式的使用约束非常明确：“始终被其它样式以BasedOn的方式使用”。这也是 HandyControl 整个主题体系的通用约定。在实际项目中，你可以这样派生自己的业务样式：

<Style x:Key="MyPageTitleStyle" BasedOn="{StaticResource TextBlockTitleBold}" TargetType="TextBlock"> <Setter Property="Foreground" Value="{DynamicResource PrimaryBrush}"/> </Style> <Style x:Key="MyMutedTextStyle" BasedOn="{StaticResource TextBlockDefault}" TargetType="TextBlock"> <Setter Property="Foreground" Value="{DynamicResource ThirdlyTextBrush}"/> <Setter Property="TextTrimming" Value="CharacterEllipsis"/> </Style>

这样做的好处是：即使未来基础样式的默认值（如前景色、对齐方式）随主题升级而变化，你的派生样式依然能自动继承最新默认值，只覆盖自己关心的属性，避免重复维护。

相关延伸：HighlightTextBlock 高亮文本块

在 TextBlockBaseStyle.xaml 中，还顺带定义了高亮文本块的基样式：

<Style x:Key="HighlightTextBlockBaseStyle" TargetType="hc:HighlightTextBlock"> <Setter Property="HighlightBrush" Value="{DynamicResource PrimaryBrush}"/> <Setter Property="HighlightTextBrush" Value="{DynamicResource TextIconBrush}"/> </Style>

随后在 TextBlock.xaml 末尾通过<Style BasedOn="{StaticResource HighlightTextBlockBaseStyle}" TargetType="hc:HighlightTextBlock"/>将其注册为hc:HighlightTextBlock的类型默认样式，即无需指定 Key 即可生效。这属于 TextBlock 样式体系的一部分扩展，适合需要关键词高亮展示的场景。

使用注意事项

1. 引用方式：直接使用Style="{StaticResource TextBlockTitle}"即可；若单独引入样式文件，需保证 Fonts.xaml 与 Brushes.xaml 中的资源先被加载，因为这些样式通过StaticResource/DynamicResource引用了字号与画刷资源。
2. 不要直接使用基础样式：TextBlockBaseStyle与TextBlockBoldBaseStyle是设计给派生用的，直接使用时既无法体现语义，也会绕开主题统一管理。
3. 主题联动：前景色统一使用DynamicResource，切换 HandyControl 皮肤（SkinDefault/SkinDark/SkinViolet）时文本颜色会自动适配，无需额外处理。
4. 动态资源与静态资源的选择：派生样式中的Foreground建议同样使用DynamicResource，以保持与主题的实时联动。

掌握 HandyControl 的 TextBlock 样式体系后，你可以在项目中快速建立一致的文本视觉层级：用TextBlockTitle/TextBlockSubTitle区分标题，用TextBlockDefault*系列表达语义状态，再通过BasedOn扩展出自己的业务样式，既省去了重复写Setter的样板代码，又保证了与主题皮肤的无缝协同。

• UI组件
• 桌面应用