WPF on 纪伟的个人博客

WPF 学习笔记（十二）：性能与发布

Tue, 02 Jun 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

最后一篇。前面 11 篇讲了 WPF 的原理和写法，本篇关注两件事——让应用跑得快、让应用能上线。这两件事在生产环境比"功能正确"更重要。

本篇之后，WPF 系列就完结。最后会给一个系列知识图谱，方便后续回顾。

本文要回答：

Freezable 冻结到底解决了什么？WPF 为什么不能 AOT / Trimming？self-contained 和 framework-dependent 怎么选？

一、性能优化的总思路

1.1 WPF 性能瓶颈的三个层级

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


1. 渲染层（GPU）
 - 复杂模板、过多视觉树节点
 - 高频动画、过度绘制
 - 大图、缓存失效

2. 布局层（CPU）
 - 复杂 Grid 嵌套
 - 频繁 InvalidateMeasure
 - 大数据未虚拟化

3. 绑定层（CPU）
 - 大量绑定、复杂 Path
 - 频繁 PropertyChanged
 - Converter 滥用

1.2 性能优化的优先级

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


高收益、低改动：
 ✅ 大数据用虚拟化
 ✅ Freeze 资源
 ✅ 避免 StackPanel 装大数据
 ✅ 优先用 RenderTransform 而不是 Width/Height 动画

中等收益：
 - 简化 ControlTemplate 嵌套
 - 减少绑定 Converter
 - 异步加载（不阻塞 UI 线程）

低收益、复杂改动：
 - 自定义 OnRender 替代控件
 - 用 SkiaSharp / Win2D
 - 手动管视觉树

二、Freezable：冻结资源

2.1 Freezable 是什么

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Freezable 是 WPF 一种特殊类型：
 - 可变状态（默认）：可以改属性
 - 冻结状态：不可变，性能更好

继承 Freezable 的类型：
 - Brush（SolidColorBrush、LinearGradientBrush...）
 - Geometry
 - Transform
 - Pen、DashStyle
 - ImageSource（部分）
 - 3D Material

2.2 为什么冻结更快

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


var brush = new SolidColorBrush(Colors.Red);

// 不冻：WPF 必须监听 brush 的变化（万一你改 Color）
// 每次渲染都要检查
button.Background = brush;

// 冻：声明"我不会改"
brush.Freeze();
button.Background = brush;
// WPF 知道不可变 → 跳过监听 → 渲染更快
// 而且多个线程可以安全访问（线程安全）

1
2
3
4
5
6
7
8
9


性能差异：
 Freeze 一个常用 Brush，渲染频繁场景
 → 减少 10~30% 渲染开销
 → 频繁改色的场景效果更明显

附加好处：
 - 冻结对象线程安全（可跨线程访问）
 - 不会触发变更通知
 - 适合做资源（Resources 字典里都该 Freeze）

2.3 在 XAML 里冻结

1
2
3
4
5
6
7
8


<!-- XAML 里写的资源会自动 Freeze -->
<Application.Resources>
 <!-- 这是 Frozen 的 -->
 <SolidColorBrush x:Key="bg" Color="Red"/>
</Application.Resources>

<!-- 但动态创建的不会 -->
<!-- C# 里 new 的 Brush 不会自动冻 -->

2.4 在 C# 里冻结

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public static readonly Brush WarningBrush = CreateFrozenBrush();

private static Brush CreateFrozenBrush()
{
 var brush = new LinearGradientBrush
 {
 StartPoint = new Point(0, 0),
 EndPoint = new Point(1, 0)
 };
 brush.GradientStops.Add(new GradientStop(Colors.Yellow, 0));
 brush.GradientStops.Add(new GradientStop(Colors.Red, 1));
 brush.Freeze(); // ← 关键
 return brush;
}

2.5 检查与解冻

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


if (brush.CanFreeze)
 brush.Freeze();

if (brush.IsFrozen)
{
 // 解冻 = 创建可变副本
 var mutable = brush.Clone();
 mutable.Opacity = 0.5;
 mutable.Freeze();
}

三、虚拟化与滚动性能

3.1 启用虚拟化

1
2
3
4


<ListBox ItemsSource="{Binding Items}"
 VirtualizingPanel.IsVirtualizing="True"
 VirtualizingPanel.VirtualizationMode="Recycling"
 VirtualizingPanel.ScrollUnit="Pixel"/>

1
2
3
4
5
6
7
8


关键属性：
 IsVirtualizing：开/关虚拟化（默认 True）
 VirtualizationMode：
 Standard：每次创建新容器
 Recycling：复用容器（推荐，性能好）
 ScrollUnit：
 Item：按 Item 滚动（默认，可能卡）
 Pixel：按像素滚动（流畅）

3.2 虚拟化的"陷阱"

嵌套破坏虚拟化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<!-- ❌ 外层 ScrollViewer + 内层 ListBox -->
<ScrollViewer>
 <StackPanel> <!-- StackPanel 给子无限高度 -->
 <ListBox ItemsSource="{Binding Items}"/>
 <!-- ListBox 高度被拉伸到所有 Item → 虚拟化失效 -->
 </StackPanel>
</ScrollViewer>

<!-- ✅ ListBox 自己滚动 -->
<Grid>
 <ListBox ItemsSource="{Binding Items}"/>
</Grid>

ItemsControl 默认不虚拟化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<!-- ❌ ItemsControl 默认用 StackPanel -->
<ItemsControl ItemsSource="{Binding Items}"/>

<!-- ✅ 改用 VirtualizingStackPanel -->
<ItemsControl ItemsSource="{Binding Items}">
 <ItemsControl.ItemsPanel>
 <ItemsPanelTemplate>
 <VirtualizingStackPanel/>
 </ItemsPanelTemplate>
 </ItemsControl.ItemsPanel>
</ItemsControl>

<!-- ✅ 或直接用 ListBox -->
<ListBox ItemsSource="{Binding Items}"/>

设固定高度也破坏虚拟化

1
2
3
4
5
6
7
8


<!-- ❌ 固定高度 = 没有滚动 = 虚拟化没用 -->
<ListBox Height="500" ItemsSource="{Binding Items}"/>
<!-- 1000 个 Item 还是全部实例化 -->

<!-- ✅ 让 ListBox 在容器内 Stretch -->
<Grid>
 <ListBox ItemsSource="{Binding Items}"/>
</Grid>

3.3 ContainerGenerator 性能

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 虚拟化时，容器在后台生成
// 监听 ItemContainerGenerator.StatusChanged
listBox.ItemContainerGenerator.StatusChanged += (s, e) =>
{
 var status = listBox.ItemContainerGenerator.Status;
 if (status == GeneratorStatus.ContainersGenerated)
 {
 // 容器生成完
 }
};

四、绑定优化

4.1 减少 Converter

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- ❌ Converter 滥用 -->
<TextBlock Visibility="{Binding IsVisible, Converter={StaticResource BoolToVis}}"/>

<!-- ✅ 用 DataTrigger（在 Style 里） -->
<Style TargetType="TextBlock">
 <Style.Triggers>
 <DataTrigger Binding="{Binding IsVisible}" Value="False">
 <Setter Property="Visibility" Value="Collapsed"/>
 </DataTrigger>
 </Style.Triggers>
</Style>

1
2
3
4
5
6
7
8
9


Converter 的代价：
 每次属性变化都调用 Convert
 跨语言边界（托管 → 反射）
 高频更新场景拖慢

替代方案：
 - 简单逻辑用 DataTrigger
 - 复杂逻辑用 ViewModel 暴露"加工后"的属性
 （ViewModel.IsVisibleText、ViewModel.StatusColor）

4.2 避免复杂 Path

1
2
3
4
5


<!-- ❌ 深层路径，每次都反射 -->
<TextBlock Text="{Binding User.Address.City.ZipCode}"/>

<!-- ✅ ViewModel 直接暴露扁平属性 -->
<TextBlock Text="{Binding ZipCode}"/>

4.3 OneTime 绑定

1
2
3
4


<!-- 数据几乎不变 → OneTime 性能最好 -->
<TextBlock Text="{Binding Name, Mode=OneTime}"/>

<!-- 不订阅 INPC，只绑定一次 -->

4.4 避免字符串格式化

1
2
3
4
5


<!-- ❌ 每次都格式化 -->
<TextBlock Text="{Binding Price, StringFormat=C}"/>

<!-- ✅ ViewModel 直接给字符串 -->
<TextBlock Text="{Binding PriceDisplay}"/>

4.5 异步绑定

1
2


<!-- .NET 4.5+ 异步绑定 -->
<TextBlock Text="{Binding ExpensiveProperty, IsAsync=True}"/>

1
2
3
4
5
6
7


IsAsync 的含义：
 - 在后台线程读属性
 - 不阻塞 UI
 - 适合"很慢的属性"

注意：本质还是同步读取，只是不在 UI 线程
真正的异步要用 Task + NotifyTask（第三方库）

五、Layout 优化

5.1 简化视觉树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<!-- ❌ 过度嵌套 -->
<Border>
 <Grid>
 <Border>
 <StackPanel>
 <Border>
 <Button/>
 </Border>
 </StackPanel>
 </Border>
 </Grid>
</Border>

<!-- ✅ 扁平 -->
<Grid>
 <Button/>
</Grid>

5.2 用 Canvas 处理固定布局

1
2
3
4
5
6


<!-- 固定布局（不用 measure） -->
<Canvas>
 <Button Canvas.Left="10" Canvas.Top="10"/>
</Canvas>

<!-- 比 Grid 快得多 -->

5.3 延迟创建（Lazy）

1
2
3
4
5
6
7


<TabControl>
 <TabItem Header="Tab 1">
 <local:HeavyView/> <!-- TabItem 默认全部创建 -->
 </TabItem>
</TabControl>

<!-- 改：每个 Tab 内容用 ContentPresenter + 触发器延迟 -->

六、RenderOptions

6.1 CachingHint

1
2
3
4


<!-- 复杂静态内容缓存 -->
<Path Data="..." RenderOptions.CachingHint="Cache"
 RenderOptions.CacheInvalidationThresholdMaximum="2"
 RenderOptions.CacheInvalidationThresholdMinimum="0.5"/>

1
2
3
4
5
6
7
8
9


默认（CachingHint=Default）：
 小元素：不缓存
 大元素：缓存

显式 Cache：
 强制缓存（适合重复绘制且不变的元素）

显式 NoCache：
 频繁变化的元素不缓存

6.2 EdgeMode

1
2
3
4
5
6


<!-- 边缘模式（位图） -->
<Image Source="photo.jpg" RenderOptions.BitmapScalingMode="HighQuality"/>
<!-- HighQuality（默认）：双线性，慢但好 -->
<!-- LowQuality：最近邻，快但糙 -->
<!-- NearestNeighbor：最近邻（像素艺术） -->
<!-- Fant：高质量下采样 -->

6.3 ProcessRenderMode

1
2
3
4


// 强制软件渲染（GPU 渲染反而慢的场景）
RenderOptions.ProcessRenderMode = RenderMode.SoftwareOnly;

// 默认 HardwareOnly（GPU 渲染）

1
2
3
4
5
6
7
8


何时用 SoftwareOnly：
 - 远程桌面（RDP）场景
 - 某些 GPU 驱动有 bug
 - 复杂 3D 在弱 GPU 上

何时不用：
 - 普通桌面应用
 - 复杂动画、特效

七、内存优化

7.1 弱事件模式

1
2
3
4
5
6
7
8
9


// ❌ 短生命周期对象订阅长生命周期事件
Application.Current.MainWindow.Closing += shortLived.Handler;
// shortLived 被持有，泄漏

// ✅ 弱事件
PropertyChangedEventManager.AddHandler(source, handler, nameof(source.Property));

// 或 Toolkit 的 WeakReferenceMessenger
WeakReferenceMessenger.Default.Register<MyMessage>(this, (r, m) => { ... });

7.2 大对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// ❌ 一次性加载大列表
public ObservableCollection<Item> Items { get; } = new();
foreach (var item in Enumerable.Range(0, 100000))
 Items.Add(new Item()); // 大量分配

// ✅ 分页 / 增量加载
public ObservableCollection<Item> Items { get; } = new();
private async Task LoadMoreAsync()
{
 var batch = await _service.GetItems(skip: Items.Count, take: 100);
 foreach (var item in batch) Items.Add(item);
}

7.3 释放资源

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// ❌ 忘记 Dispose
public MainWindow()
{
 var timer = new DispatcherTimer { Interval = TimeSpan.FromSeconds(1) };
 timer.Tick += Timer_Tick;
 timer.Start();
 // 窗口关闭，timer 仍持有窗口引用 → 泄漏
}

// ✅ 关闭时取消订阅
protected override void OnClosed(EventArgs e)
{
 _timer.Stop();
 _timer.Tick -= Timer_Tick;
 base.OnClosed(e);
}

八、性能诊断工具

8.1 Visual Studio Performance Profiler

1
2
3


CPU Usage：找 CPU 热点
Memory Usage：找内存泄漏
Application Timeline：找 UI 卡顿（WPF 专用）

8.2 WPF Performance Suite

1
2
3
4
5
6


旧工具（SDK 自带）：
 - Perforator：渲染统计
 - TraceProfiler：事件追踪
 - Visual Profiler：视觉树性能

新版本在 Windows SDK / Store 找

8.3 代码计时

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var sw = Stopwatch.StartNew();
// ... 操作
sw.Stop();
Debug.WriteLine($"耗时：{sw.ElapsedMilliseconds} ms");

// 计算渲染帧
CompositionTarget.Rendering += (s, e) =>
{
 _frameCount++;
};

九、发布：基础概念

9.1 部署模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Framework-Dependent（依赖框架）：
 - 假设用户机器已装 .NET Runtime
 - 发布包小（几 MB）
 - 用户必须自己装 .NET

Self-Contained（自包含）：
 - 把 .NET Runtime 打包进去
 - 发布包大（60~150 MB）
 - 用户无需装 .NET

Single-File（单文件）：
 - 所有 DLL 打成一个 exe
 - 用户体验好（一个文件）
 - 启动稍慢（首次解压）

9.2 csproj 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<PropertyGroup>
 <OutputType>WinExe</OutputType>
 <TargetFramework>net8.0-windows</TargetFramework>
 <UseWPF>true</UseWPF>

 <!-- 发布配置 -->
 <RuntimeIdentifier>win-x64</RuntimeIdentifier>
 <SelfContained>true</SelfContained>
 <PublishSingleFile>true</PublishSingleFile>
 <PublishReadyToRun>true</PublishReadyToRun>
 <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
 <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
</PropertyGroup>

1
2
3
4
5
6


RuntimeIdentifier：必须指定（win-x64 / win-x86 / win-arm64）
SelfContained：true 自包含 / false 框架依赖
PublishSingleFile：单文件发布
PublishReadyToRun：AOT 预编译（提前编 IL）
IncludeNativeLibrariesForSelfExtract：native 库也打进单文件
EnableCompressionInSingleFile：压缩单文件（体积更小，启动稍慢）

9.3 发布命令

1
2
3
4
5
6
7
8


# 自包含 + 单文件 + AOT
dotnet publish -c Release -r win-x64 --self-contained true \
 /p:PublishSingleFile=true \
 /p:PublishReadyToRun=true \
 /p:IncludeNativeLibrariesForSelfExtract=true

# 框架依赖（最小包）
dotnet publish -c Release -r win-x64 --self-contained false

9.4 体积对比

1
2
3
4
5
6
7
8


配置 体积
─────────────────────────────────────────
Framework-Dependent ~5 MB
Self-Contained ~80 MB
Self-Contained + SingleFile ~80 MB（一个文件）
Self-Contained + SingleFile + 压缩 ~50 MB
+ ReadyToRun +10 MB（提前编 IL）
+ Trimming ⚠️ WPF 不支持（见下节）

十、ReadyToRun 与 Trimming

10.1 ReadyToRun（R2R）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


ReadyToRun = 提前编译为 native 代码（部分）

优点：
 - 启动更快（JIT 不用从 IL 编译）
 - 仍兼容反射（不是完全 AOT）

代价：
 - 体积增加 10~30%
 - 跨平台弱（必须指定 RID）

WPF 支持：
 ✅ 完全支持
 建议生产应用开启

1
2


<PublishReadyToRun>true</PublishReadyToRun>
<PublishReadyToRunComposite>true</PublishReadyToRunComposite>

10.2 Trimming

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Trimming = 移除未使用的代码（减小体积）

WPF 的硬限制：
 ❌ WPF 不能 Trim（WPF 大量用反射）
 ❌ DependencyProperty.Register 反射注册
 ❌ XAML/BAML 解析反射
 ❌ Binding Path 反射

.NET 6+ 部分支持：
 ⚠️ 可以 trim 应用层代码（不影响 WPF 核心）
 ⚠️ 但 trim WPF 自己的代码会运行时崩

实践：
 Trimming 在 WPF 不推荐
 体积优化靠 SingleFile + 压缩

1
2
3


<!-- 不推荐 -->
<PublishTrimmed>true</PublishTrimmed>
<!-- 即使配 TrimMode=partial，风险也高 -->

10.3 NativeAOT

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


.NET 8+ 的 NativeAOT：
 - 完全 AOT 编译
 - 体积小、启动极快
 - 无 JIT、无反射（部分）

WPF 的现状：
 ❌ WPF 不支持 NativeAOT
 - DependencyProperty 注册依赖反射
 - XAML 解析依赖反射
 - 类型系统深度依赖运行时

替代方案：
 - WinUI 3：部分支持
 - Avalonia：实验性支持
 - MAUI：iOS / Android 用 AOT（不是 WPF）

 WPF 工程师：放弃 NativeAOT，用 R2R + SingleFile

十一、MSIX 打包

11.1 MSIX 是什么

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


MSIX = Windows 现代应用打包格式
 - 替代传统 MSI
 - 沙盒运行（隔离）
 - 自动更新（从 Microsoft Store）
 - 干净卸载（不残留注册表）

适用：
 - Microsoft Store 发布
 - 企业内部署
 - 自动更新场景

11.2 打包步骤

1
2
3
4
5


1. 用 Visual Studio 的 "Windows Application Packaging Project"
2. 引用 WPF 项目
3. 配置 Package.appxmanifest
4. 生成 .msix 包
5. 签名（测试或正式证书）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<!-- Package.appxmanifest 关键部分 -->
<Identity Name="MyApp"
 Publisher="CN=MyCompany"
 Version="1.0.0.0"/>

<Applications>
 <Application Id="App"
 Executable="$targetnametoken$.exe"
 EntryPoint="$targetentrypoint$">
 <uap:VisualElements
 DisplayName="MyApp"
 Description="My WPF Application"
 BackgroundColor="transparent"
 Square150x150Logo="Assets\Logo.png"/>
 </Application>
</Applications>

11.3 MSIX vs 传统安装包

维度	传统 exe/msi	MSIX
安装	注册表、Program Files	沙盒
卸载	可能残留	干净
更新	手动	自动
权限	用户 / 管理员	UAC 友好
兼容	全部 Windows	Win10 1709+
适合	老应用	现代应用

1
2
3
4


实践建议：
 - 桌面应用首选 MSIX（如果支持）
 - 老系统兼容用传统 exe
 - 内部工具直接 dotnet publish 单文件

十二、应用清单与兼容性

12.1 app.manifest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
 <assemblyIdentity version="1.0.0.0" name="MyApp"/>

 <!-- DPI 感知（详见第 4 篇） -->
 <application xmlns="urn:schemas-microsoft-com:asm.v3">
 <windowsSettings>
 <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
 <longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longPathAware>
 </windowsSettings>
 </application>

 <!-- 兼容性（声明支持的 Windows 版本） -->
 <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
 <application>
 <supportedOS Id="8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a"/> <!-- Windows 10/11 -->
 </application>
 </compatibility>
</assembly>

12.2 管理员权限

1
2


<!-- 请求管理员权限 -->
<requestedExecutionLevel level="requireAdministrator" uiAccess="false"/>

十三、自动更新

13.1 ClickOnce（旧）

1
2
3
4
5
6
7
8


特点：
 - .NET 早期技术
 - 自动更新简单
 - 但限制多（不能改注册表、沙盒）

适用：
 - 内部工具
 - 简单应用

13.2 现代：Velopack / Squirrel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Velopack（推荐）：
 - 现代化、跨平台
 - 增量更新
 - GitHub Release 集成
 - 替代 Squirrel

Squirrel：
 - 经典方案
 - GitHub 出品
 - 已基本停更

使用：
 Velopack 在 csproj 集成
 发布到 GitHub Release / 自建服务器
 应用启动检查更新

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// Velopack 示例
public partial class App : Application
{
 protected override void OnStartup(StartupEventArgs e)
 {
 VelopackApp.Build().Run();
 base.OnStartup(e);

 // 检查更新
 var mgr = new UpdateManager("https://myserver/releases");
 if (mgr.CheckForUpdates() is not null)
 {
 var upd = mgr.UpdateAppAsync();
 // 更新完成后重启
 }
 }
}

十四、WPF 知识图谱（系列总结）

经过 12 篇深入，WPF 的核心知识已经覆盖：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


┌─────────────────────────────────────────────────────────┐
│ WPF 知识图谱 │
├─────────────────────────────────────────────────────────┤
│ │
│ 基础机制（第 1~3 篇） │
│ ├─ 架构 + XAML 编译流水线 │
│ ├─ 依赖属性（11 级优先级 + 三回调链） │
│ └─ 路由事件（Tunneling/Bubbling/Direct） │
│ │
│ UI 与数据（第 4~7 篇） │
│ ├─ 布局系统（Measure/Arrange + Panel 全家桶） │
│ ├─ 数据绑定（INPC + Binding + CollectionView） │
│ ├─ 命令（ICommand + CommunityToolkit.Mvvm） │
│ └─ MVVM 工程化（DI + 导航 + 对话框） │
│ │
│ 外观与并发（第 8~10 篇） │
│ ├─ 样式与模板（Style/ControlTemplate/DataTemplate） │
│ ├─ Dispatcher 与 async/await │
│ └─ 动画与图形（保留模式 + Storyboard） │
│ │
│ 扩展与上线（第 11~12 篇） │
│ ├─ 自定义控件（UserControl/CustomControl/OnRender） │
│ └─ 性能与发布（Freezable/虚拟化/MSIX） │
│ │
└─────────────────────────────────────────────────────────┘

14.1 进阶路径

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


学完本系列，可以继续探索：

UI 框架对比：
 - WinUI 3（现代 Windows UI）
 - MAUI（跨平台）
 - Avalonia（跨平台、类 WPF）
 - Blazor Hybrid（Web 技术做桌面）

进阶主题：
 - SkiaSharp（高性能绘图）
 - Helix Toolkit（3D）
 - WebView2（嵌入式浏览器）
 - WPF + Blazor Hybrid（Razor 组件做桌面）

工程实践：
 - Prism（重量级 MVVM 框架）
 - ReactiveUI（响应式 MVVM）
 - StyleCop + Roslyn 分析器
 - XAML 热重载 + 设计时数据

发布生态：
 - Velopack（自动更新）
 - MSIX（现代打包）
 - Windows App SDK

14.2 后端工程师学 WPF 的"思维转变"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


从命令式 → 声明式
 传统：手动改 UI（textBox.Text = ...）
 WPF：声明绑定（{Binding}），数据驱动 UI

从事件 → 命令
 传统：button.Click += handler
 WPF：Command + ViewModel

从单线程 → UI 单线程 + Dispatcher
 传统：随便多线程
 WPF：UI 必须单线程，跨线程用 Dispatcher

从绝对定位 → 两阶段布局
 传统：控件 Location
 WPF：父容器 Measure/Arrange

从渲染即画 → 保留模式
 传统：OnPaint 自己画
 WPF：描述视觉树，框架渲染

十五、小结

本文是 WPF 系列收尾，聚焦生产环境：

性能优化的三层瓶颈（渲染/布局/绑定）
Freezable 冻结（10~30% 渲染提升）
虚拟化（大数据列表必备，注意嵌套陷阱）
绑定优化（少 Converter、扁平 Path、OneTime）
Layout 优化（简化视觉树、Canvas、延迟创建）
RenderOptions（CachingHint、ProcessRenderMode）
内存优化（弱事件、分页加载、释放资源）
发布模式（Framework-Dependent / Self-Contained / Single-File）
ReadyToRun（WPF 完全支持）
Trimming / NativeAOT（WPF 不支持，原因：反射依赖）
MSIX 打包（现代部署）
app.manifest（DPI 感知、权限、兼容性）
自动更新（Velopack）
WPF 系列知识图谱

1
2
3
4


记住三句话：
 1. 性能优化的第一刀是虚拟化 + Freeze——简单收益大
 2. WPF 不能 AOT/Trim——历史包袱（反射 + XAML 解析）
 3. 发布默认 Self-Contained + SingleFile + ReadyToRun——用户体验最好

系列完结

WPF 学习笔记系列 12 篇到这里全部完成：

架构总览与 XAML 原理
依赖属性
路由事件
布局系统
数据绑定
命令与 CommunityToolkit.Mvvm
MVVM 工程化与依赖注入
样式与模板
多线程与 Dispatcher
动画与图形
自定义控件
性能与发布

希望这份笔记能帮到你建立系统的 WPF 知识体系。WPF 是一个"老但深"的框架——表面 API 简单，底层机制复杂。理解了底层，写代码就不再迷茫；理解了机制，调性能就有了方向。

后端工程师学 WPF 的最大障碍不是 API，而是思维模式——从"命令式"切换到"声明式"。一旦完成这个转变，WPF 反而是 .NET 生态里最优雅的 UI 框架。

继续探索，继续精进。完。

WPF 学习笔记（十一）：自定义控件

Fri, 29 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

写 WPF 到一定程度，你会遇到"现有控件不够用"的场景——可能是想要一个 NumericUpDown、一个圆形进度环、一个带占位符的 TextBox。这时你需要在三种"自定义控件"路线里选一种：UserControl、CustomControl、重写 FrameworkElement。

本篇把三条路线讲透，并实战一个完整的 NumericUpDown 控件——这是 WPF 自定义控件的"Hello World"。

本文要回答：

UserControl、CustomControl、OnRender 怎么选？Generic.xaml 是什么？PART_xxx 命名约定干什么用？

一、三条路线

1.1 概览

1
2
3
4
5


路线 实现方式 适用场景
──────────────────────────────────────────────────────────────────────
1. UserControl 组合现有控件 视图级复用（登录框、列表项）
2. CustomControl 继承 Control + 模板 控件库、跨项目复用
3. 重写 OnRender 直接 DrawingContext 高性能绘图、完全自定义

1.2 选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


你的需求？
 ↓
需要重用一组 UI（登录框、地址卡）？
 → UserControl

需要"标准控件"但 WPF 没有（NumericUpDown、Timeline、ColorPicker）？
 → CustomControl

需要高性能绘图（折线图、热力图、自定义动画）？
 → 重写 OnRender（或 SkiaSharp）

只要"小修补"现有控件？
 → Style + ControlTemplate（详见第 8 篇，不要写新控件）

二、UserControl

2.1 特点

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


UserControl = "组合控件"
 - 继承 UserControl（间接 FrameworkElement）
 - XAML + code-behind
 - 把现有控件组合成一个"块"
 - 不可换皮肤（XAML 是固定的）

适用：
 - 重复使用的 UI 块（如登录框、地址卡）
 - 视图局部（如 Sidebar、TopBar）
 - 项目内复用（不跨项目）

2.2 创建

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<!-- LoginControl.xaml -->
<UserControl x:Class="MyApp.Controls.LoginControl"
 xmlns="..."
 xmlns:x="...">
 <Grid>
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 </Grid.RowDefinitions>

 <TextBox Grid.Row="0" x:Name="userBox" Margin="0,0,0,8"/>
 <PasswordBox Grid.Row="1" x:Name="pwdBox" Margin="0,0,0,8"/>
 <Button Grid.Row="2" Content="登录" Click="Login_Click"/>
 </Grid>
</UserControl>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// LoginControl.xaml.cs
public partial class LoginControl : UserControl
{
 public event EventHandler<string> LoginSubmitted;

 public LoginControl()
 {
 InitializeComponent();
 }

 private void Login_Click(object sender, RoutedEventArgs e)
 {
 LoginSubmitted?.Invoke(this, $"{userBox.Text}:{pwdBox.Password}");
 }
}

1
2
3
4


<!-- 使用 -->
<Window xmlns:ctrl="clr-namespace:MyApp.Controls">
 <ctrl:LoginControl LoginSubmitted="Login_LoginSubmitted"/>
</Window>

2.3 UserControl 的局限

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


❌ 不能换 ControlTemplate
 UserControl 的 XAML 是写死的，外部不能改

❌ 难做"主题"
 要主题切换只能改内部属性

❌ 不适合做"标准控件"
 派生、扩展不灵活

✅ 简单复用 OK
 视图局部、业务相关

三、CustomControl

3.1 特点

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


CustomControl = "真正的自定义控件"
 - 继承 Control（不是 UserControl）
 - 外观由 ControlTemplate 决定（外部可换）
 - 默认模板在 Themes/Generic.xaml
 - 可以暴露依赖属性、路由事件
 - 适合控件库

适用：
 - 控件库（开源、商业）
 - 跨项目复用
 - 需要"换肤"的控件

3.2 创建步骤

1
2
3
4
5


1. 新建 WPF Custom Control Library 项目（或现有项目添加）
2. 添加 CustomControl（继承 Control）
3. 注册依赖属性 + 路由事件
4. 在 Themes/Generic.xaml 写默认 ControlTemplate
5. 应用 TemplatePart / TemplateVisualState 元数据

3.3 Themes/Generic.xaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


约定路径：项目根 / Themes / Generic.xaml

 MyControlLibrary/
 ├── MyButton.cs
 ├── NumericUpDown.cs
 └── Themes/
 └── Generic.xaml ← 默认模板集中在这

WPF 自动加载这个文件（assembly 级 ThemeInfo）
[assembly: ThemeInfo(ResourceDictionaryLocation.None,
 ResourceDictionaryLocation.SourceAssembly)]
 ↑ 这里指定在 SourceAssembly 找 Generic.xaml

3.4 完整 NumericUpDown

控件类

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163


using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;

namespace MyApp.Controls;

public class NumericUpDown : Control
{
 static NumericUpDown()
 {
 // 重写默认样式 key（让 Generic.xaml 找到）
 DefaultStyleKeyProperty.OverrideMetadata(
 typeof(NumericUpDown),
 new FrameworkPropertyMetadata(typeof(NumericUpDown)));
 }

 // 依赖属性：Value
 public static readonly DependencyProperty ValueProperty =
 DependencyProperty.Register(
 nameof(Value),
 typeof(int),
 typeof(NumericUpDown),
 new FrameworkPropertyMetadata(
 defaultValue: 0,
 propertyChangedCallback: OnValueChanged,
 coerceValueCallback: CoerceValue),
 validateValueCallback: ValidateValue);

 public int Value
 {
 get => (int)GetValue(ValueProperty);
 set => SetValue(ValueProperty, value);
 }

 // 依赖属性：Minimum / Maximum
 public static readonly DependencyProperty MinimumProperty =
 DependencyProperty.Register(nameof(Minimum), typeof(int), typeof(NumericUpDown),
 new FrameworkPropertyMetadata(0, OnMinMaxChanged));

 public int Minimum
 {
 get => (int)GetValue(MinimumProperty);
 set => SetValue(MinimumProperty, value);
 }

 public static readonly DependencyProperty MaximumProperty =
 DependencyProperty.Register(nameof(Maximum), typeof(int), typeof(NumericUpDown),
 new FrameworkPropertyMetadata(100, OnMinMaxChanged));

 public int Maximum
 {
 get => (int)GetValue(MaximumProperty);
 set => SetValue(MaximumProperty, value);
 }

 // 依赖属性：SmallChange（步长）
 public static readonly DependencyProperty SmallChangeProperty =
 DependencyProperty.Register(nameof(SmallChange), typeof(int), typeof(NumericUpDown),
 new PropertyMetadata(1));

 public int SmallChange
 {
 get => (int)GetValue(SmallChangeProperty);
 set => SetValue(SmallChangeProperty, value);
 }

 // 路由事件：ValueChanged
 public static readonly RoutedEvent ValueChangedEvent =
 EventManager.RegisterRoutedEvent(
 nameof(ValueChanged),
 RoutingStrategy.Bubbling,
 typeof(RoutedPropertyChangedEventHandler<int>),
 typeof(NumericUpDown));

 public event RoutedPropertyChangedEventHandler<int> ValueChanged
 {
 add => AddHandler(ValueChangedEvent, value);
 remove => RemoveHandler(ValueChangedEvent, value);
 }

 // TemplatePart：声明模板里需要的命名元素
 [TemplatePart(Name = "PART_UpButton", Type = typeof(ButtonBase))]
 [TemplatePart(Name = "PART_DownButton", Type = typeof(ButtonBase))]
 [TemplatePart(Name = "PART_TextBox", Type = typeof(TextBox))]
 public class NumericUpDown { ... }

 // 元数据回调：值变化
 private static void OnValueChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
 {
 var control = (NumericUpDown)d;
 var oldVal = (int)e.OldValue;
 var newVal = (int)e.NewValue;

 // 更新内部 TextBox
 if (control._textBox != null)
 control._textBox.Text = newVal.ToString();

 // 触发路由事件
 control.RaiseEvent(new RoutedPropertyChangedEventArgs<int>(oldVal, newVal, ValueChangedEvent));
 }

 // 强制约束：value 必须在 [Minimum, Maximum]
 private static object CoerceValue(DependencyObject d, object baseValue)
 {
 var control = (NumericUpDown)d;
 var value = (int)baseValue;
 if (value < control.Minimum) return control.Minimum;
 if (value > control.Maximum) return control.Maximum;
 return value;
 }

 private static bool ValidateValue(object value)
 => value is int;

 private static void OnMinMaxChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
 {
 var control = (NumericUpDown)d;
 // 重新强制当前值（Min/Max 变了，Value 可能超界）
 control.CoerceValue(ValueProperty);
 }

 // 内部元素引用
 private ButtonBase? _upButton;
 private ButtonBase? _downButton;
 private TextBox? _textBox;

 // 模板应用时被调用
 public override void OnApplyTemplate()
 {
 base.OnApplyTemplate();

 // 取消旧元素的订阅
 if (_upButton != null) _upButton.Click -= UpButton_Click;
 if (_downButton != null) _downButton.Click -= DownButton_Click;
 if (_textBox != null) _textBox.TextChanged -= TextBox_TextChanged;

 // 用 GetTemplateChild 拿新元素
 _upButton = GetTemplateChild("PART_UpButton") as ButtonBase;
 _downButton = GetTemplateChild("PART_DownButton") as ButtonBase;
 _textBox = GetTemplateChild("PART_TextBox") as TextBox;

 // 重新订阅
 if (_upButton != null) _upButton.Click += UpButton_Click;
 if (_downButton != null) _downButton.Click += DownButton_Click;
 if (_textBox != null)
 {
 _textBox.Text = Value.ToString();
 _textBox.TextChanged += TextBox_TextChanged;
 }
 }

 private void UpButton_Click(object sender, RoutedEventArgs e)
 => Value += SmallChange;

 private void DownButton_Click(object sender, RoutedEventArgs e)
 => Value -= SmallChange;

 private void TextBox_TextChanged(object sender, TextChangedEventArgs e)
 {
 if (int.TryParse(_textBox!.Text, out int result))
 Value = result;
 }
}

注：上面 TemplatePart 特性应该放在主类声明上（不是嵌套类），整理示意。实际写法：

1
2
3
4


[TemplatePart(Name = "PART_UpButton", Type = typeof(ButtonBase))]
[TemplatePart(Name = "PART_DownButton", Type = typeof(ButtonBase))]
[TemplatePart(Name = "PART_TextBox", Type = typeof(TextBox))]
public class NumericUpDown : Control { ... }

Themes/Generic.xaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


<ResourceDictionary xmlns="..."
 xmlns:x="..."
 xmlns:local="clr-namespace:MyApp.Controls">

 <Style TargetType="{x:Type local:NumericUpDown}">
 <Setter Property="Template">
 <Setter.Value>
 <ControlTemplate TargetType="{x:Type local:NumericUpDown}">
 <Border Background="{TemplateBinding Background}"
 BorderBrush="{TemplateBinding BorderBrush}"
 BorderThickness="{TemplateBinding BorderThickness}">
 <Grid>
 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="*"/>
 <ColumnDefinition Width="Auto"/>
 </Grid.ColumnDefinitions>

 <TextBox Grid.Column="0" x:Name="PART_TextBox"
 VerticalContentAlignment="Center"
 BorderThickness="0"
 Background="Transparent"/>

 <StackPanel Grid.Column="1" Orientation="Vertical">
 <Button x:Name="PART_UpButton" Content="▲" Width="20"/>
 <Button x:Name="PART_DownButton" Content="▼" Width="20"/>
 </StackPanel>
 </Grid>
 </Border>
 </ControlTemplate>
 </Setter.Value>
 </Setter>
 </Style>
</ResourceDictionary>

使用

1
2
3
4


<Window xmlns:ctrl="clr-namespace:MyApp.Controls">
 <ctrl:NumericUpDown Value="50" Minimum="0" Maximum="100" SmallChange="5"
 ValueChanged="NumericUpDown_ValueChanged"/>
</Window>

3.5 关键设计点

TemplatePart 与 PART_ 命名约定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


TemplatePart attribute：
 - 声明控件"期望"模板里有哪些命名元素
 - 命名约定：PART_ 开头
 - 类型约束（如 PART_TextBox 必须是 TextBox）

作用：
 - 给设计器/Blend 提示（哪些是"必需"元素）
 - 给写模板的人提示（哪些名字必须有）
 - 是"控件与模板"的契约

代码侧：
 GetTemplateChild("PART_TextBox") 拿元素
 OnApplyTemplate 时调用（不是构造函数！）

OnApplyTemplate

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


OnApplyTemplate 的角色：
 - 模板应用时被调用
 - 此时 GetTemplateChild 才能拿到命名元素
 - 类似"模板就绪"事件

 必须重写：
 1. 拿新元素
 2. 取消旧元素的订阅（避免泄漏）
 3. 订阅新元素事件
 4. 初始化新元素状态（如设 TextBox.Text）

默认模板可替换

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<!-- 用户可以替换默认模板 -->
<ctrl:NumericUpDown>
 <ctrl:NumericUpDown.Template>
 <ControlTemplate TargetType="{x:Type ctrl:NumericUpDown}">
 <!-- 完全自定义外观，但必须保留 PART_ 命名元素 -->
 <Grid>
 <RepeatButton x:Name="PART_UpButton" Content="↑"/>
 <TextBox x:Name="PART_TextBox"/>
 <RepeatButton x:Name="PART_DownButton" Content="↓"/>
 </Grid>
 </ControlTemplate>
 </ctrl:NumericUpDown.Template>
</ctrl:NumericUpDown>

1
2
3
4
5


关键观察：
 - 控件代码完全不知道"模板长什么样"
 - 只依赖 PART_xxx 契约
 - 用户可以彻底换肤
 - 这就是 CustomControl 的核心价值

四、重写 OnRender

最自由也最重的方案。

4.1 适用场景

1
2
3
4
5
6
7
8
9


重写 FrameworkElement.OnRender：
 - 自定义绘图（折线图、雷达图）
 - 大量重复元素（每帧渲染几千条线）
 - 性能极致（绕开视觉树）

代价：
 - 没有 XAML
 - 没有 ControlTemplate（不可换肤）
 - 自己处理布局、命中测试

4.2 示例：折线图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


public class LineChart : FrameworkElement
{
 public static readonly DependencyProperty PointsProperty =
 DependencyProperty.Register(
 nameof(Points),
 typeof(PointCollection),
 typeof(LineChart),
 new FrameworkPropertyMetadata(
 null,
 FrameworkPropertyMetadataOptions.AffectsRender));

 public PointCollection Points
 {
 get => (PointCollection)GetValue(PointsProperty);
 set => SetValue(PointsProperty, value);
 }

 public Brush LineBrush { get; set; } = Brushes.DodgerBlue;
 public double LineThickness { get; set; } = 2;

 protected override void OnRender(DrawingContext dc)
 {
 base.OnRender(dc);

 if (Points == null || Points.Count < 2) return;

 var geometry = new StreamGeometry();
 using (var ctx = geometry.Open())
 {
 ctx.BeginFigure(Points[0], false, false);
 for (int i = 1; i < Points.Count; i++)
 ctx.LineTo(Points[i], true, false);
 }

 var pen = new Pen(LineBrush, LineThickness);
 dc.DrawGeometry(null, pen, geometry);
 }
}

1

<local:LineChart Points="{Binding ChartPoints}" LineBrush="OrangeRed" LineThickness="3"/>

4.3 DrawingContext

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


DrawingContext 的方法：
 DrawLine(pen, point1, point2)
 DrawRectangle(brush, pen, rect)
 DrawRoundedRectangle(...)
 DrawEllipse(brush, pen, center, radiusX, radiusY)
 DrawGeometry(brush, pen, geometry)
 DrawText(formattedText, origin)
 DrawImage(imageSource, rect)
 PushTransform(transform) / Pop()
 PushClip(geom) / Pop()
 PushOpacity(opacity) / Pop()

 类似 GDI+ 的 Graphics 对象
 但不是立即渲染（WPF 内部收集指令，统一提交）

五、自定义依赖属性

CustomControl 离不开依赖属性。第 2 篇已详细讲过，这里聚焦"控件场景"。

5.1 控件属性的元数据

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public static readonly DependencyProperty ValueProperty =
 DependencyProperty.Register(
 nameof(Value), typeof(int), typeof(NumericUpDown),
 new FrameworkPropertyMetadata(
 0,
 OnValueChanged, // 值变化回调
 CoerceValue), // 强制回调
 ValidateValue);

// 关键元数据选项（FrameworkPropertyMetadataOptions）
FrameworkPropertyMetadataOptions.AffectsMeasure // 改了要重新 Measure
FrameworkPropertyMetadataOptions.AffectsArrange // 改了要重新 Arrange
FrameworkPropertyMetadataOptions.AffectsRender // 改了要重新渲染
FrameworkPropertyMetadataOptions.BindsTwoWayByDefault // 默认双向绑定
FrameworkPropertyMetadataOptions.Inherits // 可继承

5.2 路由事件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


public static readonly RoutedEvent ValueChangedEvent =
 EventManager.RegisterRoutedEvent(
 nameof(ValueChanged),
 RoutingStrategy.Bubbling,
 typeof(RoutedPropertyChangedEventHandler<int>),
 typeof(NumericUpDown));

public event RoutedPropertyChangedEventHandler<int> ValueChanged
{
 add => AddHandler(ValueChangedEvent, value);
 remove => RemoveHandler(ValueChangedEvent, value);
}

// 触发
private static void OnValueChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
 var control = (NumericUpDown)d;
 control.RaiseEvent(new RoutedPropertyChangedEventArgs<int>(
 (int)e.OldValue, (int)e.NewValue, ValueChangedEvent));
}

六、控件库项目结构

6.1 多项目组织

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


MyCompany.MyApp/
├── MyCompany.MyApp.csproj ← 主应用
├── MyCompany.MyApp.Controls/ ← 控件库
│ ├── MyCompany.MyApp.Controls.csproj
│ ├── Themes/
│ │ └── Generic.xaml
│ ├── NumericUpDown.cs
│ ├── CircularProgress.cs
│ └── ...
└── MyCompany.MyApp.Services/ ← 服务库

6.2 csproj 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<!-- 控件库 csproj -->
<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net8.0-windows</TargetFramework>
 <UseWPF>true</UseWPF>
 <AssemblyInfo>true</AssemblyInfo>
 </PropertyGroup>

 <!-- ThemeInfo 必须有（让 WPF 找到 Generic.xaml） -->
 <ItemGroup>
 <AssemblyAttribute Include="System.Windows.ThemeInfoAttribute">
 <_Parameter1>System.Windows.ResourceDictionaryLocation.None</_Parameter1>
 <_Parameter2>System.Windows.ResourceDictionaryLocation.SourceAssembly</_Parameter2>
 </AssemblyAttribute>
 </ItemGroup>
</Project>

6.3 Generic.xaml 注意事项

1
2
3
4
5
6
7
8
9


Generic.xaml 必须满足：
 - 路径：项目根 / Themes / Generic.xaml
 - Build Action：Page（默认）
 - 包含程序集的 ThemeInfo（自动或手动）

调试技巧：
 - Generic.xaml 改了不生效 → 重新生成（不是热重载）
 - 默认模板找不到 → 检查 DefaultStyleKeyProperty.OverrideMetadata
 - PART_ 拿不到 → 检查模板里的 x:Name 拼写

七、设计时支持

让设计器（VS/Blend）友好。

7.1 Category / Description

1
2
3


[Category("Common")]
[Description("当前数值")]
public int Value { ... }

设计器 Properties 面板会分类显示。

7.2 ToolboxBitmap

1
2


[ToolboxBitmap(typeof(NumericUpDown), "Resources.numericupdown.ico")]
public class NumericUpDown : Control { ... }

工具箱里显示自定义图标。

7.3 DefaultEvent

1
2


[DefaultEvent("ValueChanged")]
public class NumericUpDown : Control { ... }

设计器双击控件自动生成 ValueChanged 事件处理器。

八、实战：完整 NumericUpDown（精简版）

8.1 控件类（最终版）

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106


[TemplatePart(Name = "PART_UpButton", Type = typeof(ButtonBase))]
[TemplatePart(Name = "PART_DownButton", Type = typeof(ButtonBase))]
[TemplatePart(Name = "PART_TextBox", Type = typeof(TextBox))]
[DefaultEvent("ValueChanged")]
public class NumericUpDown : Control
{
 static NumericUpDown()
 {
 DefaultStyleKeyProperty.OverrideMetadata(
 typeof(NumericUpDown),
 new FrameworkPropertyMetadata(typeof(NumericUpDown)));
 }

 #region Value
 public static readonly DependencyProperty ValueProperty =
 DependencyProperty.Register(nameof(Value), typeof(int), typeof(NumericUpDown),
 new FrameworkPropertyMetadata(0,
 FrameworkPropertyMetadataOptions.BindsTwoWayByDefault,
 OnValueChanged, CoerceValue),
 ValidateValue);

 public int Value
 {
 get => (int)GetValue(ValueProperty);
 set => SetValue(ValueProperty, value);
 }

 private static void OnValueChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
 {
 var c = (NumericUpDown)d;
 if (c._textBox != null) c._textBox.Text = e.NewValue.ToString();
 c.RaiseEvent(new RoutedPropertyChangedEventArgs<int>(
 (int)e.OldValue, (int)e.NewValue, ValueChangedEvent));
 }

 private static object CoerceValue(DependencyObject d, object v)
 {
 var c = (NumericUpDown)d;
 var value = (int)v;
 return value < c.Minimum ? c.Minimum
 : value > c.Maximum ? c.Maximum
 : value;
 }

 private static bool ValidateValue(object v) => v is int;
 #endregion

 #region Minimum / Maximum / SmallChange
 public int Minimum { get => (int)GetValue(MinimumProperty); set => SetValue(MinimumProperty, value); }
 public static readonly DependencyProperty MinimumProperty =
 DependencyProperty.Register(nameof(Minimum), typeof(int), typeof(NumericUpDown),
 new FrameworkPropertyMetadata(0, (d, e) => ((NumericUpDown)d).CoerceValue(ValueProperty)));

 public int Maximum { get => (int)GetValue(MaximumProperty); set => SetValue(MaximumProperty, value); }
 public static readonly DependencyProperty MaximumProperty =
 DependencyProperty.Register(nameof(Maximum), typeof(int), typeof(NumericUpDown),
 new FrameworkPropertyMetadata(100, (d, e) => ((NumericUpDown)d).CoerceValue(ValueProperty)));

 public int SmallChange { get => (int)GetValue(SmallChangeProperty); set => SetValue(SmallChangeProperty, value); }
 public static readonly DependencyProperty SmallChangeProperty =
 DependencyProperty.Register(nameof(SmallChange), typeof(int), typeof(NumericUpDown), new PropertyMetadata(1));
 #endregion

 #region ValueChanged event
 public static readonly RoutedEvent ValueChangedEvent =
 EventManager.RegisterRoutedEvent(nameof(ValueChanged), RoutingStrategy.Bubbling,
 typeof(RoutedPropertyChangedEventHandler<int>), typeof(NumericUpDown));

 public event RoutedPropertyChangedEventHandler<int> ValueChanged
 {
 add => AddHandler(ValueChangedEvent, value);
 remove => RemoveHandler(ValueChangedEvent, value);
 }
 #endregion

 private ButtonBase? _upButton;
 private ButtonBase? _downButton;
 private TextBox? _textBox;

 public override void OnApplyTemplate()
 {
 base.OnApplyTemplate();

 if (_upButton != null) _upButton.Click -= (_, _) => Value += SmallChange;
 if (_downButton != null) _downButton.Click -= (_, _) => Value -= SmallChange;
 if (_textBox != null) _textBox.TextChanged -= OnTextBoxTextChanged;

 _upButton = GetTemplateChild("PART_UpButton") as ButtonBase;
 _downButton = GetTemplateChild("PART_DownButton") as ButtonBase;
 _textBox = GetTemplateChild("PART_TextBox") as TextBox;

 if (_upButton != null) _upButton.Click += (_, _) => Value += SmallChange;
 if (_downButton != null) _downButton.Click += (_, _) => Value -= SmallChange;
 if (_textBox != null)
 {
 _textBox.Text = Value.ToString();
 _textBox.TextChanged += OnTextBoxTextChanged;
 }
 }

 private void OnTextBoxTextChanged(object sender, TextChangedEventArgs e)
 {
 if (int.TryParse(_textBox!.Text, out int result))
 Value = result;
 }
}

8.2 Generic.xaml（见第 3.4 节）

8.3 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


✅ DefaultStyleKeyProperty.OverrideMetadata
✅ 依赖属性注册（含 Coerce + Validate + PropertyChanged）
✅ FrameworkPropertyMetadataOptions.BindsTwoWayByDefault
✅ 路由事件注册 + RaiseEvent
✅ TemplatePart attribute 声明契约
✅ OnApplyTemplate + GetTemplateChild
✅ 设计器特性（DefaultEvent）

观察：
 - 控件类完全没写"长什么样"
 - Generic.xaml 描述外观
 - 用户可彻底换肤
 - Value 变化触发路由事件，可被父级监听

九、常见陷阱

9.1 DefaultStyleKey 没设

1
2
3
4
5


// ❌ 忘了 OverrideMetadata
public class MyControl : Control { }

// 后果：WPF 用 Control 的默认样式（空白）
// 控件不显示任何东西

9.2 Generic.xaml 路径错

1
2
3


❌ Themes/generic.xaml（小写）
❌ theme/Generic.xaml
✅ Themes/Generic.xaml（大小写敏感）

9.3 GetTemplateChild 时机错

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// ❌ 在构造函数调
public MyControl()
{
 var btn = GetTemplateChild("PART_UpButton"); // 返回 null
 // 此时模板还没应用
}

// ✅ 在 OnApplyTemplate
public override void OnApplyTemplate()
{
 base.OnApplyTemplate();
 var btn = GetTemplateChild("PART_UpButton");
}

9.4 事件订阅不取消

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// ❌ 旧元素订阅没取消
public override void OnApplyTemplate()
{
 var newBtn = GetTemplateChild("PART_UpButton") as ButtonBase;
 newBtn.Click += ClickHandler;
 // 如果之前已经有 _upButton，旧的事件没取消 → 重复触发
}

// ✅ 先取消，再订阅
if (_upButton != null) _upButton.Click -= ClickHandler;
_upButton = GetTemplateChild("PART_UpButton") as ButtonBase;
if (_upButton != null) _upButton.Click += ClickHandler;

9.5 CLR 包装器里写逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// ❌（详见第 2 篇）
public int Value
{
 get => (int)GetValue(ValueProperty);
 set
 {
 SetValue(ValueProperty, value);
 UpdateTextBox(); // ❌ 不会执行（绑定/动画绕过 wrapper）
 }
}

// ✅ 把副作用放 PropertyChangedCallback

十、与 ASP.NET Core / 前端的对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


ASP.NET Core WPF CustomControl
──────────────────────────────────────────────
Tag Helper MarkupExtension
Razor Component UserControl
Partial View UserControl
Custom Tag Helper CustomControl
_Layout.cshtml Generic.xaml（默认模板）

前端 React/Vue WPF
──────────────────────────────────────────────
Component UserControl / CustomControl
Props Dependency Property
Slot (children) ContentPresenter
Custom Hook 附加属性
Style Library Themes/Generic.xaml

后端视角：
 CustomControl = "可换皮的控件"
 TemplatePart 契约 = "接口约定"（PART_xxx 是 method 名）
 Generic.xaml = "默认实现"

十一、小结

本文深入 WPF 的自定义控件：

三条路线（UserControl / CustomControl / OnRender）的选型
UserControl：组合现有控件，XAML + code-behind
CustomControl：继承 Control + Generic.xaml + TemplatePart
Themes/Generic.xaml 的约定与角色
TemplatePart 与 PART_ 命名约定
OnApplyTemplate + GetTemplateChild 的契约
重写 OnRender（DrawingContext 绘图）
自定义依赖属性 + 路由事件
控件库项目结构
设计时支持（DefaultEvent / Category / ToolboxBitmap）
实战：完整 NumericUpDown

1
2
3
4


记住三句话：
 1. 视图复用 UserControl，控件库用 CustomControl，绘图用 OnRender
 2. CustomControl 的核心契约是 PART_xxx——控件代码只依赖名字，外观可彻底换
 3. OnApplyTemplate 是"模板就绪"事件——所有 GetTemplateChild 必须在这里调

下一篇是系列收尾——性能与发布：Freezable、虚拟化、绑定优化、self-contained、Trimming、MSIX 打包。

WPF 学习笔记（十）：动画与图形——保留模式渲染

Mon, 25 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

WPF 的图形动画系统是它和 WinForms 最大的代际差异。WinForms 要动画，你得自己写定时器、自己算每帧位置、自己 Invalidate 触发重绘。WPF 的动画是声明式的——你描述"从 A 到 B 用时 1 秒"，框架替你跑每一帧。

本篇要把 WPF 的渲染范式、动画系统、图形原语讲清楚。这是后端工程师相对陌生的领域，但理解了原理就不再觉得"魔法"。

本文要回答：

WPF 为什么不会因为动画卡 UI？动画结束后属性值为什么改不回去了？保留模式和立即模式到底差在哪？

一、保留模式 vs 立即模式

1.1 两种渲染范式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


立即模式（Immediate Mode）：
 每帧由你重新画
 → 你写代码：每帧 OnRender(e) → e.Graphics.DrawXXX
 → 不画就消失
 → 例：WinForms、DirectX、OpenGL、ImGui

保留模式（Retained Mode）：
 你描述一棵"视觉树"，框架渲染
 → 视觉树常驻内存
 → 你改属性，框架自动重绘
 → 例：WPF、DOM/CSS、HTML

1.2 对比

维度	立即模式	保留模式
状态	你管（每帧重画）	框架管（树常驻）
API 风格	DrawXXX() 命令	设属性
性能	极简场景快	复杂场景友好（GPU 加速）
动画	你写定时器	声明式
适用	游戏、绘图软件	业务 UI

1
2
3
4
5
6


后端类比：
 立即模式 ≈ 每次请求重渲染（无缓存）
 保留模式 ≈ 状态机 + 增量更新（带缓存）

WPF 的视觉树 = 一棵"持久化的渲染结构"
 改属性 → 标记 dirty → Composition 线程提交 GPU → 渲染

二、WPF 多线程渲染架构

WPF 的渲染其实跨多个线程。

2.1 三类线程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


UI 线程（Main Thread）：
 - 处理用户输入、路由事件
 - 维护视觉树（你在 XAML 写的所有东西）
 - 跑 Dispatcher 消息循环
 - 计算 Measure/Arrange

Composition 线程：
 - 把视觉树变化"打包"提交给 GPU
 - 跑动画（部分）
 - 独立于 UI 线程
 - 这就是为什么动画不卡 UI

Render 线程（GPU 线程）：
 - 实际向 GPU 发命令
 - 由 milcore.dll 管理

2.2 数据流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


UI 线程
 ↓ 改属性（DP）
 ↓ 标记 dirty
Composition 线程
 ↓ 收集变化
 ↓ 计算动画帧
 ↓ 打包到 GPU 命令
Render 线程（GPU）
 ↓ 渲染
屏幕

2.3 为什么动画不卡 UI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


传统想象：
 动画 = 每秒 60 帧 × UI 线程跑 → UI 卡死

WPF 实际：
 动画声明 → Composition 线程接管
 → 每帧在 Composition 线程算
 → 不占 UI 线程
 → UI 线程照常响应输入

但有限制：
 → 涉及布局（Measure/Arrange）的动画还是要 UI 线程
 → 只渲染的动画（Opacity、RenderTransform）才能 Composition 跑
 → 所以"动画属性"选 Opacity/Transform 性能好

三、图形原语

3.1 Shape（基础形状）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<Canvas>
 <Rectangle Canvas.Left="10" Canvas.Top="10" Width="100" Height="60"
 Fill="DodgerBlue" Stroke="Black"/>
 <Ellipse Canvas.Left="120" Canvas.Top="10" Width="60" Height="60"
 Fill="OrangeRed"/>
 <Line Canvas.Left="10" Canvas.Top="80" X1="0" Y1="0" X2="200" Y2="0"
 Stroke="Black" StrokeThickness="2"/>
 <Polyline Points="10,100 50,140 90,100 130,140" Stroke="Green" StrokeThickness="2"/>
 <Polygon Points="200,100 240,140 280,100 260,60 220,60" Fill="Purple"/>
</Canvas>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


Shape 系列：
 - Rectangle：矩形
 - Ellipse：椭圆
 - Line：线段
 - Polyline：折线
 - Polygon：多边形
 - Path：任意路径（最强，用 Geometry）

特点：
 - 都是 FrameworkElement（参与布局）
 - 自带 Stroke / Fill 属性
 - 相对较重（适合少量元素）

3.2 Geometry（路径几何）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<Path Stroke="Black" StrokeThickness="2" Fill="LightBlue">
 <Path.Data>
 <PathGeometry>
 <PathFigure StartPoint="10,10" IsClosed="True">
 <LineSegment Point="100,10"/>
 <LineSegment Point="50,80"/>
 </PathFigure>
 </PathGeometry>
 </Path.Data>
</Path>

<!-- Mini-language（路径字符串） -->
<Path Stroke="Red" Data="M 10,10 L 100,10 L 50,80 Z"/>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Geometry vs Shape：
 - Geometry：纯几何描述（不带渲染）
 - Shape：UI 元素（含 Geometry + 渲染）

 Geometry 轻，可以多个 Path 共享
 Shape 重，但简单易用

后端类比：
 Geometry ≈ DTO（数据描述）
 Shape ≈ View Model + View（数据 + 渲染）

3.3 Brush（画刷）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


<!-- 纯色 -->
<Rectangle Fill="Red"/>
<Rectangle Fill="#FFFF0000"/>

<!-- 渐变 -->
<Rectangle>
 <Rectangle.Fill>
 <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
 <GradientStop Offset="0" Color="Yellow"/>
 <GradientStop Offset="1" Color="Red"/>
 </LinearGradientBrush>
 </Rectangle.Fill>
</Rectangle>

<!-- 径向渐变 -->
<Ellipse>
 <Ellipse.Fill>
 <RadialGradientBrush>
 <GradientStop Offset="0" Color="White"/>
 <GradientStop Offset="1" Color="Black"/>
 </RadialGradientBrush>
 </Ellipse.Fill>
</Ellipse>

<!-- 图片 -->
<Rectangle>
 <Rectangle.Fill>
 <ImageBrush ImageSource="background.jpg"/>
 </Rectangle.Fill>
</Rectangle>

<!-- 视觉刷（用任意 UI 元素作为画刷） -->
<Rectangle>
 <Rectangle.Fill>
 <VisualBrush Visual="{Binding ElementName=sourceElement}"/>
 </Rectangle.Fill>
</Rectangle>

3.4 Transform（变换）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


<Button Content="Rotate" RenderTransformOrigin="0.5,0.5">
 <Button.RenderTransform>
 <RotateTransform Angle="45"/>
 </Button.RenderTransform>
</Button>

<Button Content="Scale">
 <Button.RenderTransform>
 <ScaleTransform ScaleX="1.5" ScaleY="1.5"/>
 </Button.RenderTransform>
</Button>

<!-- 复合变换 -->
<Button Content="Combined">
 <Button.RenderTransform>
 <TransformGroup>
 <ScaleTransform ScaleX="1.5" ScaleY="1.5"/>
 <RotateTransform Angle="15"/>
 <TranslateTransform X="10" Y="20"/>
 </TransformGroup>
 </Button.RenderTransform>
</Button>

1
2
3
4
5


RenderTransform vs LayoutTransform（详见第 4 篇）：
 RenderTransform：渲染时变换，不影响布局
 LayoutTransform：变换后重新参与布局

动画优先用 RenderTransform（性能好）

四、动画系统

4.1 声明式动画

1
2
3


<!-- 1 秒内，Opacity 从 1 → 0 -->
<DoubleAnimation Storyboard.TargetProperty="Opacity"
 From="1" To="0" Duration="0:0:1"/>

1
2
3
4
5
6
7
8


动画的本质：
 你描述 From / To / Duration
 框架每帧算当前值（基于时间）
 把当前值赋给 TargetProperty

后端类比：
 动画 ≈ 定时器 + 插值函数
 框架替你管"每帧"

4.2 Timeline 与 AnimationTimeline

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Timeline（时间线）：
 - 抽象基类
 - 有 Duration、BeginTime、RepeatBehavior
 - 表示"一段时间内发生的事"

AnimationTimeline（动画时间线）：
 - Timeline 的派生
 - 知道怎么算"当前帧的值"
 - 例：DoubleAnimation、ColorAnimation

Storyboard（故事板）：
 - 多个 AnimationTimeline 的容器
 - 统一管理 Begin/Stop/Pause
 - 触发动画的标准方式

4.3 三种基本动画类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- DoubleAnimation（数字属性） -->
<DoubleAnimation Storyboard.TargetProperty="Opacity"
 From="1" To="0" Duration="0:0:1"/>

<!-- ColorAnimation（颜色） -->
<ColorAnimation Storyboard.TargetProperty="(Background).(SolidColorBrush.Color)"
 From="Red" To="Blue" Duration="0:0:1"/>

<!-- PointAnimation（点） -->
<PointAnimation Storyboard.TargetProperty="(PathGeometry.Figures)[0].StartPoint"
 From="10,10" To="100,100" Duration="0:0:1"/>

1
2
3
4
5
6


为什么是这三种？
 - double：最常见（位置、大小、透明度）
 - Color：颜色变化
 - Point：几何点变化

其他类型（bool、string 等）不能动画（用 ObjectAnimationUsingKeyFrames 替代）

五、Storyboard 触发动画

5.1 EventTrigger 触发

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


<Button Content="Hover Me">
 <Button.Triggers>
 <EventTrigger RoutedEvent="Button.MouseEnter">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="Opacity"
 To="0.7" Duration="0:0:0.3"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 <EventTrigger RoutedEvent="Button.MouseLeave">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="Opacity"
 To="1.0" Duration="0:0:0.3"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 </Button.Triggers>
</Button>

5.2 Style 里的 EventTrigger

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


<Style TargetType="Button">
 <Style.Triggers>
 <EventTrigger RoutedEvent="Button.MouseEnter">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="FontSize"
 To="20" Duration="0:0:0.2"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 <EventTrigger RoutedEvent="Button.MouseLeave">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="FontSize"
 To="14" Duration="0:0:0.2"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 </Style.Triggers>
</Style>

5.3 代码触发

1
2
3


// 在 code-behind
var storyboard = (Storyboard)FindResource("MyAnimation");
storyboard.Begin(myButton);

六、依赖属性动画"占用"机制

这是 WPF 动画最反直觉的部分。

6.1 现象

1
2
3
4
5
6
7
8
9


// 设置 Width
myButton.Width = 100;

// 跑动画到 200
var animation = new DoubleAnimation(200, TimeSpan.FromSeconds(1));
myButton.BeginAnimation(Button.WidthProperty, animation);

// 动画结束后
myButton.Width = 50; // ⚠️ 没效果！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


原因：
 动画结束后，WidthProperty 的"动画值"占据优先级 2（详见第 2 篇）
 本地值（你直接赋值的）优先级 3...等等，这个反过来了

 实际：
 Priority 2: Animation
 Priority 3: Local Value

 → 动画的值 > 你的本地值
 → 你的赋值"被动画压住"

FillBehavior：
 HoldEnd（默认）：动画结束后保持最后值（继续占用属性）
 Stop：动画结束后释放，回到本地值

6.2 解决方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 方法 1：FillBehavior = Stop
var animation = new DoubleAnimation
{
 To = 200,
 Duration = TimeSpan.FromSeconds(1),
 FillBehavior = FillBehavior.Stop // ← 释放占用
};
myButton.BeginAnimation(Button.WidthProperty, animation);
// 动画结束后 Width 回到 100（之前的本地值）

// 方法 2：手动清除动画
myButton.BeginAnimation(Button.WidthProperty, null);
myButton.Width = 50; // ✅ 生效

6.3 占用机制总结

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


动画运行时：
 property = animation.CurrentValue
 优先级最高（仅次于 Coerce）

动画停止（HoldEnd）：
 property = animation.To
 继续占用

动画停止（Stop）：
 property = local value（你之前赋的）
 释放占用

清除动画：
 BeginAnimation(dp, null)
 完全清除占用

七、缓动函数 EasingFunction

线性动画生硬，缓动函数让动画自然。

7.1 内置缓动

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


<!-- 线性（默认） -->
<DoubleAnimation Storyboard.TargetProperty="X"
 From="0" To="100" Duration="0:0:1"/>

<!-- 二次方缓入缓出 -->
<DoubleAnimation Storyboard.TargetProperty="X"
 From="0" To="100" Duration="0:0:1">
 <DoubleAnimation.EasingFunction>
 <QuadraticEase EasingMode="EaseInOut"/>
 </DoubleAnimation.EasingFunction>
</DoubleAnimation>

<!-- 弹性 -->
<DoubleAnimation Storyboard.TargetProperty="X"
 From="0" To="100" Duration="0:0:1">
 <DoubleAnimation.EasingFunction>
 <ElasticEase Oscillations="3" Springiness="5"/>
 </DoubleAnimation.EasingFunction>
</DoubleAnimation>

<!-- 三次贝塞尔（最灵活） -->
<DoubleAnimation Storyboard.TargetProperty="X"
 From="0" To="100" Duration="0:0:1">
 <DoubleAnimation.EasingFunction>
 <CubicEase EasingMode="EaseOut"/>
 </DoubleAnimation.EasingFunction>
</DoubleAnimation>

7.2 缓动类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


EasingMode：
 EaseIn：开始慢，后面快
 EaseOut：开始快，后面慢（推荐，UI 动画最自然）
 EaseInOut：两端慢中间快

内置缓动：
 Linear、Quadratic、Cubic、Quartic、Quintic
 Sine、Circle、Elastic、Back、Bounce
 Exponential、Power
 CubicBezier（自定义贝塞尔）

设计原则：
 - UI 进入动画：EaseOut
 - UI 退出动画：EaseIn
 - 状态切换：EaseInOut

7.3 关键帧动画

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<DoubleAnimationUsingKeyFrames Storyboard.TargetProperty="X">
 <!-- 线性关键帧 -->
 <LinearDoubleKeyFrame KeyTime="0:0:0" Value="0"/>
 <LinearDoubleKeyFrame KeyTime="0:0:0.5" Value="50"/>
 <LinearDoubleKeyFrame KeyTime="0:0:1" Value="100"/>

 <!-- 缓和关键帧 -->
 <EasingDoubleKeyFrame KeyTime="0:0:1.5" Value="120">
 <EasingDoubleKeyFrame.EasingFunction>
 <CubicEase/>
 </EasingDoubleKeyFrame.EasingFunction>
 </EasingDoubleKeyFrame>

 <!-- 离散（瞬间跳变） -->
 <DiscreteDoubleKeyFrame KeyTime="0:0:2" Value="200"/>
</DoubleAnimationUsingKeyFrames>

八、动画实战：加载动画 + 进度环

8.1 旋转加载圈

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


<!-- XAML -->
<Window.Resources>
 <Style TargetType="ProgressBar" x:Key="CircularProgress">
 <Setter Property="Template">
 <Setter.Value>
 <ControlTemplate TargetType="ProgressBar">
 <Grid>
 <Path Name="PART_Track" Stroke="LightGray" StrokeThickness="6"
 Data="M 50,10 A 40,40 0 1 1 49.99,10" Fill="Transparent"/>
 <Path Name="PART_Indicator" Stroke="DodgerBlue" StrokeThickness="6"
 StrokeStartLineCap="Round" StrokeEndLineCap="Round"
 Data="M 50,10 A 40,40 0 1 1 49.99,10" Fill="Transparent"/>
 </Grid>
 </ControlTemplate>
 </Setter.Value>
 </Setter>
 </Style>
</Window.Resources>

<!-- 实际加载旋转动画 -->
<Grid Width="60" Height="60">
 <Border Width="40" Height="40" BorderBrush="DodgerBlue" BorderThickness="4"
 CornerRadius="20" RenderTransformOrigin="0.5,0.5">
 <Border.RenderTransform>
 <RotateTransform x:Name="spinRotation"/>
 </Border.RenderTransform>
 </Border>

 <Border.Triggers>
 <EventTrigger RoutedEvent="Loaded">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetName="spinRotation"
 Storyboard.TargetProperty="Angle"
 From="0" To="360" Duration="0:0:1"
 RepeatBehavior="Forever"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 </Border.Triggers>
</Grid>

8.2 平滑过渡的进度环

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


<Canvas Width="100" Height="100">
 <!-- 背景圆 -->
 <Path Stroke="LightGray" StrokeThickness="6"
 Data="M 50,10 A 40,40 0 1 1 49.99,10"
 Fill="Transparent"/>

 <!-- 进度圆弧（用 StrokeDashOffset 控制长度） -->
 <Path x:Name="progressArc" Stroke="DodgerBlue" StrokeThickness="6"
 StrokeStartLineCap="Round" StrokeEndLineCap="Round"
 Data="M 50,10 A 40,40 0 1 1 49.99,10"
 Fill="Transparent"
 StrokeDashArray="251.32 251.32"
 StrokeDashOffset="251.32">
 <Path.RenderTransform>
 <RotateTransform x:Name="arcRotate" CenterX="50" CenterY="50"/>
 </Path.RenderTransform>
 </Path>

 <Path.Triggers>
 <EventTrigger RoutedEvent="Loaded">
 <BeginStoryboard>
 <Storyboard>
 <!-- 进度 0 → 75%（offset 从 251.32 → 251.32*0.25=62.83） -->
 <DoubleAnimation Storyboard.TargetName="progressArc"
 Storyboard.TargetProperty="StrokeDashOffset"
 From="251.32" To="62.83"
 Duration="0:0:1"
 EasingFunction="{...}"/>
 <!-- 持续旋转（让进度环转起来，更动感） -->
 <DoubleAnimation Storyboard.TargetName="arcRotate"
 Storyboard.TargetProperty="Angle"
 From="0" To="360" Duration="0:0:2"
 RepeatBehavior="Forever"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 </Path.Triggers>
</Canvas>

8.3 用 Trigger 实现 Material 风格按钮悬停

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


<Style TargetType="Button">
 <Setter Property="Background" Value="#2196F3"/>
 <Setter Property="Foreground" Value="White"/>
 <Setter Property="Padding" Value="24,12"/>
 <Setter Property="RenderTransformOrigin" Value="0.5,0.5"/>
 <Setter Property="RenderTransform">
 <Setter.Value>
 <ScaleTransform ScaleX="1" ScaleY="1"/>
 </Setter.Value>
 </Setter>

 <Style.Triggers>
 <EventTrigger RoutedEvent="MouseEnter">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleX)"
 To="1.05" Duration="0:0:0.2">
 <DoubleAnimation.EasingFunction>
 <CubicEase EasingMode="EaseOut"/>
 </DoubleAnimation.EasingFunction>
 </DoubleAnimation>
 <DoubleAnimation Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleY)"
 To="1.05" Duration="0:0:0.2"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 <EventTrigger RoutedEvent="MouseLeave">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleX)"
 To="1.0" Duration="0:0:0.2"/>
 <DoubleAnimation Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleY)"
 To="1.0" Duration="0:0:0.2"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 </Style.Triggers>
</Style>

8.4 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


✅ DoubleAnimation + Storyboard
✅ EventTrigger 触发
✅ RepeatBehavior="Forever"
✅ StrokeDashArray + StrokeDashOffset（圆弧进度技巧）
✅ EasingFunction（CubicEase）
✅ RenderTransform（性能友好的动画属性）

观察：
 - 动画期间 UI 仍然响应（Composition 线程跑）
 - 加载圈"永不结束"用 RepeatBehavior="Forever"
 - Material 按钮的 1.05 缩放非常微妙但舒服

九、VisualStateManager 与动画

CustomControl 推荐用 VSM 触发动画（详见第 8 篇）。

9.1 VSM 与动画

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


<ControlTemplate TargetType="Button">
 <Grid>
 <Border x:Name="root" Background="DodgerBlue"/>
 <ContentPresenter HorizontalAlignment="Center" VerticalAlignment="Center"/>

 <VisualStateManager.VisualStateGroups>
 <VisualStateGroup x:Name="CommonStates">
 <VisualState x:Name="Normal"/>
 <VisualState x:Name="MouseOver">
 <Storyboard>
 <ColorAnimation Storyboard.TargetName="root"
 Storyboard.TargetProperty="(Border.Background).(SolidColorBrush.Color)"
 To="LightBlue" Duration="0:0:0.2"/>
 </Storyboard>
 </VisualState>
 <VisualState x:Name="Pressed">
 <Storyboard>
 <DoubleAnimation Storyboard.TargetName="root"
 Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleX)"
 To="0.95" Duration="0:0:0.1"/>
 <DoubleAnimation Storyboard.TargetName="root"
 Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleY)"
 To="0.95" Duration="0:0:0.1"/>
 </Storyboard>
 </VisualState>
 </VisualStateGroup>
 </VisualStateManager.VisualStateGroups>
 </Grid>
</ControlTemplate>

1
2
3
4


VSM 的优势：
 - 状态机抽象（Normal / MouseOver / Pressed）
 - 状态间自动过渡动画
 - 微软推荐 CustomControl 用 VSM

十、性能优化

10.1 选对动画属性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


✅ 性能好（Composition 线程跑）：
 Opacity
 RenderTransform（Translate、Scale、Rotate）
 这些属性不影响布局

❌ 性能差（UI 线程跑）：
 Width / Height（触发 layout）
 Margin / Padding
 Canvas.Left / Top

实践：
 动画尽量用 RenderTransform 而不是 Width
 例：缩放用 ScaleTransform 而不是改 Width

10.2 RenderOptions

1
2
3
4


<!-- 缓存渲染（适合复杂静态元素） -->
<Path RenderOptions.CachingHint="Cache"
 RenderOptions.CacheInvalidationThresholdMaximum="2"
 RenderOptions.CacheInvalidationThresholdMinimum="0.5"/>

1
2


// 强制软件渲染（GPU 渲染反而慢的场景）
RenderOptions.ProcessRenderMode = RenderMode.SoftwareOnly;

10.3 Freeze Brush

1
2
3
4
5
6
7
8
9


// ❌ Brush 不变也每帧检查
LinearGradientBrush brush = new LinearGradientBrush();
brush.GradientStops.Add(new GradientStop(Colors.Red, 0));
brush.GradientStops.Add(new GradientStop(Colors.Blue, 1));
button.Background = brush;

// ✅ Freeze（不可变，性能好）
brush.Freeze();
button.Background = brush;

10.4 减少视觉树复杂度

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<!-- ❌ 嵌套太多 -->
<Grid>
 <Border>
 <Grid>
 <Border>
 <Button/>
 </Border>
 </Grid>
 </Border>
</Grid>

<!-- ✅ 扁平 -->
<Grid>
 <Button/>
</Grid>

十一、常见陷阱

11.1 动画结束后改属性无效

1
2


// 详见第 6 节
// 用 FillBehavior.Stop 或 BeginAnimation(dp, null) 解决

11.2 颜色动画路径写错

1
2
3
4
5
6


<!-- ❌ 直接 Background.Color -->
<ColorAnimation Storyboard.TargetProperty="Background.Color" .../>
<!-- 找不到 -->

<!-- ✅ 要写完整路径 -->
<ColorAnimation Storyboard.TargetProperty="(Control.Background).(SolidColorBrush.Color)" .../>

11.3 RenderTransform 没设 RenderTransformOrigin

1
2
3
4
5
6
7
8
9


<!-- ❌ 缩放原点在 (0,0)（左上角），看起来"飞走" -->
<Button RenderTransformOrigin="0,0">
 <Button.RenderTransform>
 <ScaleTransform ScaleX="2" ScaleY="2"/>
 </Button.RenderTransform>
</Button>

<!-- ✅ 缩放原点在中心 -->
<Button RenderTransformOrigin="0.5,0.5">...</Button>

11.4 动画死循环 UI 卡

1
2
3
4
5
6
7
8


// ❌ 用 Width 动画（每帧触发 layout）
DoubleAnimation widthAnim = new(100, 500, TimeSpan.FromSeconds(1));
myButton.BeginAnimation(WidthProperty, widthAnim);

// ✅ 用 ScaleTransform
DoubleAnimation scaleAnim = new(1, 1.5, TimeSpan.FromSeconds(1));
myButton.RenderTransform = new ScaleTransform();
((ScaleTransform)myButton.RenderTransform).BeginAnimation(ScaleTransform.ScaleXProperty, scaleAnim);

十二、与 CSS 动画的对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


CSS WPF
──────────────────────────────────────────
@keyframes <Storyboard>
animation: 1s ease Duration + EasingFunction
transform: scale() ScaleTransform
opacity Opacity
transition EventTrigger + DoubleAnimation
animation-fill-mode FillBehavior

共同点：
 - 都是声明式
 - 都用 GPU 加速
 - 都有缓动函数

差异：
 - CSS 的 transition 触发简单（属性变化）
 - WPF 要写完整 Storyboard（更冗长）
 - WPF 动画类型严格（double/Color/Point 分开）

十三、小结

本文深入 WPF 的图形与动画：

保留模式 vs 立即模式（WPF 选保留）
WPF 多线程渲染架构（UI / Composition / Render）
为什么动画不卡 UI（Composition 线程）
图形原语：Shape / Geometry / Brush / Transform
动画系统：Timeline / AnimationTimeline / Storyboard
三种基本动画（Double / Color / Point）
依赖属性动画"占用"机制（FillBehavior）
缓动函数与关键帧
实战：加载旋转 + Material 按钮悬停
性能优化（选对属性、Freeze、RenderOptions）

1
2
3
4


记住三句话：
 1. WPF 是保留模式——你改属性，框架渲染
 2. 动画跑在 Composition 线程——选 Opacity/RenderTransform 不卡 UI
 3. 动画结束后属性"被占用"——FillBehavior.Stop 或 BeginAnimation(null) 释放

下一篇进入 WPF 的自定义控件——UserControl / CustomControl / 重写 OnRender 三条路线，以及 PART_ 命名约定。

WPF 学习笔记（九）：多线程与 Dispatcher——UI 线程的真相

Thu, 21 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

本篇是后端工程师最容易踩坑的一篇。在 ASP.NET Core 里，async/await 是"线程池里跑"，没有"UI 线程"概念。但在 WPF 里，所有 UI 操作必须在单个 UI 线程上——改个 TextBox.Text 跨线程，直接抛异常。

本篇要把 WPF 的单线程模型、Dispatcher 消息循环、async/await 在 UI 上的特殊行为彻底讲清楚。

本文要回答：

为什么 UI 必须单线程？Dispatcher 到底在做什么？为什么后端的 .ConfigureAwait(false) 在 WPF 里行为不同？

一、为什么 UI 必须单线程

1.1 历史背景

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


Windows GUI 从 Win32 开始就是 STA 模型
 STA = Single-Threaded Apartment
 每个窗口有一个 UI 线程
 UI 操作只在该线程

为什么这样设计：
 1. 多线程并发改 UI → 状态不一致
 （线程 A 改 Text，线程 B 改 Visibility，渲染线程懵了）
 2. Win32 消息泵本质是"单线程队列"
 （PostMessage → 线程取消息 → 处理）
 3. COM 的 STA 模型（Office、Shell 都是 STA）

WPF 继承了这个约束：
 所有 UI 元素创建在 UI 线程
 所有 UI 操作必须在 UI 线程
 违反 → InvalidOperationException

1.2 异常演示

1
2
3
4
5
6
7
8


// 后台线程改 UI
private async void Button_Click(object sender, RoutedEventArgs e)
{
 await Task.Run(() =>
 {
 myTextBlock.Text = "Hello"; // ❌ 抛异常
 });
}

1
2
3
4
5
6


异常信息：
 "The calling thread cannot access this object because a different thread owns it."

所有继承 DispatcherObject 的对象都有"线程亲和性"
 → 创建它的线程是"owner"
 → 只有 owner 线程能访问

1.3 DispatcherObject 的"线程亲和性"

1
2
3
4
5
6
7


// WPF 几乎所有对象都是 DispatcherObject 派生
public abstract class DispatcherObject
{
 public Dispatcher Dispatcher { get; }
 public bool CheckAccess() { ... } // 当前线程是否是 owner
 public void VerifyAccess() { ... } // 不是 owner 抛异常
}

1
2
3
4
5
6
7
8


DependencyObject → DispatcherObject
UIElement → ...
FrameworkElement → ...
Control → ...
Button → ...

→ WPF 几乎所有元素都"绑定到一个 Dispatcher"
→ 跨线程访问 → 异常

二、Dispatcher：UI 线程的消息循环

2.1 Dispatcher 是什么

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Dispatcher = UI 线程的"消息调度器"
 - 一个线程最多一个 Dispatcher
 - UI 线程的 Dispatcher 处理：
 * Win32 消息（鼠标、键盘）
 * WPF 的内部任务（layout、rendering）
 * 你 Post 的代码

工作流：
 while (true)
 {
 var work = DequeueHighestPriorityItem();
 work.Invoke();
 }

2.2 获取 Dispatcher

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 当前线程的 Dispatcher（如果有的话）
Dispatcher current = Dispatcher.CurrentDispatcher;

// 应用主 UI 线程的 Dispatcher（最常用）
Dispatcher ui = Application.Current.Dispatcher;

// 某个 UI 元素的 Dispatcher
Dispatcher elementDispatcher = myButton.Dispatcher;

// 通常这三种都返回同一个 Dispatcher（主 UI 线程）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


CurrentDispatcher vs Application.Current.Dispatcher 区别：
 CurrentDispatcher：
 → 当前线程的 Dispatcher（如果没就临时创建一个，可能不是你想要的）
 → 后台线程调用会创建临时 Dispatcher（陷阱！）

 Application.Current.Dispatcher：
 → 主 UI 线程的 Dispatcher（永远正确）
 → 推荐用法

 element.Dispatcher：
 → 元素所在线程的 Dispatcher（UI 元素就是主线程）
 → 也推荐

2.3 与 Win32 消息泵的关系

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Dispatcher 内部就是 Win32 消息泵的包装：

 GetMessage / PeekMessage（Win32）
 ↓
 TranslateMessage / DispatchMessage（Win32）
 ↓
 WPF 接管：
 - 系统消息（鼠标、键盘）→ 路由事件
 - WPF 自定义消息 → Dispatcher 操作队列

 Dispatcher.Run() = 进入消息循环（永不返回，直到 Shutdown）

三、跨线程访问 UI

3.1 Dispatcher.Invoke 系列

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// 同步执行
Application.Current.Dispatcher.Invoke(() =>
{
 myTextBlock.Text = "Updated";
});

// 带返回值
var result = Application.Current.Dispatcher.Invoke(() =>
{
 return myTextBox.Text;
});

// 异步（BeginInvoke，返回 DispatcherOperation）
Application.Current.Dispatcher.BeginInvoke(new Action(() =>
{
 myTextBlock.Text = "Updated";
}));

3.2 Invoke vs BeginInvoke vs InvokeAsync

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Invoke(action)：
 - 同步阻塞
 - 等到 action 执行完才返回
 - ⚠️ 危险：从 UI 线程自己调 → 可能死锁

BeginInvoke(action)：
 - 异步，把 action 加入队列立即返回
 - 返回 DispatcherOperation（可等待）
 - 老接口（沿用自 WinForms）

InvokeAsync(action)：
 - 异步，返回 Task<T>
 - 现代 API（推荐）
 - 支持 await

1
2
3
4
5


// 推荐写法
await Application.Current.Dispatcher.InvokeAsync(() =>
{
 myTextBlock.Text = "Updated";
});

3.3 死锁陷阱

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// ❌ 在 UI 线程调 Invoke → 死锁
private void Button_Click(...)
{
 // 当前已经在 UI 线程
 Dispatcher.Invoke(() => // 试图"同步切到 UI 线程"
 {
 // 但 UI 线程被外层阻塞着（Invoke 是同步的）
 // → 永远等不到执行
 // → 死锁
 DoSomething();
 });
}

// ✅ 用 BeginInvoke / InvokeAsync（异步）
Dispatcher.BeginInvoke(() => DoSomething());

// ✅ 或检查是否已经在 UI 线程
if (!Dispatcher.CheckAccess())
 Dispatcher.Invoke(...);
else
 ... // 直接执行

四、async/await 在 WPF

后端工程师的关键调整点。

4.1 SynchronizationContext

1
2
3
4
5
6
7
8
9


async/await 的"上下文捕获"机制：
 await 一个 Task 前，记录当前 SynchronizationContext
 await 完成后，回到原上下文继续

不同环境的 SynchronizationContext：
 ASP.NET Core：null（无上下文）→ 任意线程池线程继续
 ASP.NET 经典：AspNetSynchronizationContext → 请求线程继续
 WPF：DispatcherSynchronizationContext → UI 线程继续
 WinForms：WindowsFormsSynchronizationContext → UI 线程继续

4.2 WPF 的 await 行为

1
2
3
4
5
6


private async void Button_Click(object sender, RoutedEventArgs e)
{
 var result = await SomeAsyncOperation();
 // ← 这里回到 UI 线程继续
 myTextBlock.Text = result; // ✅ 安全
}

1
2
3
4
5
6
7
8
9


执行流：
 1. Button_Click 在 UI 线程执行
 2. await SomeAsyncOperation()
 → 记录 SynchronizationContext（= UI 线程）
 → 线程池线程跑 SomeAsyncOperation
 3. 完成后，Post 回 UI 线程
 4. myTextBlock.Text = result 在 UI 线程

这就是为什么"后端 await 模式"在 WPF 也能用

4.3 ConfigureAwait(false)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// ❌ WPF 中常见反模式
private async Task LoadAsync()
{
 var data = await httpClient.GetAsync(url);
 // 后续回到 UI 线程
 var json = await data.Content.ReadAsStringAsync();
 // 又回到 UI 线程（多余的切换）
}

// ✅ 库代码用 ConfigureAwait(false)
public async Task<string> FetchAsync()
{
 var data = await httpClient.GetAsync(url).ConfigureAwait(false);
 var json = await data.Content.ReadAsStringAsync().ConfigureAwait(false);
 // 全程在后台线程
 return json;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


ConfigureAwait(false) 的语义：
 - 不捕获 SynchronizationContext
 - 后续在任意线程池线程继续
 - 性能更好（避免 UI 线程切换）
 - 但后续不能直接访问 UI

什么时候用：
 - 库代码（不关心调用方是 UI 还是控制台）
 - 不需要访问 UI 的步骤

什么时候不用：
 - UI 层代码（要访问 UI）
 - WPF ViewModel 的命令（最后要更新 UI）

4.4 完整模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


public partial class MainViewModel : ObservableObject
{
 [RelayCommand]
 private async Task LoadDataAsync()
 {
 IsLoading = true;
 try
 {
 // 后台线程获取数据（用 ConfigureAwait(false) 优化）
 var data = await _service.GetDataAsync().ConfigureAwait(false);

 // 回 UI 线程更新 ObservableCollection
 await Application.Current.Dispatcher.InvokeAsync(() =>
 {
 Items.Clear();
 foreach (var item in data) Items.Add(item);
 });
 }
 finally
 {
 // IsLoading 是 INPC，绑定更新要 UI 线程
 // 但 await 之前的 ConfigureAwait(false) 让我们不在 UI 线程
 // 切回去
 await Application.Current.Dispatcher.InvokeAsync(() => IsLoading = false);
 }
 }
}

1
2
3
4


观察：
 - await 默认回 UI 线程（什么都不写最简单）
 - 优化才用 ConfigureAwait(false)
 - 后台线程改 UI 必须用 Dispatcher

五、DispatcherTimer vs Task.Delay

两个看起来都能"延迟"，但完全不同。

5.1 DispatcherTimer

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var timer = new DispatcherTimer
{
 Interval = TimeSpan.FromSeconds(1)
};
timer.Tick += (s, e) =>
{
 // 在 UI 线程触发
 myTextBlock.Text = DateTime.Now.ToString();
};
timer.Start();

1
2
3
4
5
6
7
8
9


DispatcherTimer：
 - 在 UI 线程触发 Tick
 - 优先级由 Dispatcher 控制（默认 Background）
 - 不精确（受 UI 繁忙程度影响）
 - 可以直接访问 UI

适用：
 - 定期刷新 UI（每秒更新时钟）
 - 不需要精确定时

5.2 Task.Delay

1
2
3


await Task.Delay(1000);
// 1 秒后继续（线程池线程）
// 注意：在 WPF 中 await 后默认回 UI 线程

1
2
3
4
5
6
7
8
9


Task.Delay：
 - 基于 Task 的延迟
 - 不占用 UI 线程
 - 配合 async/await 用
 - await 后回到原 SynchronizationContext

适用：
 - 异步流程里的延迟
 - 不需要"定时触发"

5.3 区别

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


场景：每秒更新 UI

DispatcherTimer：
 - 简单
 - UI 卡顿时丢帧（不会触发）
 - UI 线程触发

Task.Delay + 循环：
 - 略复杂
 - 后台线程触发（不卡 UI）
 - 配合 Dispatcher 更新 UI

推荐：
 - 普通定时器（时钟、UI 刷新）用 DispatcherTimer
 - 异步流程内延迟用 Task.Delay

六、跨线程访问 UI 的正确姿势

6.1 IProgress

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


private async Task ProcessAsync()
{
 var progress = new Progress<int>(p =>
 {
 // 回调在 UI 线程（Progress<T> 自动捕获 SynchronizationContext）
 progressBar.Value = p;
 });

 await Task.Run(() =>
 {
 for (int i = 0; i <= 100; i++)
 {
 ((IProgress<int>)progress).Report(i);
 Thread.Sleep(50);
 }
 });
}

1
2
3
4
5


Progress<T>：
 - 创建时捕获 SynchronizationContext
 - Report 在 UI 线程触发回调
 - 是"进度通知"的标准模式
 - 比手动 Dispatcher.Invoke 干净

6.2 CancellationToken

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


private async Task ProcessAsync(CancellationToken token)
{
 await Task.Run(async () =>
 {
 for (int i = 0; i < 1000; i++)
 {
 token.ThrowIfCancellationRequested();
 await DoWorkAsync(i);
 }
 }, token);
}

// 调用
var cts = new CancellationTokenSource();
buttonCancel.Click += (s, e) => cts.Cancel();
await ProcessAsync(cts.Token);

6.3 完整模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


[RelayCommand]
private async Task LongOperationAsync(CancellationToken token)
{
 var progress = new Progress<int>(p =>
 {
 ProgressValue = p;
 });

 try
 {
 var result = await Task.Run(() => DoHeavyWork(progress, token), token);
 Result = result;
 }
 catch (OperationCanceledException)
 {
 // 用户取消
 }
}

private int DoHeavyWork(IProgress<int> progress, CancellationToken token)
{
 for (int i = 0; i <= 100; i++)
 {
 token.ThrowIfCancellationRequested();
 Thread.Sleep(50);
 progress.Report(i);
 }
 return 42;
}

七、BackgroundWorker 的现代替代

老代码用 BackgroundWorker，新代码用 Task.Run + Progress + CancellationToken。

7.1 BackgroundWorker（旧）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


var worker = new BackgroundWorker
{
 WorkerReportsProgress = true,
 WorkerSupportsCancellation = true
};

worker.DoWork += (s, e) =>
{
 // 后台线程
 for (int i = 0; i <= 100; i++)
 {
 if (worker.CancellationPending) { e.Cancel = true; return; }
 worker.ReportProgress(i);
 Thread.Sleep(50);
 }
};

worker.ProgressChanged += (s, e) =>
{
 // UI 线程
 progressBar.Value = e.ProgressPercentage;
};

worker.RunWorkerCompleted += (s, e) =>
{
 // UI 线程
 if (e.Cancelled) return;
 MessageBox.Show("Done");
};

worker.RunWorkerAsync();

7.2 现代等价（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


private async Task RunWithProgressAsync(CancellationToken token)
{
 var progress = new Progress<int>(p => progressBar.Value = p);

 try
 {
 await Task.Run(() =>
 {
 for (int i = 0; i <= 100; i++)
 {
 token.ThrowIfCancellationRequested();
 ((IProgress<int>)progress).Report(i);
 Thread.Sleep(50);
 }
 }, token);

 MessageBox.Show("Done");
 }
 catch (OperationCanceledException) { }
}

1
2
3
4
5


现代优势：
 - 更简洁
 - 异常处理自然（try-catch）
 - 取消用标准 CancellationToken
 - 没有事件订阅的内存泄漏

八、Dispatcher 优先级

Dispatcher 处理任务有优先级。

8.1 优先级枚举

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


DispatcherPriority 枚举（从高到低）：
 Send （最高，同步执行）
 Normal
 Background
 Input （键盘鼠标输入）
 Loaded
 Render
 DataBind
 Send （最低）
 Inactive
 ApplicationIdle
 ContextIdle
 Background
 ...

8.2 用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 等到 UI 渲染完再执行
await Application.Current.Dispatcher.InvokeAsync(() =>
{
 // 在所有渲染任务后
}, DispatcherPriority.Loaded);

// 等到 Application Idle（空闲）
await Application.Current.Dispatcher.InvokeAsync(() =>
{
 // 应用空闲时执行
}, DispatcherPriority.ApplicationIdle);

8.3 让 UI 响应

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// ❌ 长循环阻塞 UI
private void ProcessData()
{
 for (int i = 0; i < 1000000; i++)
 {
 DoWork(i); // 阻塞 UI 线程
 }
}

// ✅ 切到后台线程
private async Task ProcessDataAsync()
{
 await Task.Run(() =>
 {
 for (int i = 0; i < 1000000; i++) DoWork(i);
 });
}

// ✅ 或者用 Dispatcher.Yield（不推荐，仅调试）
for (int i = 0; i < 1000000; i++)
{
 DoWork(i);
 if (i % 1000 == 0)
 await Dispatcher.Yield(DispatcherPriority.Background);
}

九、实战：可取消的进度条后台任务

9.1 ViewModel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


public partial class MainViewModel : ObservableObject
{
 private CancellationTokenSource _cts;

 [ObservableProperty]
 private int _progress;

 [ObservableProperty]
 private bool _isRunning;

 [ObservableProperty]
 private string _status = "就绪";

 [RelayCommand]
 private async Task StartAsync()
 {
 _cts = new CancellationTokenSource();
 IsRunning = true;
 Status = "处理中...";

 var progress = new Progress<int>(p => Progress = p);

 try
 {
 var result = await Task.Run(() => DoWorkAsync(progress, _cts.Token), _cts.Token);
 Status = $"完成：{result}";
 }
 catch (OperationCanceledException)
 {
 Status = "已取消";
 Progress = 0;
 }
 finally
 {
 IsRunning = false;
 }
 }

 [RelayCommand]
 private void Cancel()
 {
 _cts?.Cancel();
 }

 private int DoWorkAsync(IProgress<int> progress, CancellationToken token)
 {
 int total = 100;
 for (int i = 0; i <= total; i++)
 {
 token.ThrowIfCancellationRequested();
 Thread.Sleep(50);
 progress.Report(i);
 }
 return 42;
 }
}

9.2 XAML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<Window.DataContext>
 <local:MainViewModel/>
</Window.DataContext>

<StackPanel Margin="20">
 <ProgressBar Value="{Binding Progress}" Maximum="100" Height="25" Margin="0,0,0,8"/>

 <TextBlock Text="{Binding Status}" Margin="0,0,0,8"/>

 <StackPanel Orientation="Horizontal">
 <Button Content="开始" Command="{Binding StartCommand}" Width="80" Margin="0,0,8,0"
 IsEnabled="{Binding IsRunning, Converter={StaticResource InverseBool}}"/>
 <Button Content="取消" Command="{Binding CancelCommand}" Width="80"
 IsEnabled="{Binding IsRunning}"/>
 </StackPanel>
</StackPanel>

9.3 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


✅ Task.Run 后台执行
✅ IProgress<T> 进度通知（自动 UI 线程）
✅ CancellationToken 取消
✅ RelayCommand 异步命令
✅ IsRunning 状态绑定按钮启用
✅ 异常处理（OperationCanceledException）

观察：
 - 任务期间 UI 完全响应（可拖动、可取消）
 - 进度条平滑更新（每 50ms 一次）
 - 取消立即响应（每次循环检查 token）

十、与 ASP.NET Core 的关键对比

后端工程师必读。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


 ASP.NET Core WPF
─────────────────────────────────────────────────────────────
SynchronizationContext null（无） DispatcherSynchronizationContext
默认 await 后续 任意线程池线程 UI 线程
ConfigureAwait(false) 无意义（已无上下文） 显著优化（避免 UI 切换）
线程模型 每请求独立 单 UI 线程
跨线程访问 无"线程亲和"对象 UI 元素有亲和性
进度报告 IProgress<T> IProgress<T>（自动 UI 切换）
取消 CancellationToken CancellationToken（同样）
Timer System.Threading.Timer DispatcherTimer（UI 线程）

关键差异：
 1. ASP.NET Core 没有 UI 线程概念
 → 后端代码可以任意线程跑
 → ConfigureAwait(false) 几乎无意义

 2. WPF 的 await 默认回 UI 线程
 → 简单（不写 ConfigureAwait 就回 UI）
 → 但要小心"过度切换"（库代码用 ConfigureAwait(false) 优化）

 3. 后台代码改 UI 必须用 Dispatcher
 → 这条 ASP.NET Core 工程师最容易忘

10.1 经典迁移错误

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// 后端思维（在 ASP.NET Core 没问题）
public async Task<string> GetAsync()
{
 var data = await httpClient.GetStringAsync(url);
 return data.Trim();
}

// 直接搬到 WPF ViewModel 没问题（await 自动回 UI）
public async Task<string> GetAsync()
{
 var data = await httpClient.GetStringAsync(url);
 return data.Trim();
}

// ❌ 但如果换 Task.Run 不 await
public string Get()
{
 var data = httpClient.GetStringAsync(url).Result; // ❌ 死锁
 return data.Trim();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


.Result 在 WPF 死锁原因：
 - .Result 阻塞 UI 线程
 - httpClient 内部要回到 UI 线程（SynchronizationContext）
 - 但 UI 线程被阻塞
 - → 死锁

ASP.NET Core 不死锁：
 - 无 SynchronizationContext
 - httpClient 不需要回到原线程
 - .Result 直接拿后台结果

修复：
 - 用 await（推荐）
 - 或 ConfigureAwait(false)（库代码）

十一、常见陷阱

11.1 async void

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// ❌ async void 异常会崩溃
private async void DoWork()
{
 await Task.Delay(1000);
 throw new Exception(); // 应用崩溃
}

// ✅ async Task
private async Task DoWorkAsync()
{
 await Task.Delay(1000);
 throw new Exception(); // 异常被 Task 捕获
}

// 例外：事件处理器（必须是 async void）
private async void Button_Click(...)
{
 await DoWorkAsync();
}

11.2 忘了 await

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// ❌ fire-and-forget
[RelayCommand]
private void Save()
{
 _service.SaveAsync(); // 没 await，异常丢失
}

// ✅
[RelayCommand]
private async Task SaveAsync()
{
 await _service.SaveAsync();
}

11.3 后台线程改 ObservableCollection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// ❌
await Task.Run(() =>
{
 Items.Add(new Item()); // 异常
});

// ✅ 切回 UI 线程
await Application.Current.Dispatcher.InvokeAsync(() =>
{
 Items.Add(new Item());
});

// ✅ 或启用集合同步
BindingOperations.EnableCollectionSynchronization(Items, _lock);

11.4 在构造函数里 await

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// ❌ 构造函数不能 async
public MainViewModel()
{
 await LoadDataAsync(); // 编译错误
}

// ✅ 异步初始化模式
public MainViewModel()
{
 Loaded = LoadDataAsync();
}

public Task Loaded { get; }

// 调用方
await viewModel.Loaded;

11.5 CurrentDispatcher 陷阱

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// ❌ 在后台线程调
Task.Run(() =>
{
 Dispatcher.CurrentDispatcher.Invoke(...);
 // CurrentDispatcher 在后台线程会"创建临时 Dispatcher"
 // 不是 UI 线程的 Dispatcher
});

// ✅ 用 Application.Current.Dispatcher
Task.Run(() =>
{
 Application.Current.Dispatcher.Invoke(...);
});

十二、小结

本文深入 WPF 的多线程模型：

UI 单线程硬约束的历史与必要性
Dispatcher 的角色（消息循环 + 任务调度）
DispatcherObject 的线程亲和性
Invoke / BeginInvoke / InvokeAsync 的差异与死锁陷阱
SynchronizationContext 与 WPF 的 await 行为
ConfigureAwait(false) 在 WPF 的语义
DispatcherTimer vs Task.Delay
IProgress + CancellationToken 模式
BackgroundWorker 的现代替代
Dispatcher 优先级
实战：可取消进度条后台任务
与 ASP.NET Core 的关键差异

1
2
3
4


记住三句话：
 1. UI 单线程是硬约束——后台线程改 UI 必须用 Dispatcher
 2. await 默认回 UI 线程（DispatcherSynchronizationContext），库代码用 ConfigureAwait(false) 优化
 3. 后端工程师最常踩的坑：.Result 在 WPF 会死锁（ASP.NET Core 不会）

下一篇进入 WPF 的图形与动画——保留模式渲染、Timeline、Storyboard、动画占用机制。

WPF 学习笔记（八）：样式与模板——WPF 的"换肤"机制

Sun, 17 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

WPF 最让人惊艳的特性之一——同一个 Button，可以看起来像 Material 按钮、像 iOS 按钮、像 Office 按钮、甚至像一颗星星。所有这些"换肤"都靠本篇讲的三层机制：Style、ControlTemplate、DataTemplate。

本篇要把它们各自的语义、适用场景、相互关系讲清楚。理解之后，你就能从"用别人写好的控件"升级到"自己定义控件外观"。

本文要回答：

Style / ControlTemplate / DataTemplate 三者到底有什么区别？StaticResource 和 DynamicResource 选哪个？Trigger 为什么"不用写代码就能改外观"？

一、资源系统：ResourceDictionary

样式、模板、画刷都存在"资源"里。

1.1 资源的定义和使用

1
2
3
4
5
6
7
8


<Window.Resources>
 <SolidColorBrush x:Key="AccentBrush" Color="DodgerBlue"/>
 <Style x:Key="MyButton" TargetType="Button">
 <Setter Property="Background" Value="{StaticResource AccentBrush}"/>
 </Style>
</Window.Resources>

<Button Content="OK" Style="{StaticResource MyButton}"/>

1
2
3
4
5
6


资源定义：放在 .Resources 字典里
 - x:Key 是资源名（必须）
 - 任意对象都可以是资源（Brush / Style / Template / 数字 / 字符串）

资源使用：{StaticResource key} 或 {DynamicResource key}
 - 通过 key 查找

1.2 资源查找链

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


WPF 资源查找顺序（从内到外）：

 元素自身.Resources
 ↓（找不到）
 父元素.Resources
 ↓
 Window.Resources
 ↓
 App.Resources
 ↓
 Theme（系统主题样式）
 ↓
 抛 XamlParseException

类似变量作用域链

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<Window.Resources>
 <SolidColorBrush x:Key="bg" Color="Red"/> <!-- 全局 -->
</Window.Resources>

<Grid>
 <Grid.Resources>
 <SolidColorBrush x:Key="bg" Color="Blue"/> <!-- 局部覆盖 -->
 </Grid.Resources>
 <Button Background="{StaticResource bg}"/> <!-- 用蓝色（局部优先） -->
</Grid>

1.3 ResourceDictionary 合并

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<!-- App.xaml 合并多个资源字典 -->
<Application.Resources>
 <ResourceDictionary>
 <ResourceDictionary.MergedDictionaries>
 <ResourceDictionary Source="Styles/Colors.xaml"/>
 <ResourceDictionary Source="Styles/Buttons.xaml"/>
 <ResourceDictionary Source="Styles/TextBoxes.xaml"/>
 </ResourceDictionary.MergedDictionaries>

 <!-- 这里仍可定义本地资源 -->
 <SolidColorBrush x:Key="bg" Color="White"/>
 </ResourceDictionary>
</Application.Resources>

1
2
3
4
5
6
7
8


组织方式：
 - Colors.xaml：颜色/画刷
 - Sizes.xaml：尺寸
 - Buttons.xaml：按钮样式
 - Brushes.xaml：渐变、画刷
 - ThemeDark.xaml / ThemeLight.xaml：主题切换

 按需合并，可切换

二、StaticResource vs DynamicResource

2.1 区别

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


StaticResource：
 - 编译时（XAML 加载时）解析一次
 - 之后不再查
 - 性能好（一次性）
 - 改资源字典不会更新引用

DynamicResource：
 - 运行时解析
 - 资源变化时自动更新引用
 - 性能稍差
 - 支持主题切换、运行时换肤

2.2 何时用 DynamicResource

1
2
3
4
5


<!-- 主题切换：换主题时所有引用自动更新 -->
<Button Background="{DynamicResource AccentBrush}"/>

<!-- 系统颜色：用户改系统主题时跟随 -->
<TextBlock Foreground="{DynamicResource {x:Static SystemColors.WindowTextBrushKey}}"/>

1
2
3
4
5
6


常见 DynamicResource 场景：
 - 系统颜色 / 字体（用户改系统设置时跟随）
 - 主题切换（运行时换 ResourceDictionary）
 - 跨程序集的资源引用

其他场景用 StaticResource 即可（性能更好）

2.3 主题切换实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


private void SwitchTheme(string themeName)
{
 var newDict = new ResourceDictionary
 {
 Source = new Uri($"Themes/{themeName}.xaml", UriKind.Relative)
 };

 // 替换合并字典
 Application.Current.Resources.MergedDictionaries.Clear();
 Application.Current.Resources.MergedDictionaries.Add(newDict);
}

1

所有 {DynamicResource ...} 引用都会自动更新

三、Style（样式）

3.1 基本用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<Window.Resources>
 <Style x:Key="PrimaryButton" TargetType="Button">
 <Setter Property="Background" Value="DodgerBlue"/>
 <Setter Property="Foreground" Value="White"/>
 <Setter Property="FontWeight" Value="Bold"/>
 <Setter Property="Padding" Value="20,8"/>
 <Setter Property="BorderThickness" Value="0"/>
 </Style>
</Window.Resources>

<Button Content="保存" Style="{StaticResource PrimaryButton}"/>
<Button Content="取消" Style="{StaticResource PrimaryButton}"/>

3.2 隐式样式（不写 x:Key）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<Window.Resources>
 <Style TargetType="Button"> <!-- 注意没 x:Key -->
 <Setter Property="Background" Value="DodgerBlue"/>
 <Setter Property="Foreground" Value="White"/>
 </Style>
</Window.Resources>

<!-- 所有 Button 自动应用 -->
<Button Content="保存"/>
<Button Content="取消"/>

1
2
3
4
5
6
7
8
9


隐式样式的规则：
 - TargetType 必填，x:Key 不写
 - 自动应用到该类型的所有元素
 - 但只对"声明样式的作用域内"生效
 - 派生类不自动应用（RepeatButton 不会用 Button 的隐式样式）

适用：
 - 全局按钮风格统一
 - 全局文本样式

3.3 样式继承（BasedOn）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<Style x:Key="BaseButton" TargetType="Button">
 <Setter Property="FontWeight" Value="Bold"/>
 <Setter Property="Padding" Value="20,8"/>
</Style>

<Style x:Key="PrimaryButton" TargetType="Button" BasedOn="{StaticResource BaseButton}">
 <Setter Property="Background" Value="DodgerBlue"/>
 <Setter Property="Foreground" Value="White"/>
</Style>

<Style x:Key="DangerButton" TargetType="Button" BasedOn="{StaticResource BaseButton}">
 <Setter Property="Background" Value="Red"/>
 <Setter Property="Foreground" Value="White"/>
</Style>

1
2


BasedOn 类似 CSS 的继承
子样式继承父样式的所有 Setter，可覆盖

四、Trigger（触发器）

不用写代码，“条件改变时改属性”。

4.1 PropertyTrigger（属性触发器）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<Style TargetType="Button">
 <Setter Property="Background" Value="DodgerBlue"/>
 <Setter Property="Foreground" Value="White"/>

 <Style.Triggers>
 <!-- 鼠标悬停 -->
 <Trigger Property="IsMouseOver" Value="True">
 <Setter Property="Background" Value="LightBlue"/>
 </Trigger>

 <!-- 禁用 -->
 <Trigger Property="IsEnabled" Value="False">
 <Setter Property="Background" Value="Gray"/>
 <Setter Property="Foreground" Value="LightGray"/>
 </Trigger>
 </Style.Triggers>
</Style>

1
2
3
4
5


效果：
 - 默认蓝色
 - 鼠标悬停浅蓝（IsMouseOver=true 时）
 - 禁用灰色（IsEnabled=false 时）
 - 离开/恢复时自动回退（不用写代码！）

4.2 MultiTrigger（多条件）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<Style TargetType="Button">
 <Style.Triggers>
 <MultiTrigger>
 <MultiTrigger.Conditions>
 <Condition Property="IsMouseOver" Value="True"/>
 <Condition Property="IsEnabled" Value="True"/>
 </MultiTrigger.Conditions>
 <Setter Property="Background" Value="LightGreen"/>
 </MultiTrigger>
 </Style.Triggers>
</Style>

4.3 EventTrigger（事件触发器）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


<Style TargetType="Button">
 <Style.Triggers>
 <EventTrigger RoutedEvent="MouseEnter">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="Opacity"
 To="0.7" Duration="0:0:0.2"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 <EventTrigger RoutedEvent="MouseLeave">
 <BeginStoryboard>
 <Storyboard>
 <DoubleAnimation Storyboard.TargetProperty="Opacity"
 To="1.0" Duration="0:0:0.2"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 </Style.Triggers>
</Style>

1
2


EventTrigger 触发动画（详见第 10 篇）
不是简单改属性

4.4 DataTrigger（数据触发器）

1
2
3
4
5
6
7
8


<Style TargetType="TextBlock">
 <Style.Triggers>
 <DataTrigger Binding="{Binding IsUrgent}" Value="True">
 <Setter Property="Foreground" Value="Red"/>
 <Setter Property="FontWeight" Value="Bold"/>
 </DataTrigger>
 </Style.Triggers>
</Style>

1
2


DataTrigger 监听"任意绑定的数据"
比 PropertyTrigger（只能监听自身属性）更强大

4.5 MultiDataTrigger

1
2
3
4
5
6
7


<MultiDataTrigger>
 <MultiDataTrigger.Conditions>
 <Condition Binding="{Binding IsUrgent}" Value="True"/>
 <Condition Binding="{Binding IsOverdue}" Value="True"/>
 </MultiDataTrigger.Conditions>
 <Setter Property="Background" Value="DarkRed"/>
</MultiDataTrigger>

五、ControlTemplate（控件模板）

Style 改的是"属性"，ControlTemplate 改的是"外观结构"。

5.1 默认 Button 的视觉树

1
2
3
4


Button（默认模板展开）
 └─ ButtonChrome（主题边框）
 └─ ContentPresenter（内容容器）
 └─ （你的 Content）

1
2
3


ControlTemplate 的作用：
 完全替换上面的视觉树
 → 你可以让 Button 看起来像任何东西

5.2 自定义 Button 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


<Style TargetType="Button">
 <Setter Property="Template">
 <Setter.Value>
 <ControlTemplate TargetType="Button">
 <Grid>
 <!-- 边框 -->
 <Border x:Name="border"
 Background="{TemplateBinding Background}"
 BorderBrush="{TemplateBinding BorderBrush}"
 BorderThickness="{TemplateBinding BorderThickness}"
 CornerRadius="6">
 <!-- 内容 -->
 <ContentPresenter HorizontalAlignment="Center"
 VerticalAlignment="Center"
 Content="{TemplateBinding Content}"/>
 </Border>
 </Grid>

 <ControlTemplate.Triggers>
 <Trigger Property="IsMouseOver" Value="True">
 <Setter TargetName="border" Property="Opacity" Value="0.8"/>
 </Trigger>
 <Trigger Property="IsPressed" Value="True">
 <Setter TargetName="border" Property="Opacity" Value="0.6"/>
 </Trigger>
 </ControlTemplate.Triggers>
 </ControlTemplate>
 </Setter.Value>
 </Setter>
</Style>

5.3 TemplateBinding

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


TemplateBinding = 在 ControlTemplate 里"接通"原控件的属性

 Background="{TemplateBinding Background}"
 → 把模板内 Border.Background 接到 Button.Background
 → 你设置 Button.Background="Red"，模板里的 Border 也是红

 等价于：
 Background="{Binding Background, RelativeSource={RelativeSource TemplatedParent}, Mode=OneWay}"

 TemplateBinding 是它的语法糖（且 OneWay）

5.4 ContentPresenter

1
2
3
4
5
6
7


ContentPresenter = "原控件的内容放这里"

 <ContentPresenter Content="{TemplateBinding Content}"/>
 → Button.Content 会被渲染到这个位置

 类似 ASP.NET Razor 的 RenderBody()
 → 模板留个洞，外面填充

六、DataTemplate（数据模板）

ControlTemplate 决定"控件长什么样" DataTemplate 决定"数据长什么样"

6.1 问题引入

1
2
3
4


<ListBox ItemsSource="{Binding Items}"/>
<!-- Items 是 List<TodoItem> -->
<!-- ListBox 不知道怎么显示 TodoItem -->
<!-- 默认调用 .ToString()，丑爆 -->

6.2 用 DataTemplate

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<ListBox ItemsSource="{Binding Items}">
 <ListBox.ItemTemplate>
 <DataTemplate>
 <Grid Margin="4">
 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="Auto"/>
 <ColumnDefinition Width="*"/>
 <ColumnDefinition Width="Auto"/>
 </Grid.ColumnDefinitions>
 <CheckBox Grid.Column="0" IsChecked="{Binding Completed}"/>
 <TextBlock Grid.Column="1" Text="{Binding Title}" Margin="8,0"/>
 <TextBlock Grid.Column="2" Text="{Binding CreatedAt, StringFormat=yyyy-MM-dd}"/>
 </Grid>
 </DataTemplate>
 </ListBox.ItemTemplate>
</ListBox>

1
2
3
4
5


效果：
 每个 TodoItem 不再是 ToString
 而是按 DataTemplate 渲染（复选框 + 标题 + 日期）

 DataContext 自动是当前 Item

6.3 隐式 DataTemplate（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<!-- App.xaml 全局注册 -->
<Application.Resources>
 <DataTemplate DataType="{x:Type models:TodoItem}">
 <Grid Margin="4">
 <TextBlock Text="{Binding Title}"/>
 </Grid>
 </DataTemplate>

 <DataTemplate DataType="{x:Type models:User}">
 <StackPanel Orientation="Horizontal">
 <Image Source="{Binding Avatar}" Width="32"/>
 <TextBlock Text="{Binding Name}" VerticalAlignment="Center"/>
 </StackPanel>
 </DataTemplate>
</Application.Resources>

1
2
3


<!-- 任意 ItemsControl 自动按数据类型选模板 -->
<ListBox ItemsSource="{Binding Items}"/>
<!-- 不同类型的 Item 显示不同样式 -->

1
2
3
4
5
6
7
8


隐式 DataTemplate 的优势：
 - 不需要在每个 ItemsControl 写 ItemTemplate
 - 同一类型在全应用一致显示
 - 异构列表（多种类型混合）自动选模板

后端类比：
 DataTemplate ≈ Razor 的 DisplayTemplate
 隐式 DataTemplate ≈ EditorTemplates/DisplayTemplates 按类型选

七、ControlTemplate vs DataTemplate 对比

维度	ControlTemplate	DataTemplate
应用对象	控件（Control）	数据（任意对象）
决定什么	控件外观结构	数据呈现方式
触发位置	Style.Template	ItemTemplate / ContentTemplate
内部绑定	TemplateBinding（绑控件属性）	普通绑定（绑数据）
隐式	主题样式（Generic.xaml）	DataType 隐式模板

1
2
3
4
5
6
7


记忆点：
 ControlTemplate 改"控件"（如 Button 怎么画）
 DataTemplate 改"数据"（如 TodoItem 怎么显示）

 一个控件同时可有两者：
 <ListBox ItemTemplate="..."/> <!-- 数据呈现 -->
 <ListBox.Template="..."/> <!-- 控件结构 -->

八、VisualStateManager（VSM）

Trigger 的"现代替代品"。

8.1 VSM 概念

1
2
3
4
5
6
7


VisualStateManager：
 - 把控件状态抽象成"组"
 - 每个状态对应一组动画/属性
 - 状态间过渡用动画

例：Button 有 CommonStates 组
 Normal / MouseOver / Pressed / Disabled

8.2 用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


<ControlTemplate TargetType="Button">
 <Grid>
 <Border x:Name="border" Background="DodgerBlue" CornerRadius="6"/>
 <ContentPresenter HorizontalAlignment="Center" VerticalAlignment="Center"/>

 <VisualStateManager.VisualStateGroups>
 <VisualStateGroup x:Name="CommonStates">
 <VisualState x:Name="Normal"/>
 <VisualState x:Name="MouseOver">
 <Storyboard>
 <ColorAnimation Storyboard.TargetName="border"
 Storyboard.TargetProperty="(Border.Background).(SolidColorBrush.Color)"
 To="LightBlue" Duration="0:0:0.2"/>
 </Storyboard>
 </VisualState>
 <VisualState x:Name="Pressed">
 <Storyboard>
 <ColorAnimation Storyboard.TargetName="border"
 Storyboard.TargetProperty="(Border.Background).(SolidColorBrush.Color)"
 To="DarkBlue" Duration="0:0:0.1"/>
 </Storyboard>
 </VisualState>
 </VisualStateGroup>
 </VisualStateManager.VisualStateGroups>
 </Grid>
</ControlTemplate>

8.3 Trigger vs VSM

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


Trigger（属性触发器）：
 - 简单属性变化
 - 立即生效
 - 在 ControlTemplate.Triggers 里
 - 适合"非动画"的简单切换

VSM：
 - 状态机模型
 - 内置动画过渡
 - 适合 CustomControl（自定义控件的标准做法）
 - 微软推荐用 VSM

实践：
 - 简单 Style（如颜色变化）用 Trigger
 - 自定义控件用 VSM
 - 大量动画用 VSM

九、实战：Material 风格 Button + 卡片 ListBox

9.1 Material Button

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


<!-- App.xaml -->
<Application.Resources>
 <Style x:Key="MaterialButton" TargetType="Button">
 <Setter Property="Background" Value="#2196F3"/>
 <Setter Property="Foreground" Value="White"/>
 <Setter Property="FontWeight" Value="Medium"/>
 <Setter Property="FontSize" Value="14"/>
 <Setter Property="Padding" Value="24,12"/>
 <Setter Property="BorderThickness" Value="0"/>
 <Setter Property="Cursor" Value="Hand"/>
 <Setter Property="Template">
 <Setter.Value>
 <ControlTemplate TargetType="Button">
 <Border x:Name="root"
 Background="{TemplateBinding Background}"
 CornerRadius="4">
 <ContentPresenter HorizontalAlignment="Center"
 VerticalAlignment="Center"
 Margin="{TemplateBinding Padding}"/>
 </Border>
 <ControlTemplate.Triggers>
 <Trigger Property="IsMouseOver" Value="True">
 <Setter TargetName="root" Property="Background" Value="#1976D2"/>
 </Trigger>
 <Trigger Property="IsPressed" Value="True">
 <Setter TargetName="root" Property="Background" Value="#0D47A1"/>
 </Trigger>
 <Trigger Property="IsEnabled" Value="False">
 <Setter TargetName="root" Property="Background" Value="#BDBDBD"/>
 </Trigger>
 </ControlTemplate.Triggers>
 </ControlTemplate>
 </Setter.Value>
 </Setter>
 </Style>

 <!-- 危险变体（继承） -->
 <Style x:Key="MaterialDangerButton" TargetType="Button"
 BasedOn="{StaticResource MaterialButton}">
 <Setter Property="Background" Value="#F44336"/>
 </Style>
</Application.Resources>

9.2 卡片 ListBox

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


<Application.Resources>
 <Style x:Key="CardListBox" TargetType="ListBox">
 <Setter Property="BorderThickness" Value="0"/>
 <Setter Property="Background" Value="Transparent"/>
 <Setter Property="ScrollViewer.HorizontalScrollBarVisibility" Value="Disabled"/>
 <Setter Property="ItemsPanel">
 <Setter.Value>
 <ItemsPanelTemplate>
 <WrapPanel/>
 </ItemsPanelTemplate>
 </Setter.Value>
 </Setter>
 </Style>

 <!-- 卡片 DataTemplate -->
 <DataTemplate x:Key="CardTemplate" DataType="{x:Type models:TodoItem}">
 <Border Background="White" CornerRadius="6" Padding="16" Margin="8"
 Width="240">
 <Border.Effect>
 <DropShadowEffect BlurRadius="8" ShadowDepth="2" Opacity="0.2"/>
 </Border.Effect>

 <StackPanel>
 <Grid>
 <TextBlock Text="{Binding Title}" FontWeight="Bold" FontSize="16"/>
 <Border HorizontalAlignment="Right"
 Background="{Binding Completed,
 Converter={StaticResource StatusToColor}}"
 CornerRadius="8" Padding="6,2">
 <TextBlock Text="{Binding Completed,
 Converter={StaticResource StatusToText}}"
 Foreground="White" FontSize="11"/>
 </Border>
 </Grid>

 <TextBlock Text="{Binding Description}"
 Foreground="Gray" Margin="0,8,0,0"
 TextTrimming="CharacterEllipsis"/>
 <TextBlock Text="{Binding CreatedAt, StringFormat=yyyy-MM-dd HH:mm}"
 Foreground="LightGray" FontSize="11" Margin="0,8,0,0"/>
 </StackPanel>
 </Border>
 </DataTemplate>
</Application.Resources>

1
2
3
4


<!-- 使用 -->
<ListBox Style="{StaticResource CardListBox}"
 ItemTemplate="{StaticResource CardTemplate}"
 ItemsSource="{Binding Todos}"/>

9.3 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


✅ Style + Setter + 隐式触发器
✅ ControlTemplate + TemplateBinding + ContentPresenter
✅ ControlTemplate.Triggers
✅ Style 继承（BasedOn）
✅ DataTemplate 隐式 + 显式
✅ ItemTemplate 应用
✅ ItemsPanel 改变布局（WrapPanel）
✅ DropShadowEffect（特效）
✅ Converter 在模板里（StatusToColor / StatusToText）

观察：
 - 改 Style 不改业务逻辑
 - 同一个 ViewModel + 不同 Style = 完全不同 UI
 - 这是 WPF "设计 vs 开发"分离的体现

十、Theme 与 Generic.xaml

10.1 主题样式

1
2
3
4
5
6


每个 WPF 控件都有"默认主题样式"
 - 来自 PresentationFramework.Aero2.dll（Windows 10 默认主题）
 - 包含 ControlTemplate、Trigger
 - 是"没写 Style 时的样子"

 你写 Style TargetType="Button"（隐式）会覆盖主题样式

10.2 Generic.xaml（自定义控件的主题）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


自定义 CustomControl 时：
 - 创建 Themes/Generic.xaml
 - 里面写控件的默认 ControlTemplate
 - WPF 自动加载（约定）

文件结构：
 MyControlLibrary/
 ├── MyButton.cs
 └── Themes/
 └── Generic.xaml ← 约定路径

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<!-- Generic.xaml -->
<ResourceDictionary xmlns="...">
 <Style TargetType="{x:Type local:MyButton}">
 <Setter Property="Template">
 <Setter.Value>
 <ControlTemplate TargetType="{x:Type local:MyButton}">
 <!-- 模板 -->
 </ControlTemplate>
 </Setter.Value>
 </Setter>
 </Style>
</ResourceDictionary>

十一、常见陷阱

11.1 StaticResource 引用顺序

1
2
3
4
5
6
7
8


<!-- ❌ 资源定义在使用之后 -->
<Button Background="{StaticResource bg}"/>
<SolidColorBrush x:Key="bg" Color="Red"/>
<!-- 报错：找不到 bg -->

<!-- ✅ 先定义后使用 -->
<SolidColorBrush x:Key="bg" Color="Red"/>
<Button Background="{StaticResource bg}"/>

1
2
3
4
5


StaticResource 是"前向查找"，定义必须在前面
但同一 Resources 字典内不分先后（解析时全收集）
跨字典才要求顺序

DynamicResource 没此限制（运行时查）

11.2 隐式样式对派生类不生效

1
2
3
4
5
6
7


<Style TargetType="Button">
 <Setter Property="Background" Value="Red"/>
</Style>

<RepeatButton Content="..."/>
<!-- RepeatButton 继承自 ButtonBase，不是 Button -->
<!-- 不会应用上面的隐式样式 -->

11.3 ControlTemplate 缺 ContentPresenter

1
2
3
4
5


<ControlTemplate TargetType="Button">
 <Border Background="Red"/>
 <!-- ❌ 没 ContentPresenter -->
 <!-- Button.Content 没地方放，不显示 -->
</ControlTemplate>

11.4 Trigger 和本地值冲突

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<Style TargetType="Button">
 <Style.Triggers>
 <Trigger Property="IsMouseOver" Value="True">
 <Setter Property="Background" Value="Red"/>
 </Trigger>
 </Style.Triggers>
</Style>

<!-- 本地值（XAML 直接设置）覆盖 Style.Trigger -->
<Button Background="Blue"/>
<!-- 鼠标悬停不会变红！ -->

1
2
3
4
5
6


原因：
 本地值 > Style.Trigger（详见第 2 篇优先级）
 Trigger 永远赢不了本地值

解决：
 把 Background="Blue" 也写到 Style 里

11.5 大量 Trigger 性能问题

1
2
3
4
5


<!-- ❌ 每个 Item 都有自己的 Trigger + 复杂 ControlTemplate -->
<ListBox ItemsSource="{Binding Items}"/>
<!-- 1000 个 Item × 复杂模板 = 慢 -->

<!-- ✅ 简化模板 + 虚拟化 -->

十二、与 CSS / Razor 的对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


CSS WPF Style
──────────────────────────────────────────
.class { color: red } <Style TargetType><Setter Property="Foreground" Value="Red"/>
:hover <Trigger Property="IsMouseOver" Value="True">
@media (theme) DynamicResource + 切换 ResourceDictionary
inheritance BasedOn

Razor Layout WPF ControlTemplate
──────────────────────────────────────────
_Layout.cshtml ControlTemplate
@RenderBody() <ContentPresenter/>
@RenderSection() ItemPresenter / ContentPresenter

Razor DisplayTemplate WPF DataTemplate
──────────────────────────────────────────
DisplayTemplates/ <DataTemplate DataType=...>
按类型选模板 隐式 DataTemplate
@Html.DisplayForModel() ItemsControl 自动用 DataTemplate

十三、小结

本文深入 WPF 的样式与模板系统：

ResourceDictionary 资源系统与查找链
StaticResource vs DynamicResource（编译期 vs 运行期）
Style（属性批处理）+ 隐式样式 + BasedOn 继承
Trigger 全家桶（Property / Multi / Event / Data / MultiData）
ControlTemplate（彻底重画控件外观）
- TemplateBinding + ContentPresenter
DataTemplate（决定数据呈现）
- 显式 ItemTemplate + 隐式 DataType
VisualStateManager（VSM）vs Trigger
实战：Material Button + 卡片 ListBox
Theme 与 Generic.xaml（自定义控件主题）

1
2
3
4


记住三句话：
 1. Style 改属性，ControlTemplate 改结构，DataTemplate 改数据呈现
 2. ContentPresenter 是 ControlTemplate 的"洞"，TemplateBinding 是"接原控件属性"
 3. DynamicResource + 切换 ResourceDictionary = 一键换肤

下一篇进入 WPF 的多线程模型——Dispatcher 与 UI 线程。这是后端工程师最容易踩坑的地方（async/await 行为和 ASP.NET Core 不同）。

WPF 学习笔记（七）：MVVM 工程化与依赖注入

Wed, 13 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS + CommunityToolkit.Mvvm 8.2+ + Microsoft.Extensions.DependencyInjection 8.0。

承接上一篇命令系统。前面学了 ICommand 和 CommunityToolkit.Mvvm 的源生成器，本篇把它们落到工程实践——怎么组织项目、怎么集成 DI、怎么处理导航和对话框这些"基础设施"问题。

本篇之后，你应该能从零搭建一个"工业级"的 WPF 项目骨架。

本文要回答：

View 和 ViewModel 怎么连？WPF 怎么集成 Microsoft.Extensions.DependencyInjection？对话框、导航、消息这些跨 View 通信怎么处理？

一、MVVM 三层职责

1.1 三层定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Model：
 - 业务实体（领域模型）
 - 数据访问（Repository / Service）
 - 纯业务逻辑，不依赖 UI

ViewModel：
 - View 的"抽象"
 - 暴露属性 + 命令（绑定用）
 - 调用 Model 层的服务
 - 不持有 View 引用

View：
 - XAML + 极少 code-behind
 - 只负责显示和绑定
 - 不写业务逻辑

1.2 数据流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 用户操作 UI
 ↓
 View 触发绑定（Command）
 ↓
 ViewModel.Execute
 ↓
 Service（业务逻辑）
 ↓
 Model（持久化）
 ↓
 Service 返回数据
 ↓
 ViewModel 更新属性（INPC）
 ↓
 View 通过绑定自动更新

1
2
3
4
5
6
7


关键约束：
 - View 不知道 Model 存在
 - ViewModel 不知道 View 存在
 - Model 不知道 ViewModel / View 存在

 依赖方向：View → ViewModel → Service → Model
 反向：通过事件 / 回调 / 消息机制

1.3 与 MVC / MVP 对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


MVC（ASP.NET Core）：
 Controller 接收请求 → 调 Model → 返回 View
 View 渲染 → HTML 发给客户端
 → 服务端模式（无状态）

MVP（WinForms 经典）：
 View 持有 Presenter
 Presenter 监听 View 事件，更新 View
 → 双向依赖（紧耦合）

MVVM（WPF）：
 ViewModel 暴露属性 + 命令
 View 通过"绑定"自动同步
 ViewModel 不持有 View
 → 单向依赖（解耦）

 WPF 绑定是 MVVM 能成立的基础
 → 没绑定，MVVM 做不到（所以 WinForms 用 MVP）

二、View ↔ ViewModel 的连接方式

2.1 方式一：XAML 设置 DataContext

1
2
3


<Window.DataContext>
 <local:MainViewModel/>
</Window.DataContext>

1
2
3
4
5


优点：简单、声明式
缺点：
 - ViewModel 必须有无参构造
 - 不能注入服务
 - 不利于测试

2.2 方式二：Code-behind 设置

1
2
3
4
5


public MainWindow()
{
 InitializeComponent();
 DataContext = new MainViewModel();
}

2.3 方式三：DataTemplate 隐式映射（推荐用于多视图）

1
2
3
4
5
6
7
8
9


<!-- App.xaml -->
<Application.Resources>
 <DataTemplate DataType="{x:Type vm:MainViewModel}">
 <views:MainView/>
 </DataTemplate>
 <DataTemplate DataType="{x:Type vm:SettingsViewModel}">
 <views:SettingsView/>
 </DataTemplate>
</Application.Resources>

1
2


<!-- 主窗口只放一个 ContentControl -->
<ContentControl Content="{Binding CurrentView}"/>

1
2
3
4
5
6


效果：
 - CurrentView 是 ViewModel 类型
 - WPF 根据 DataTemplate 自动选对应 View
 - 切换 CurrentView 就切换界面

 这是"导航"的标准模式（详见第 5 节）

2.4 方式四：ViewModelLocator（旧模式）

1
2
3
4
5


// 全局服务定位器
public class ViewModelLocator
{
 public MainViewModel Main => App.Services.GetRequiredService<MainViewModel>();
}

1
2
3


<Window.DataContext>
 <Binding Path="Main" Source="{StaticResource Locator}"/>
</Window.DataContext>

1
2


现在通常被 DI + DataTemplate 替代
了解即可

三、Microsoft.Extensions.DependencyInjection 集成

WPF 完全可以用 ASP.NET Core 同款 DI 容器。

3.1 项目结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


MyApp/
├── App.xaml
├── App.xaml.cs ← DI 入口
├── Views/
│ ├── MainWindow.xaml
│ ├── MainWindow.xaml.cs
│ ├── TodoItemView.xaml
│ └── ...
├── ViewModels/
│ ├── MainViewModel.cs
│ ├── TodoItemViewModel.cs
│ └── ...
├── Services/
│ ├── ITodoService.cs
│ ├── TodoService.cs
│ ├── IDialogService.cs
│ └── DialogService.cs
├── Models/
│ └── TodoItem.cs
└── ContainerConfiguration.cs ← DI 注册

3.2 App.xaml.cs 注入

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


public partial class App : Application
{
 public static IServiceProvider Services { get; private set; }

 protected override void OnStartup(StartupEventArgs e)
 {
 base.OnStartup(e);

 // 1. 配置 DI
 var services = new ServiceCollection();
 ConfigureServices(services);
 Services = services.BuildServiceProvider();

 // 2. 解析主窗口（自动注入 MainViewModel）
 var mainWindow = Services.GetRequiredService<MainWindow>();
 mainWindow.Show();
 }

 private static void ConfigureServices(IServiceCollection services)
 {
 // 服务
 services.AddSingleton<ITodoService, TodoService>();
 services.AddSingleton<IDialogService, DialogService>();
 services.AddSingleton<INavigationService, NavigationService>();

 // ViewModel
 services.AddSingleton<MainViewModel>();
 services.AddTransient<TodoItemViewModel>();

 // 窗口
 services.AddSingleton<MainWindow>();
 }
}

1
2
3
4
5
6
7


关键点：
 - 注意 App.xaml 里的 StartupUri 要去掉（改为 OnStartup 手动显示）
 - 注册顺序不重要（DI 自动解析依赖）
 - 单例（Singleton）vs 瞬态（Transient）vs 作用域（Scoped）
 * Singleton：全局唯一（适合服务、主 ViewModel）
 * Transient：每次 new（适合短生命周期 ViewModel）
 * Scoped：WPF 较少用（无 HTTP 请求边界）

3.3 删除 StartupUri

1
2
3
4
5
6
7
8
9


<!-- App.xaml -->
<Application x:Class="MyApp.App"
 xmlns="..."
 xmlns:x="..."
 ><!-- ← 不要 StartupUri -->
 <Application.Resources>
 <!-- DataTemplate 隐式映射 -->
 </Application.Resources>
</Application>

3.4 MainWindow 接收 ViewModel

1
2
3
4
5
6
7
8


public partial class MainWindow : Window
{
 public MainWindow(MainViewModel viewModel)
 {
 InitializeComponent();
 DataContext = viewModel;
 }
}

1
2
3


DI 解析 MainWindow → 看到构造需要 MainViewModel → 解析 MainViewModel
→ MainViewModel 构造需要 ITodoService → 解析 TodoService
→ 全部注入完成

四、ViewModel 接收服务

4.1 构造函数注入（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


public partial class MainViewModel : ObservableObject
{
 private readonly ITodoService _todoService;
 private readonly IDialogService _dialogService;

 public MainViewModel(ITodoService todoService, IDialogService dialogService)
 {
 _todoService = todoService;
 _dialogService = dialogService;
 LoadCommand = new RelayCommand(Load);
 }

 public ObservableCollection<TodoItem> Todos { get; } = new();
 public ICommand LoadCommand { get; }

 private async void Load()
 {
 var items = await _todoService.GetAllAsync();
 Todos.Clear();
 foreach (var item in items) Todos.Add(item);
 }
}

1
2
3
4
5
6
7
8


优点：
 - 依赖明确（构造签名就是依赖列表）
 - 易测试（mock 服务注入）
 - 编译期检查依赖

缺点：
 - 依赖多了构造函数参数多
 - 但这是"好"的复杂度（强迫你思考）

4.2 服务定位器（不推荐）

1
2
3
4


public MainViewModel()
{
 _todoService = App.Services.GetRequiredService<ITodoService>();
}

1
2
3
4


为什么不好：
 - 隐藏依赖
 - 难测试（依赖全局静态 Services）
 - 容易循环依赖

五、导航服务

WPF 的"导航"通常用 ContentControl + DataTemplate 切换。

5.1 接口定义

1
2
3
4
5
6


public interface INavigationService
{
 ViewModelBase CurrentViewModel { get; }
 event Action CurrentViewModelChanged;
 void NavigateTo<TViewModel>() where TViewModel : ViewModelBase;
}

5.2 实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


public class NavigationService : INavigationService, ObservableObject
{
 private readonly IServiceProvider _services;
 private ViewModelBase _currentViewModel;

 public NavigationService(IServiceProvider services)
 {
 _services = services;
 }

 public ViewModelBase CurrentViewModel
 {
 get => _currentViewModel;
 private set => SetProperty(ref _currentViewModel, value);
 }

 public event Action CurrentViewModelChanged;

 public void NavigateTo<TViewModel>() where TViewModel : ViewModelBase
 {
 // 从 DI 解析 ViewModel
 CurrentViewModel = _services.GetRequiredService<TViewModel>();
 CurrentViewModelChanged?.Invoke();
 }
}

5.3 使用

1
2
3
4
5
6
7
8
9


<!-- App.xaml 注册 DataTemplate -->
<Application.Resources>
 <DataTemplate DataType="{x:Type vm:HomeViewModel}">
 <views:HomeView/>
 </DataTemplate>
 <DataTemplate DataType="{x:Type vm:SettingsViewModel}">
 <views:SettingsView/>
 </DataTemplate>
</Application.Resources>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<!-- MainWindow -->
<Grid>
 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="200"/>
 <ColumnDefinition Width="*"/>
 </Grid.ColumnDefinitions>

 <StackPanel Grid.Column="0">
 <Button Content="主页" Command="{Binding NavigateHomeCommand}"/>
 <Button Content="设置" Command="{Binding NavigateSettingsCommand}"/>
 </StackPanel>

 <!-- 关键：ContentControl 绑定到当前 ViewModel -->
 <ContentControl Grid.Column="1" Content="{Binding Navigation.CurrentViewModel}"/>
</Grid>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public partial class MainViewModel : ObservableObject
{
 private readonly INavigationService _navigation;

 public MainViewModel(INavigationService navigation)
 {
 _navigation = navigation;
 NavigateHomeCommand = new RelayCommand(() => _navigation.NavigateTo<HomeViewModel>());
 NavigateSettingsCommand = new RelayCommand(() => _navigation.NavigateTo<SettingsViewModel>());
 }

 public INavigationService Navigation => _navigation;
 public ICommand NavigateHomeCommand { get; }
 public ICommand NavigateSettingsCommand { get; }
}

六、对话框服务

ViewModel 不能直接 MessageBox.Show（破坏 MVVM）。

6.1 抽象接口

1
2
3
4
5
6


public interface IDialogService
{
 void ShowMessage(string message, string title = "提示");
 bool ShowConfirm(string message, string title = "确认");
 Task<string> ShowInputAsync(string prompt, string defaultValue = "");
}

6.2 实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


public class DialogService : IDialogService
{
 public void ShowMessage(string message, string title = "提示")
 => MessageBox.Show(message, title, MessageBoxButton.OK, MessageBoxImage.Information);

 public bool ShowConfirm(string message, string title = "确认")
 => MessageBox.Show(message, title, MessageBoxButton.YesNo, MessageBoxImage.Question) == MessageBoxResult.Yes;

 public async Task<string> ShowInputAsync(string prompt, string defaultValue = "")
 {
 // 简化：用 InputBox 风格的自定义窗口
 var dialog = new InputDialog(prompt, defaultValue);
 if (dialog.ShowDialog() == true)
 return dialog.InputValue;
 return null;
 }
}

6.3 ViewModel 使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


[RelayCommand]
private async Task DeleteAsync(TodoItem item)
{
 if (item == null) return;

 if (_dialogService.ShowConfirm($"确定删除 {item.Title}？"))
 {
 await _todoService.DeleteAsync(item.Id);
 Todos.Remove(item);
 _dialogService.ShowMessage("删除成功");
 }
}

1
2
3
4


好处：
 - ViewModel 不直接依赖 MessageBox
 - 单元测试可以 mock IDialogService
 - 想换"自定义漂亮对话框"，只改 DialogService

七、ViewModel 间通信

7.1 Messager 模式（CommunityToolkit.Mvvm）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


public class TodoDeletedMessage : ValueChangedMessage<TodoItem>
{
 public TodoDeletedMessage(TodoItem item) : base(item) { }
}

// 发送
public partial class TodoListViewModel : ObservableObject
{
 [RelayCommand]
 private void Delete(TodoItem item)
 {
 WeakReferenceMessenger.Default.Send(new TodoDeletedMessage(item));
 }
}

// 接收
public partial class SummaryViewModel : ObservableObject
{
 public SummaryViewModel()
 {
 WeakReferenceMessenger.Default.Register<TodoDeletedMessage>(this, (r, m) =>
 {
 // 处理消息
 UpdateSummary(m.Value);
 });
 }
}

7.2 弱事件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


WeakReferenceMessenger 的关键：
 - 弱引用持有接收者
 - 接收者被 GC 回收，自动取消订阅
 - 不会内存泄漏

vs 普通 C# event：
 - event 强引用
 - 不取消订阅会泄漏

何时用：
 - ViewModel 间广播（多对多）
 - 跨层级事件
 - 不适合：父子 ViewModel 直接通信（直接方法调用更清晰）

7.3 事件聚合器（Prism 的等价物）

如果用 Prism，类似叫 IEventAggregator。Toolkit 的 WeakReferenceMessenger 是更轻量的实现。

八、集合的 MVVM

8.1 ObservableCollection 替代 List

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public partial class TodoListViewModel : ObservableObject
{
 public ObservableCollection<TodoItem> Todos { get; } = new();

 [RelayCommand]
 private async Task LoadAsync()
 {
 var items = await _todoService.GetAllAsync();
 Todos.Clear();
 foreach (var item in items) Todos.Add(item);
 }
}

8.2 后台线程加载数据

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


[RelayCommand]
private async Task LoadAsync()
{
 // 后台线程获取数据
 var items = await _todoService.GetAllAsync();

 // ObservableCollection 的 Add 必须在 UI 线程
 // 但 await 之后已经在 UI 线程（SynchronizationContext）
 Todos.Clear();
 foreach (var item in items) Todos.Add(item);
}

// 或者：跨线程同步
private readonly object _lock = new();
public ObservableCollection<TodoItem> Todos { get; }

public TodoListViewModel()
{
 Todos = new ObservableCollection<TodoItem>();
 BindingOperations.EnableCollectionSynchronization(Todos, _lock);
}

8.3 增量更新 vs 整体替换

1
2
3
4
5
6


// ❌ 性能差：每次 Clear + Add 触发多次通知
Todos.Clear();
foreach (var item in items) Todos.Add(item);

// ✅ 性能好：单次 Reset
Todos = new ObservableCollection<TodoItem>(items); // 整体替换（要 OnPropertyChanged）

九、设计时数据

让 XAML 设计器显示示例数据，而不是空白。

9.1 d:DataContext

1
2
3


<Window xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
 d:DataContext="{d:DesignInstance Type=local:MainViewModel,
 IsDesignTimeCreatable=True}">

1
2
3
4
5
6
7
8
9


// MainViewModel 设计时构造（提供示例数据）
public MainViewModel()
{
 if (DesignerProperties.GetIsInDesignMode(new DependencyObject()))
 {
 Todos.Add(new TodoItem { Title = "示例任务", Completed = false });
 Todos.Add(new TodoItem { Title = "另一个任务", Completed = true });
 }
}

9.2 d:DesignData

1

<Window d:DataContext="{d:DesignData Source=SampleData.xaml}">

1
2
3
4
5
6


好处：
 - VS/Blend 设计器立即显示效果
 - 不需要运行就能看到 UI 布局
 - 设计师友好

实际编译时 d: 前缀的内容会被忽略

十、实战：TodoApp 完整工程

把全部组合起来。

10.1 项目结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


TodoApp/
├── App.xaml / App.xaml.cs
├── Models/TodoItem.cs
├── Services/
│ ├── ITodoService.cs
│ ├── InMemoryTodoService.cs
│ ├── IDialogService.cs
│ ├── DialogService.cs
│ └── INavigationService.cs
├── ViewModels/
│ ├── ViewModelBase.cs
│ ├── MainViewModel.cs
│ ├── HomeViewModel.cs
│ └── SettingsViewModel.cs
└── Views/
 ├── MainWindow.xaml / .cs
 ├── HomeView.xaml
 ├── SettingsView.xaml
 └── Controls (TodoItemView.xaml)

10.2 Model

1
2
3
4
5
6
7


public class TodoItem
{
 public int Id { get; set; }
 public string Title { get; set; }
 public bool Completed { get; set; }
 public DateTime CreatedAt { get; set; }
}

10.3 Service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


public interface ITodoService
{
 Task<List<TodoItem>> GetAllAsync();
 Task<TodoItem> AddAsync(string title);
 Task DeleteAsync(int id);
 Task ToggleAsync(int id);
}

public class InMemoryTodoService : ITodoService
{
 private readonly List<TodoItem> _items = new();
 private int _nextId = 1;

 public Task<List<TodoItem>> GetAllAsync() => Task.FromResult(_items.ToList());

 public Task<TodoItem> AddAsync(string title)
 {
 var item = new TodoItem
 {
 Id = _nextId++,
 Title = title,
 CreatedAt = DateTime.Now
 };
 _items.Add(item);
 return Task.FromResult(item);
 }

 public Task DeleteAsync(int id)
 {
 _items.RemoveAll(x => x.Id == id);
 return Task.CompletedTask;
 }

 public Task ToggleAsync(int id)
 {
 var item = _items.FirstOrDefault(x => x.Id == id);
 if (item != null) item.Completed = !item.Completed;
 return Task.CompletedTask;
 }
}

10.4 ViewModel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82


public abstract class ViewModelBase : ObservableObject { }

public partial class HomeViewModel : ViewModelBase
{
 private readonly ITodoService _todoService;
 private readonly IDialogService _dialogService;

 public ObservableCollection<TodoItem> Todos { get; } = new();

 [ObservableProperty]
 private string _newTodoTitle = "";

 public HomeViewModel(ITodoService todoService, IDialogService dialogService)
 {
 _todoService = todoService;
 _dialogService = dialogService;
 _ = LoadAsync();
 }

 [RelayCommand]
 private async Task LoadAsync()
 {
 var items = await _todoService.GetAllAsync();
 Todos.Clear();
 foreach (var item in items) Todos.Add(item);
 }

 [RelayCommand(CanExecute = nameof(CanAdd))]
 private async Task AddAsync()
 {
 var item = await _todoService.AddAsync(NewTodoTitle);
 Todos.Add(item);
 NewTodoTitle = "";
 }

 private bool CanAdd() => !string.IsNullOrWhiteSpace(NewTodoTitle);

 [RelayCommand]
 private async Task DeleteAsync(TodoItem item)
 {
 if (item == null) return;
 if (_dialogService.ShowConfirm($"删除 \"{item.Title}\"？"))
 {
 await _todoService.DeleteAsync(item.Id);
 Todos.Remove(item);
 }
 }

 [RelayCommand]
 private async Task ToggleAsync(TodoItem item)
 {
 if (item == null) return;
 await _todoService.ToggleAsync(item.Id);
 item.Completed = !item.Completed;
 }

 partial void OnNewTodoTitleChanged(string value)
 => AddCommand.NotifyCanExecuteChanged();
}

public partial class SettingsViewModel : ViewModelBase
{
 [ObservableProperty]
 private bool _confirmOnDelete = true;

 [ObservableProperty]
 private bool _autoSave = true;
}

public partial class MainViewModel : ViewModelBase
{
 public INavigationService Navigation { get; }

 public MainViewModel(INavigationService navigation)
 {
 Navigation = navigation;
 Navigation.NavigateTo<HomeViewModel>();
 }

 [RelayCommand] private void GoHome() => Navigation.NavigateTo<HomeViewModel>();
 [RelayCommand] private void GoSettings() => Navigation.NavigateTo<SettingsViewModel>();
}

10.5 App + DI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


public partial class App : Application
{
 public static IServiceProvider Services { get; private set; }

 protected override void OnStartup(StartupEventArgs e)
 {
 base.OnStartup(e);

 var services = new ServiceCollection();
 ConfigureServices(services);
 Services = services.BuildServiceProvider();

 var mainWindow = Services.GetRequiredService<MainWindow>();
 mainWindow.Show();
 }

 private void ConfigureServices(IServiceCollection services)
 {
 services.AddSingleton<ITodoService, InMemoryTodoService>();
 services.AddSingleton<IDialogService, DialogService>();
 services.AddSingleton<INavigationService, NavigationService>();

 services.AddSingleton<MainViewModel>();
 services.AddTransient<HomeViewModel>();
 services.AddTransient<SettingsViewModel>();

 services.AddSingleton<MainWindow>();
 }
}

10.6 XAML（精简）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


<!-- App.xaml -->
<Application.Resources>
 <DataTemplate DataType="{x:Type vm:HomeViewModel}">
 <views:HomeView/>
 </DataTemplate>
 <DataTemplate DataType="{x:Type vm:SettingsViewModel}">
 <views:SettingsView/>
 </DataTemplate>
</Application.Resources>

<!-- MainWindow.xaml -->
<Window x:Class="TodoApp.MainWindow"
 Title="TodoApp" Width="800" Height="500">
 <Grid>
 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="180"/>
 <ColumnDefinition Width="*"/>
 </Grid.ColumnDefinitions>

 <StackPanel Grid.Column="0" Background="#F0F0F0">
 <Button Content="主页" Command="{Binding GoHomeCommand}" Margin="8"/>
 <Button Content="设置" Command="{Binding GoSettingsCommand}" Margin="8"/>
 </StackPanel>

 <ContentControl Grid.Column="1" Content="{Binding Navigation.CurrentViewModel}"/>
 </Grid>
</Window>

<!-- HomeView.xaml -->
<UserControl xmlns="...">
 <Grid Margin="12">
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="*"/>
 </Grid.RowDefinitions>

 <StackPanel Grid.Row="0" Orientation="Horizontal" Margin="0,0,0,8">
 <TextBox Width="300" Text="{Binding NewTodoTitle, UpdateSourceTrigger=PropertyChanged}"/>
 <Button Content="添加" Command="{Binding AddCommand}" Margin="8,0,0,0"/>
 </StackPanel>

 <ListBox Grid.Row="1" ItemsSource="{Binding Todos}">
 <ListBox.ItemTemplate>
 <DataTemplate>
 <Grid Margin="4">
 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="30"/>
 <ColumnDefinition Width="*"/>
 <ColumnDefinition Width="Auto"/>
 </Grid.ColumnDefinitions>
 <CheckBox Grid.Column="0" IsChecked="{Binding Completed}"/>
 <TextBlock Grid.Column="1" Text="{Binding Title}"/>
 <Button Grid.Column="2" Content="✕"
 Command="{Binding DataContext.DeleteCommand,
 RelativeSource={RelativeSource AncestorType=UserControl}}"
 CommandParameter="{Binding}"/>
 </Grid>
 </DataTemplate>
 </ListBox.ItemTemplate>
 </ListBox>
 </Grid>
</UserControl>

10.7 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


✅ MVVM 三层（Model / ViewModel / View）
✅ DI 容器集成（Microsoft.Extensions.DependencyInjection）
✅ ViewModel 构造函数注入服务
✅ ContentControl + DataTemplate 导航
✅ INavigationService 抽象导航
✅ IDialogService 抽象对话框
✅ ObservableCollection + 异步加载
✅ CommandParameter 传参（Delete item）
✅ 相对源绑定（AncestorType=UserControl 找 ViewModel）
✅ [ObservableProperty] + [RelayCommand]
✅ partial 钩子（OnNewTodoTitleChanged 通知 CanExecute）

观察：
 - 完全无业务 code-behind
 - ViewModel 可单元测试（mock ITodoService / IDialogService）
 - 导航切换是数据驱动（改 ViewModel，UI 自动切）

十一、单元测试

MVVM 的最大收益之一。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


[Fact]
public async Task AddAsync_WithValidTitle_AddsToCollection()
{
 // Arrange
 var todoService = new Mock<ITodoService>();
 todoService.Setup(s => s.AddAsync("New task"))
 .ReturnsAsync(new TodoItem { Id = 1, Title = "New task" });

 var dialogService = new Mock<IDialogService>();
 var vm = new HomeViewModel(todoService.Object, dialogService.Object);
 vm.NewTodoTitle = "New task";

 // Act
 await vm.AddCommand.ExecuteAsync(null);

 // Assert
 Assert.Single(vm.Todos);
 Assert.Equal("New task", vm.Todos[0].Title);
 Assert.Equal("", vm.NewTodoTitle);
}

[Fact]
public void AddCommand_CannotExecute_WhenTitleEmpty()
{
 var vm = new HomeViewModel(Mock.Of<ITodoService>(), Mock.Of<IDialogService>());
 vm.NewTodoTitle = "";

 Assert.False(vm.AddCommand.CanExecute(null));
}

1
2


没有 UI、没有 MessageBox、没有视觉树
完全纯 .NET 测试 → 快、稳、可 CI

十二、常见陷阱

12.1 ViewModel 持有 View 引用

1
2
3
4
5


// ❌ ViewModel 直接拿 Window
public class MainViewModel
{
 private readonly MainWindow _window; // 反模式！
}

1
2
3
4


为什么不行：
 - ViewModel 不应该知道 View 存在
 - 一旦依赖 View，无法跨 View 复用 ViewModel
 - 单元测试要 mock View，复杂

12.2 code-behind 写业务

1
2
3
4
5
6


// ❌ Button.Click 在 code-behind 里写业务
private void SaveButton_Click(...)
{
 if (string.IsNullOrEmpty(nameBox.Text)) return;
 _service.Save(nameBox.Text);
}

1
2
3


✅ 用 Command + Binding
SaveCommand 处理业务逻辑
nameBox.Text 绑定到 ViewModel.Name

12.3 服务注册遗漏

1
2
3


services.AddSingleton<MainViewModel>();
// ❌ 忘了注册 ITodoService
// 解析 MainViewModel 时报错

12.4 Singleton ViewModel 的状态泄漏

1
2
3
4
5
6


// Singleton 的 HomeViewModel 全局唯一
// → Todos 集合在所有"主页"间共享
// → 用户切换出去再回来，状态保留（这通常是你想要的）

// 但如果要"每次进入都新状态"，用 Transient
services.AddTransient<HomeViewModel>();

12.5 异步 void

1
2
3
4
5
6


// ❌ 异步 void 异常会崩溃
private async void Load() { ... }

// ✅ 异步 Task（命令内部）
[RelayCommand]
private async Task LoadAsync() { ... }

十三、与 ASP.NET Core 的对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


ASP.NET Core WPF MVVM
──────────────────────────────────────────────
Controller ViewModel
View (Razor) View (XAML)
Service Service（同样）
Repository Repository（同样）
DI Container DI Container（同样）
Middleware （WPF 无等价）
Route DataTemplate（隐式映射）
ModelState.IsValid INotifyDataErrorInfo
HttpClient HttpClient（同样）
Logger Logger（同样）

关键差异：
 - ASP.NET Core Controller 每请求新建
 - WPF ViewModel 通常 Singleton 或 Transient
 - ASP.NET Core 的 View 在服务端渲染
 - WPF 的 View 在客户端常驻 + 绑定

后端工程师视角：
 ViewModel = Controller（一个屏幕一个）
 Service = Application Service / Domain Service
 View = Razor Page（绑定模型字段）

十四、小结

本文把 MVVM 落到工程实践：

MVVM 三层职责与单向依赖
View ↔ ViewModel 的四种连接方式
Microsoft.Extensions.DependencyInjection 集成 WPF
ViewModel 构造函数注入服务
导航服务（ContentControl + DataTemplate）
对话框服务（IDialogService 抽象）
ViewModel 间通信（WeakReferenceMessenger）
设计时数据（d:DataContext）
实战：TodoApp 完整工程
单元测试 ViewModel

1
2
3
4


记住三句话：
 1. ViewModel 永远不知道 View 存在——这是 MVVM 的红线
 2. DI 容器在 WPF 用法和 ASP.NET Core 一样——直接搬过来
 3. ContentControl + DataTemplate 是导航的标准武器——别用 Window.Show

下一篇进入 WPF 的"换肤"机制——样式与模板。ResourceDictionary、Style、ControlTemplate、DataTemplate、Trigger 全家桶。

WPF 学习笔记（六）：命令系统与 CommunityToolkit.Mvvm

Sat, 09 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS + CommunityToolkit.Mvvm 8.2+。

承接上一篇数据绑定。绑定解决了"显示同步"，但用户点击按钮、敲键盘这些"操作"怎么处理？传统做法是写 Button.Click += Handler——但这把 UI 和业务逻辑焊死了。WPF 给的答案是命令（Command）。

本篇聚焦命令系统本身和 CommunityToolkit.Mvvm 的源生成器——下一章把 MVVM 落到完整工程实践。

本文要回答：

ICommand 接口在干嘛？为什么 [ObservableProperty] 一个特性就能替代 30 行 INPC 样板代码？源生成器到底生成了什么？

一、为什么不用事件而用命令

1.1 事件的问题

1
2
3
4
5
6
7


// 传统事件
button.Click += OnButtonClick;

private void OnButtonClick(object sender, RoutedEventArgs e)
{
 // 业务逻辑
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


问题：
 1. UI 和逻辑耦合
 → 这段代码必须在 Window 类里（事件源是 button）
 → 不能放到独立的 ViewModel

 2. 无法"自动禁用"
 → 业务规则"未输入用户名时不能提交"
 → 要手写 button.IsEnabled = !string.IsNullOrEmpty(...)
 → 规则一变要改多处

 3. 难以复用
 → 同一个"保存"操作，可能在按钮、菜单、快捷键触发
 → 事件要分别挂

 4. 难以测试
 → 单元测试要 mock Window，复杂

后端类比：
 事件 = WinForms 思路（UI 直接挂逻辑）
 命令 = MVC 的 Controller Action（UI 调用业务命令）

1.2 命令的解决思路

1
2
3
4
5


// ViewModel 暴露命令
public ICommand SaveCommand { get; }

// XAML 绑定
<Button Content="保存" Command="{Binding SaveCommand}"/>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


好处：
 1. UI 和逻辑解耦
 → ViewModel 提供 ICommand
 → View 绑定即可
 → 同一个命令绑定到按钮、菜单、快捷键都行

 2. 自动启用/禁用
 → ICommand.CanExecute 决定按钮是否可用
 → CanExecute 变化自动通知 UI

 3. 可测试
 → 单元测试直接调 SaveCommand.Execute()
 → 不需要 UI

二、ICommand 接口

2.1 接口定义

1
2
3
4
5
6


public interface ICommand
{
 void Execute(object parameter); // 执行操作
 bool CanExecute(object parameter); // 是否可执行
 event EventHandler CanExecuteChanged; // 可执行状态变化
}

2.2 三个成员的语义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Execute(parameter)：
 → 真正执行业务逻辑
 → UI 触发命令时调用
 → parameter 来自 CommandParameter（XAML 可设）

CanExecute(parameter)：
 → 返回 true/false
 → true：UI 控件启用；false：UI 控件灰掉
 → 频繁调用（每次 CanExecuteChanged 都会查）

CanExecuteChanged：
 → 事件，告诉 UI"快重新查 CanExecute"
 → 触发后 UI 调 CanExecute
 → 通常转订阅 CommandManager.RequerySuggested（自动触发）

2.3 一个简单的实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


public class RelayCommand : ICommand
{
 private readonly Action _execute;
 private readonly Func<bool> _canExecute;

 public RelayCommand(Action execute, Func<bool> canExecute = null)
 {
 _execute = execute ?? throw new ArgumentNullException(nameof(execute));
 _canExecute = canExecute;
 }

 public bool CanExecute(object parameter) => _canExecute?.Invoke() ?? true;

 public void Execute(object parameter) => _execute();

 // 关键：转订阅 CommandManager
 public event EventHandler CanExecuteChanged
 {
 add => CommandManager.RequerySuggested += value;
 remove => CommandManager.RequerySuggested -= value;
 }
}

2.4 使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public class MainViewModel
{
 public string UserName { get; set; }

 public ICommand SaveCommand { get; }

 public MainViewModel()
 {
 SaveCommand = new RelayCommand(
 execute: () => MessageBox.Show($"Saving {UserName}"),
 canExecute: () => !string.IsNullOrEmpty(UserName));
 }
}

1
2
3


<TextBox Text="{Binding UserName, UpdateSourceTrigger=PropertyChanged}"/>
<Button Content="保存" Command="{Binding SaveCommand}"/>
<!-- UserName 为空时按钮自动灰掉 -->

三、CommandManager.RequerySuggested

这是 ICommand 的"自动重新评估"机制。

3.1 它在干什么

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


CommandManager.RequerySuggested 是一个全局事件
WPF 在某些时机自动触发它：
 - 用户输入（按键、点击）
 - 焦点变化
 - 鼠标移动
 - 鼠标空闲（每隔一段时间）

触发后：
 - 所有订阅 CanExecuteChanged 的命令重新调 CanExecute
 - UI 根据返回值刷新控件状态

3.2 优缺点

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


优点：
 - 写 ViewModel 不用关心"何时通知 CanExecute"
 - 系统自动重新评估

缺点：
 - 性能：全局事件，大量命令时频繁调用 CanExecute
 - 不精确：CanExecute 实际只依赖某几个属性，但每次都查
 - 延迟：依赖"空闲时刻"，不是属性变化的瞬间

CommunityToolkit.Mvvm 的 RelayCommand 不用 CommandManager
 → 用显式 NotifyCanExecuteChangedFor
 → 更精确，但要求 ViewModel 主动通知

四、RoutedCommand vs RelayCommand

WPF 内建一种 RoutedCommand，但和 MVVM 不太合。

4.1 RoutedCommand

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// 定义
public static readonly RoutedCommand SaveCommand =
 new RoutedCommand("Save", typeof(MyWindow));

// XAML 绑定
<Button Command="{x:Static local:MyWindow.SaveCommand}"/>

// 必须有 CommandBinding 处理
<Window.CommandBindings>
 <CommandBinding Command="{x:Static local:MyWindow.SaveCommand}"
 Executed="Save_Executed"
 CanExecute="Save_CanExecute"/>
</Window.CommandBindings>

private void Save_Executed(object sender, ExecutedRoutedEventArgs e) { ... }
private void Save_CanExecute(object sender, CanExecuteRoutedEventArgs e)
 => e.CanExecute = !string.IsNullOrEmpty(UserName);

4.2 RoutedCommand 的问题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


特点：
 - 命令是路由事件（沿视觉树传播）
 - CommandBinding 必须挂在视觉树某节点上
 - 处理逻辑在 code-behind（不在 ViewModel）

为什么和 MVVM 不合：
 → 命令逻辑要写在 View（code-behind）
 → ViewModel 不能直接处理命令
 → 等于又把 UI 和逻辑耦合了

适用场景：
 - ApplicationCommands.Copy/Cut/Paste（系统命令）
 - NavigationCommands（导航）
 - 这些"控件级"命令，RoutedCommand 更合适

业务命令：
 - 用 RelayCommand（或 CommunityToolkit 的 [RelayCommand]）
 - 命令在 ViewModel 里，可测试

4.3 对比

维度	RoutedCommand	RelayCommand
命令来源	静态定义	ViewModel 实例属性
处理位置	CommandBinding（视觉树）	ViewModel
是否路由	是（沿树）	否
CanExecute	CommandBinding 提供	闭包 / 方法
适合 MVVM	❌	✅
内建命令	ApplicationCommands	无（自己写或用 Toolkit）

五、CommunityToolkit.Mvvm 概览

微软出的现代 MVVM 库，零样板代码。

5.1 安装

1

<PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.2"/>

5.2 三个核心组件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


ObservableObject：
 → 实现 INPC 的基类
 → 提供 SetProperty<T>(ref field, value) 方法

[ObservableProperty] 特性：
 → 给 private 字段加，自动生成 public 属性 + INPC
 → 字段 _name → 属性 Name

[RelayCommand] 特性：
 → 给方法加，自动生成 ICommand 属性
 → 方法 Save() → 属性 SaveCommand

5.3 用法对比

传统写法（35 行）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


public class MainViewModel : INotifyPropertyChanged
{
 private string _userName;
 public string UserName
 {
 get => _userName;
 set
 {
 if (_userName != value)
 {
 _userName = value;
 OnPropertyChanged(nameof(UserName));
 OnPropertyChanged(nameof(CanSave));
 }
 }
 }

 public bool CanSave => !string.IsNullOrEmpty(UserName);

 public ICommand SaveCommand { get; }

 public MainViewModel()
 {
 SaveCommand = new RelayCommand(() => Save(), () => CanSave);
 }

 private void Save() { /* ... */ }

 public event PropertyChangedEventHandler PropertyChanged;
 protected void OnPropertyChanged(string name)
 => PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
}

Toolkit 写法（10 行）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public partial class MainViewModel : ObservableObject
{
 [ObservableProperty]
 private string _userName;

 [RelayCommand(CanExecute = nameof(CanSave))]
 private void Save() { /* ... */ }

 public bool CanSave => !string.IsNullOrEmpty(UserName);
}

1
2
3
4
5


关键观察：
 - 字段 _userName 自动变成属性 UserName（带 INPC）
 - 方法 Save() 自动变成 ICommand 属性 SaveCommand
 - UserName 变化时 CanSave 也会重新评估（通过 NotifyCanExecuteChangedFor）
 - 必须标 partial（源生成器要补充代码）

六、[ObservableProperty] 源生成器原理

这是 CommunityToolkit.Mvvm 最神奇的地方。理解了原理，使用时心里就有底。

6.1 输入

1
2
3
4
5


public partial class MainViewModel : ObservableObject
{
 [ObservableProperty]
 private string _userName;
}

6.2 生成的代码（简化）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// 自动生成的 MainViewModel.cs（实际在 obj/ 目录）
public partial class MainViewModel
{
 public string UserName
 {
 get => _userName;
 set
 {
 if (!EqualityComparer<string>.Default.Equals(_userName, value))
 {
 OnUserNameChanging(value);
 OnPropertyChanging(new PropertyChangingEventArgs("UserName")); // 之前
 _userName = value;
 OnPropertyChanged(new PropertyChangedEventArgs("UserName")); // 之后
 OnUserNameChanged(value);
 }
 }
 }

 // 可重写的 partial 方法（钩子）
 partial void OnUserNameChanging(string value);
 partial void OnUserNameChanged(string value);
}

6.3 字段命名约定

1
2
3
4
5
6


源生成器根据字段名生成属性名：
 _userName → UserName
 _userNameField → UserNameField
 m_userName → UserName

去掉前缀（_ / m_ / s_）+ 首字母大写

6.4 partial 方法钩子

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public partial class MainViewModel : ObservableObject
{
 [ObservableProperty]
 private int _age;

 // 钩子：属性变化前
 partial void OnAgeChanging(int value)
 {
 if (value < 0 || value > 150)
 throw new ArgumentOutOfRangeException(nameof(value));
 }

 // 钩子：属性变化后
 partial void OnAgeChanged(int value)
 {
 // 触发别的属性
 OnPropertyChanged(nameof(IsAdult));
 }

 public bool IsAdult => Age >= 18;
}

1
2
3
4
5
6
7


钩子名约定：
 On<PropertyName>Changing(T newValue)
 On<PropertyName>Changed(T newValue)
 On<PropertyName>Changing(T oldValue, T newValue)（可选 old）

不用写完整的 OnPropertyChanged 调用，框架已经做了
你只在钩子里写"额外副作用"

七、[RelayCommand] 源生成器

7.1 输入

1
2
3
4
5


public partial class MainViewModel : ObservableObject
{
 [RelayCommand]
 private void Save() { /* ... */ }
}

7.2 生成的代码（简化）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public partial class MainViewModel
{
 private RelayCommand? _saveCommand;

 public IRelayCommand SaveCommand
 {
 get => _saveCommand ??= new RelayCommand(Save);
 }

 // 原方法的 partial 包装（如果需要异步等）
}

1
2
3
4
5


命名约定：
 方法 Save() → 属性 SaveCommand（自动加 Command 后缀）

 这就是为什么 XAML 写：
 <Button Command="{Binding SaveCommand}"/>

7.3 带 CanExecute

1
2
3
4
5
6
7


public partial class MainViewModel : ObservableObject
{
 [RelayCommand(CanExecute = nameof(CanSave))]
 private void Save() { /* ... */ }

 private bool CanSave() => !string.IsNullOrEmpty(UserName);
}

生成：

1

public IRelayCommand SaveCommand { get; } // 内部用 CanSave 作判据

7.4 异步命令

1
2
3
4
5
6
7
8
9


public partial class MainViewModel : ObservableObject
{
 [RelayCommand]
 private async Task LoadDataAsync()
 {
 // await 异步操作
 await Task.Delay(1000);
 }
}

生成 IAsyncRelayCommand，UI 可以等执行完。

1
2
3
4


异步命令的特点：
 → 自动暴露 IsRunning（命令是否在执行）
 → 可绑到 UI 显示 loading
 → 自动防重入（执行中不能再次触发）

7.5 NotifyCanExecuteChangedFor（属性联动）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public partial class MainViewModel : ObservableObject
{
 [ObservableProperty]
 [NotifyCanExecuteChangedFor(nameof(SaveCommand))] // ← UserName 变了，重新评估 SaveCommand
 private string _userName;

 [RelayCommand(CanExecute = nameof(CanSave))]
 private void Save() { /* ... */ }

 public bool CanSave => !string.IsNullOrEmpty(UserName);
}

1
2
3
4
5
6
7
8
9


效果：
 UserName 变化 → 触发 INPC
 → 同时通知 SaveCommand.CanExecuteChanged
 → UI 重新调 CanSave → 刷新按钮启用状态

对比 CommandManager.RequerySuggested：
 Toolkit 方案精确（只在 UserName 变时刷新 SaveCommand）
 CommandManager 方案全局（每次空闲刷新所有命令）
 → Toolkit 性能更好，但要求显式声明依赖

八、ObservableObject 基类

8.1 三个基类

1
2
3
4
5
6
7


ObservableObject（CommunityToolkit.Mvvm）：
 → 实现 INotifyPropertyChanged + INotifyPropertyChanging
 → 提供 SetProperty<T>(ref field, value)

BindableBase（Prism）：类似

ViewModelBase（自己写）：手撸 INPC

8.2 SetProperty 方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


public abstract class ObservableObject : INotifyPropertyChanged, INotifyPropertyChanging
{
 public event PropertyChangedEventHandler? PropertyChanged;
 public event PropertyChangingEventHandler? PropertyChanging;

 protected bool SetProperty<T>(ref T field, T newValue, [CallerMemberName] string? propertyName = null)
 {
 if (EqualityComparer<T>.Default.Equals(field, newValue))
 return false;

 OnPropertyChanging(propertyName);
 field = newValue;
 OnPropertyChanged(propertyName);
 return true;
 }
}

8.3 不用 [ObservableProperty] 的写法

1
2
3
4
5
6
7
8
9


public partial class MainViewModel : ObservableObject
{
 private string _userName;
 public string UserName
 {
 get => _userName;
 set => SetProperty(ref _userName, value);
 }
}

1
2
3
4
5
6
7
8


何时不用 [ObservableProperty]：
 → 字段已有复杂逻辑（自定义 setter）
 → 命名冲突
 → 编译器版本不支持 source generator

何时用：
 → 绝大多数场景（90%+）
 → 样板代码消失，更易读

九、命令参数

9.1 CommandParameter

1
2
3
4


<!-- 传参给命令 -->
<Button Content="删除"
 Command="{Binding DeleteCommand}"
 CommandParameter="{Binding SelectedItem}"/>

1
2
3
4
5
6


[RelayCommand]
private void Delete(ItemModel item)
{
 // item 来自 CommandParameter
 if (item != null) Items.Remove(item);
}

9.2 生成的命令带泛型

1
2


// 生成的命令：IRelayCommand<ItemModel>
public IRelayCommand<ItemModel> DeleteCommand { get; }

十、实战：可命令化的简单计算器

把命令 + Toolkit + 绑定全部用上。

10.1 ViewModel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using System.ComponentModel;

namespace CalculatorDemo;

public partial class CalculatorViewModel : ObservableObject
{
 [ObservableProperty]
 private double _operand1;

 [ObservableProperty]
 private double _operand2;

 [ObservableProperty]
 private double _result;

 [ObservableProperty]
 private string _operator = "+";

 [ObservableProperty]
 [NotifyCanExecuteChangedFor(nameof(CalculateCommand))]
 private bool _isCalculating;

 public CalculatorViewModel()
 {
 CalculateCommand = new RelayCommand(Calculate, CanCalculate);
 }

 // 用特性版本的命令
 [RelayCommand(CanExecute = nameof(CanCalculate))]
 private async Task CalculateAsync()
 {
 IsCalculating = true;
 try
 {
 await Task.Delay(500); // 模拟异步计算

 Result = Operator switch
 {
 "+" => Operand1 + Operand2,
 "-" => Operand1 - Operand2,
 "*" => Operand1 * Operand2,
 "/" => Operand2 != 0 ? Operand1 / Operand2 : 0,
 _ => 0
 };
 }
 finally
 {
 IsCalculating = false;
 }
 }

 // 同步版本（简化演示）
 public IRelayCommand CalculateCommand { get; }

 private void Calculate()
 {
 Result = Operator switch
 {
 "+" => Operand1 + Operand2,
 "-" => Operand1 - Operand2,
 "*" => Operand1 * Operand2,
 "/" => Operand2 != 0 ? Operand1 / Operand2 : 0,
 _ => 0
 };
 }

 private bool CanCalculate()
 => !IsCalculating && Operator != "/" || Operand2 != 0;

 [RelayCommand]
 private void Clear()
 {
 Operand1 = 0;
 Operand2 = 0;
 Result = 0;
 }

 // 依赖属性联动
 partial void OnOperatorChanged(string value)
 => CalculateCommand.NotifyCanExecuteChanged();
}

10.2 XAML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


<Window x:Class="CalculatorDemo.MainWindow"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 Title="Calculator" Width="400" Height="300">
 <Window.DataContext>
 <local:CalculatorViewModel/>
 </Window.DataContext>

 <Grid Margin="16">
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="*"/>
 </Grid.RowDefinitions>

 <StackPanel Grid.Row="0" Orientation="Horizontal" Margin="0,0,0,8">
 <TextBox Width="100" Text="{Binding Operand1, UpdateSourceTrigger=PropertyChanged}"/>
 <ComboBox Width="50" Margin="8,0" SelectedItem="{Binding Operator}">
 <ComboBoxItem Content="+"/>
 <ComboBoxItem Content="-"/>
 <ComboBoxItem Content="*"/>
 <ComboBoxItem Content="/"/>
 </ComboBox>
 <TextBox Width="100" Text="{Binding Operand2, UpdateSourceTrigger=PropertyChanged}"/>
 </StackPanel>

 <TextBlock Grid.Row="1" Margin="0,8">
 <Run Text="= "/><Run Text="{Binding Result, Mode=OneWay}"/>
 </TextBlock>

 <StackPanel Grid.Row="2" Orientation="Horizontal" Margin="0,8">
 <Button Content="计算" Command="{Binding CalculateCommand}" Width="80" Margin="0,0,8,0"/>
 <Button Content="清空" Command="{Binding ClearCommand}" Width="80"/>
 </StackPanel>

 <TextBlock Grid.Row="3" Text="{Binding IsCalculating, StringFormat=正在计算：{0}}"/>
 </Grid>
</Window>

10.3 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


✅ [ObservableProperty] 字段 → 属性
✅ [RelayCommand] 方法 → ICommand
✅ [NotifyCanExecuteChangedFor] 属性联动命令
✅ partial OnXxxChanged 钩子
✅ CanExecute 业务规则（除数不为 0）
✅ CommandParameter 传参（隐式：通过 IsCalculating）
✅ 异步命令（CalculateAsync，async Task）
✅ 绑定 Mode=OneWay（结果只读）
✅ UpdateSourceTrigger=PropertyChanged（实时同步）

观察：
 - 切换运算符为 "/" 且 Operand2=0 → 计算按钮自动灰掉
 - 输入实时反映到 UI（INPC）
 - 计算中 IsCalculating=true → 按钮禁用

十一、常见陷阱

11.1 忘了 partial

1
2
3
4
5
6
7
8
9


// ❌ 不加 partial，源生成器无法补充
public class MainViewModel : ObservableObject
{
 [ObservableProperty] private string _name;
}
// 编译报错：找不到属性 Name

// ✅
public partial class MainViewModel : ObservableObject { ... }

11.2 字段命名不规范

1
2
3
4
5
6
7


// ❌ 字段没下划线前缀
[ObservableProperty]
private string name; // 生成的属性可能也是 name（冲突）

// ✅
[ObservableProperty]
private string _name;

11.3 命令名字冲突

1
2
3
4
5
6
7


// ❌ 方法已叫 SaveCommand
[RelayCommand]
private void SaveCommand() { } // 生成属性也叫 SaveCommand → 冲突

// ✅ 方法叫 Save
[RelayCommand]
private void Save() { } // 生成属性 SaveCommand

11.4 CanExecute 不通知

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// ❌ UserName 变了但 SaveCommand 不知道
[ObservableProperty]
private string _userName;

[RelayCommand(CanExecute = nameof(CanSave))]
private void Save() { }
public bool CanSave => !string.IsNullOrEmpty(UserName);

// → UserName 改变，按钮启用状态不刷新

// ✅ 加 NotifyCanExecuteChangedFor
[ObservableProperty]
[NotifyCanExecuteChangedFor(nameof(SaveCommand))]
private string _userName;

11.5 异步命令没 await

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// ❌ fire-and-forget
[RelayCommand]
private async Task LoadAsync()
{
 LoadData(); // 没 await，立即返回，IsRunning=false
}

// ✅
[RelayCommand]
private async Task LoadAsync()
{
 await LoadDataAsync();
}

十二、与 ASP.NET Core 的对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


ASP.NET Core WPF Command
──────────────────────────────────────────────
Controller Action ICommand.Execute
[HttpPost] 路由 Command 绑定到 Button
Authorization Filter ICommand.CanExecute
[FromBody] 参数 CommandParameter
MediatR Command ICommand（思路一致）
MediatR Handler Command 内部逻辑

后端类比小结：
 ICommand ≈ MediatR 的 IRequest
 RelayCommand.Execute ≈ Handler.Handle
 CanExecute ≈ Authorization Policy
 CommandParameter ≈ Request DTO

十三、小结

本文聚焦命令系统本身：

事件 vs 命令的本质差别（耦合度、可测试性）
ICommand 三成员（Execute / CanExecute / CanExecuteChanged）
CommandManager.RequerySuggested 的角色
RoutedCommand vs RelayCommand 的选型
CommunityToolkit.Mvvm 三件套（ObservableObject / [ObservableProperty] / [RelayCommand]）
[ObservableProperty] 源生成器原理（生成属性 + INPC + partial 钩子）
[RelayCommand] 源生成器原理（生成 ICommand + 自动命名）
NotifyCanExecuteChangedFor 的精确通知
异步命令与 IsRunning
实战：可命令化的计算器

1
2
3
4


记住三句话：
 1. ICommand 是"业务操作的抽象"——Execute 是动作，CanExecute 是规则
 2. [ObservableProperty] / [RelayCommand] 是源生成器——零样板但要知道生成了什么
 3. CommunityToolkit 用 NotifyCanExecuteChangedFor 替代 CommandManager——更精确但要求显式声明

下一篇将进入 MVVM 工程化——把命令、绑定、DP 落到完整项目结构，引入 Microsoft.Extensions.DependencyInjection，搭建 TodoApp 完整工程。

WPF 学习笔记（五）：数据绑定——WPF 的"响应式"基础

Tue, 05 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

数据绑定是 WPF 的灵魂。前面几篇学的（DP、路由事件、布局）都是基础，本篇是把它们"串起来"的关键——声明式响应式 UI。

理解了绑定，你就知道为什么 WPF 能让 UI 和业务逻辑完全解耦，为什么 MVVM 模式在 WPF 里行得通。本篇不引入 MVVM（留到第 6、7 篇），纯讲绑定机制本身。

本文要回答：

绑定怎么"自动同步"？为什么改 ViewModel 的属性，UI 立刻变？双向绑定怎么避免死循环？

一、绑定的本质

1.1 一个最简单的绑定

1

<TextBox Text="{Binding Name}"/>

1
2
3
4
5
6


表面：TextBox.Text 绑定到 Name 属性
含义：
 - 找 TextBox 的 DataContext
 - 取 DataContext.Name
 - 把值赋给 TextBox.Text
 - 同时监听 Name 变化，变了就更新 TextBox.Text

1.2 绑定 = 对象间声明式依赖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


传统命令式 UI：
 1. 改 Name
 2. 手动找 TextBox
 3. 手动赋值 textBox.Text = Name

WPF 绑定：
 1. 改 Name
 2. TextBox.Text 自动变

 你只关心"数据"，UI 自己跟着变

后端类比：
 绑定 ≈ 带生命周期的事件订阅
 Source.PropertyChanged += (s, e) => Target.Value = Source.Property
 但 WPF 帮你管理生命周期、转换、错误处理

1.3 绑定的两个端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


绑定源（Source）：
 数据来源（任何对象、任何属性）

绑定目标（Target）：
 显示数据的 DP（必须是依赖属性）

绑定方向：
 OneWay：源 → 目标（默认，源变目标变）
 TwoWay：双向（任一变另一变）
 OneWayToSource：目标 → 源
 OneTime：源 → 目标，只一次

1
2
3
4
5
6
7
8
9


为什么目标必须是 DP？
 → 绑定系统要监听目标变化
 → DP 的 PropertyChanged 是天然的监听点
 → CLR 属性没有

为什么源不必须是 DP？
 → 源可以用 INotifyPropertyChanged 通知
 → 或 DependencyObject（也是 DP）
 → 或反射直接读属性

二、Binding 对象模型

{Binding Name} 在底层是 new Binding { Path = "Name" }。

2.1 关键属性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public class Binding : MarkupExtension
{
 public object Source { get; set; } // 显式指定源
 public RelativeSource RelativeSource { get; set; } // 相对源
 public string ElementName { get; set; } // 命名元素
 public PropertyPath Path { get; set; } // 属性路径
 public BindingMode Mode { get; set; } // 方向
 public UpdateSourceTrigger UpdateSourceTrigger { get; set; }
 public IValueConverter Converter { get; set; }
 public object ConverterParameter { get; set; }
 public string StringFormat { get; set; }
 public bool ValidatesOnDataErrors { get; set; }
 public object FallbackValue { get; set; }
 public object TargetNullValue { get; set; }
}

2.2 XAML 等价 C#

1
2
3
4
5


<!-- XAML -->
<TextBox Text="{Binding Name, Source={StaticResource vm},
 Mode=TwoWay,
 UpdateSourceTrigger=PropertyChanged,
 Converter={StaticResource boolToVis}}"/>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// C# 等价
var binding = new Binding
{
 Source = Resources["vm"],
 Path = new PropertyPath("Name"),
 Mode = BindingMode.TwoWay,
 UpdateSourceTrigger = UpdateSourceTrigger.PropertyChanged,
 Converter = (IValueConverter)Resources["boolToVis"]
};
BindingOperations.SetBinding(textBox, TextBox.TextProperty, binding);

三、绑定源的三种指定方式

3.1 DataContext（隐式源，最常用）

1
2
3
4
5
6
7


<Window.DataContext>
 <local:MainViewModel/>
</Window.DataContext>

<!-- 子元素隐式继承 DataContext -->
<TextBox Text="{Binding Name}"/> <!-- 绑定到 Window.DataContext.Name -->
<Button Content="{Binding Title}"/>

1
2
3
4
5


特点：
 - 不写 Source，默认用 DataContext
 - DataContext 是 DP 且可继承（详见第 2 篇）
 - 子元素没设置 → 用父级
 - 90% 的绑定都用这种

3.2 Source（显式指定）

1
2
3
4
5


<!-- 绑定到静态资源 -->
<TextBlock Text="{Binding Name, Source={StaticResource userVm}}"/>

<!-- 绑定到静态属性 -->
<TextBlock Text="{Binding MachineName, Source={x:Static sys:Environment.MachineName}}"/>

3.3 ElementName（命名元素）

1
2


<Slider x:Name="slider" Minimum="0" Maximum="100" Value="50"/>
<TextBlock Text="{Binding Value, ElementName=slider}"/>

3.4 RelativeSource（相对源）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 找祖先 -->
<TextBlock Text="{Binding DataContext.Title,
 RelativeSource={RelativeSource AncestorType=Window}}"/>

<!-- 找模板父 -->
<TextBlock Text="{Binding Background,
 RelativeSource={RelativeSource TemplatedParent}}"/>

<!-- 自身 -->
<TextBlock Text="{Binding Width,
 RelativeSource={RelativeSource Self}}"/>

四、Path：属性路径

4.1 简单路径

1
2
3
4


<TextBlock Text="{Binding Name}"/> <!-- .Name -->
<TextBlock Text="{Binding User.Name}"/> <!-- .User.Name（嵌套）-->
<TextBlock Text="{Binding Items[0]}"/> <!-- 索引 -->
<TextBlock Text="{Binding Items.Count}"/> <!-- 属性 -->

4.2 路径里的特殊语法

1
2
3
4
5
6
7
8
9


<!-- 当前对象 -->
<TextBlock Text="{Binding}"/> <!-- DataContext 本身 -->

<!-- 路径中的索引 -->
<TextBlock Text="{Binding Items[0].Name}"/>

<!-- 附加属性 -->
<TextBlock Text="{Binding (Grid.Row),
 RelativeSource={RelativeSource Self}}"/>

五、BindingMode 与 UpdateSourceTrigger

5.1 四种 Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


OneWay（默认大部分）：
 Source → Target
 Source 变 → Target 更新
 Target 不会改 Source

TwoWay：
 双向同步
 Target 改 → 推回 Source
 Source 变 → 更新 Target
 （TextBox.Text 默认 TwoWay）

OneWayToSource：
 Target → Source
 罕见（用于"反向"场景）

OneTime：
 只绑定一次（Source → Target 初始化）
 之后 Source 变 Target 不变
 适合"几乎不变"的数据（性能好）

5.2 各控件默认 Mode

1
2
3
4
5
6
7
8


控件 默认 Mode
────────────────────────────────
TextBox.Text TwoWay
CheckBox.IsChecked TwoWay
Slider.Value TwoWay
TextBlock.Text OneWay
Border.Background OneWay
ContentControl OneWay

5.3 UpdateSourceTrigger

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


仅在 TwoWay/OneWayToSource 模式下生效
决定"Target 改了，什么时候推回 Source"

取值：
 Default：控件决定（TextBox=LostFocus，其他=PropertyChanged）
 PropertyChanged：Target 一变就推回
 LostFocus：Target 失焦才推回
 Explicit：必须手动 BindingExpression.UpdateSource()

实战：
 <!-- 实时验证：每输入一个字符就同步 -->
 <TextBox Text="{Binding Name, UpdateSourceTrigger=PropertyChanged}"/>

1
2
3


// 手动更新（Explicit 模式）
var expr = textBox.GetBindingExpression(TextBox.TextProperty);
expr?.UpdateSource();

六、INotifyPropertyChanged

绑定源通知"我变了"的标准方式。

6.1 接口实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public class User : INotifyPropertyChanged
{
 private string _name;
 public string Name
 {
 get => _name;
 set
 {
 if (_name != value)
 {
 _name = value;
 OnPropertyChanged(nameof(Name));
 }
 }
 }

 public event PropertyChangedEventHandler PropertyChanged;

 protected virtual void OnPropertyChanged(string propertyName)
 => PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}

6.2 绑定如何监听

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


WPF 绑定系统监听源的变化：
 1. 源实现 INotifyPropertyChanged → 监听 PropertyChanged 事件
 2. 源是 DependencyObject → 监听 DP 的 PropertyChangedCallback
 3. 都不是 → 反射读一次（不监听变化）

PropertyChanged 事件触发：
 → 绑定系统收到
 → 检查 e.PropertyName 是否匹配 Path
 → 匹配 → 重新读取属性值
 → 写入 Target DP

6.3 INPC 的常见坑

坑 1：字符串硬编码

1
2
3
4
5


// ❌ 字符串写错，运行时不报错
OnPropertyChanged("Naem"); // 拼写错误

// ✅ nameof
OnPropertyChanged(nameof(Name));

坑 2：跨线程

1
2
3
4
5


// ❌ 后台线程改属性 → WPF 绑定跨线程异常
Task.Run(() => { user.Name = "New"; }); // 报错

// ✅ 切回 UI 程序（详见第 9 篇）
Application.Current.Dispatcher.Invoke(() => user.Name = "New");

坑 3：依赖属性

1
2
3
4
5
6
7
8
9


// FirstName/LastName 改了 FullName 也要变
public string FullName => $"{FirstName} {LastName}";

set
{
 _firstName = value;
 OnPropertyChanged(nameof(FirstName));
 OnPropertyChanged(nameof(FullName)); // ← 必须显式触发
}

6.4 现代写法（CommunityToolkit.Mvvm）

1
2
3
4
5
6


// 用源生成器，零样板
public partial class User : ObservableObject
{
 [ObservableProperty]
 private string _name; // 自动生成 public Name + INPC
}

详细留到第 6 篇讲。

七、IValueConverter

源和目标类型不一致时，用 Converter 转换。

7.1 接口

1
2
3
4
5


public interface IValueConverter
{
 object Convert(object value, Type targetType, object parameter, CultureInfo culture);
 object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture);
}

7.2 经典 Converter：BoolToVisibility

1
2
3
4
5
6
7
8


public class BoolToVisibilityConverter : IValueConverter
{
 public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 => value is bool b && b ? Visibility.Visible : Visibility.Collapsed;

 public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
 => value is Visibility v && v == Visibility.Visible;
}

1
2
3
4
5
6
7


<!-- 声明资源 -->
<Window.Resources>
 <local:BoolToVisibilityConverter x:Key="boolToVis"/>
</Window.Resources>

<!-- 使用 -->
<TextBlock Text="加载中..." Visibility="{Binding IsLoading, Converter={StaticResource boolToVis}}"/>

7.3 IMultiValueConverter

1
2
3
4
5
6
7
8


public class BooleanAndConverter : IMultiValueConverter
{
 public object Convert(object[] values, Type targetType, object parameter, CultureInfo culture)
 => values.OfType<bool>().All(v => v);

 public object[] ConvertBack(object value, Type[] targetTypes, object parameter, CultureInfo culture)
 => throw new NotSupportedException();
}

1
2
3
4
5
6
7
8
9


<Button Content="提交">
 <Button.IsEnabled>
 <MultiBinding Converter="{StaticResource andConv}">
 <Binding Path="IsNameValid"/>
 <Binding Path="IsEmailValid"/>
 <Binding Path="IsAgreed"/>
 </MultiBinding>
 </Button.IsEnabled>
</Button>

7.4 StringFormat

简单格式化不需要 Converter。

1
2
3


<TextBlock Text="{Binding Price, StringFormat=C}"/>
<TextBlock Text="{Binding Date, StringFormat=yyyy-MM-dd}"/>
<TextBlock Text="{Binding Name, StringFormat=用户：{0}}"/>

八、CollectionView：列表的"视图层"

绑定到集合时，WPF 自动包装成 CollectionView，提供过滤/排序/分组。

8.1 默认 CollectionView

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public ObservableCollection<User> Users { get; } = new();

// 绑定后，WPF 自动创建 CollectionView
// 获取默认视图
var view = CollectionViewSource.GetDefaultView(Users);

// 加过滤
view.Filter = item => item is User u && u.IsActive;

// 加排序
view.SortDescriptions.Add(new SortDescription(nameof(User.Name), ListSortDirection.Ascending));

// 加分组
view.GroupDescriptions.Add(new PropertyGroupDescription(nameof(User.Department)));

8.2 视图的特点

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


CollectionView 不复制数据：
 - 它是"原集合的视图层"
 - 过滤/排序/分组不修改原集合
 - 同一集合可以有多个视图

好处：
 - UI 端的"显示逻辑"和 ViewModel 的"数据"解耦
 - 多个 ListBox 同源不同视图（一个排序，一个过滤）

注意：
 - 视图的"当前项"（CurrentItem）跨视图共享
 - 选中项变化通常通过 CurrentItem 同步

8.3 分组的 UI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<ListBox ItemsSource="{Binding Users}">
 <ListBox.GroupStyle>
 <GroupStyle>
 <GroupStyle.HeaderTemplate>
 <DataTemplate>
 <TextBlock Text="{Binding Name}" FontWeight="Bold"/>
 </DataTemplate>
 </GroupStyle.HeaderTemplate>
 </GroupStyle>
 </ListBox.GroupStyle>
</ListBox>

九、ObservableCollection

集合本身的"INPC"。

9.1 为什么需要

1
2
3
4
5
6
7
8


public ObservableCollection<User> Users { get; }

Users.Add(new User()); // UI 自动更新
Users.RemoveAt(0); // UI 自动更新

// 普通 List<T> 即使绑定了，Add 也不会通知 UI
List<User> list = new();
list.Add(new User()); // UI 不知道

9.2 接口 INotifyCollectionChanged

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class ObservableCollection<T> : Collection<T>, INotifyCollectionChanged, INotifyPropertyChanged
{
 public event NotifyCollectionChangedEventHandler CollectionChanged;

 protected override void InsertItem(int index, T item)
 {
 base.InsertItem(index, item);
 CollectionChanged?.Invoke(this,
 new NotifyCollectionChangedEventArgs(NotifyCollectionChangedAction.Add, item, index));
 }
 // 类似重写其他方法
}

1
2
3
4
5
6
7
8
9


通知格式（NotifyCollectionChangedAction）：
 Add：增加
 Remove：删除
 Replace：替换
 Move：移动
 Reset：整体刷新（最贵，UI 重新绑定）

ObservableCollection 默认 Notify 单项变化（性能好）
要触发 Reset：Users.Clear() + Users.Add(...)

9.3 跨线程集合

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// ❌ 后台线程改 ObservableCollection → 报错
Task.Run(() => Users.Add(new User()));

// ✅ 启用跨线程同步
ObservableCollection<User> users = new();
BindingOperations.EnableCollectionSynchronization(users, _lock);
// 之后后台线程改 users 安全（用 _lock 同步）

// 或：切回 UI 线程
Application.Current.Dispatcher.Invoke(() => Users.Add(new User()));

十、绑定的进阶

10.1 FallbackValue / TargetNullValue

1
2
3
4
5


<!-- 源不存在时的回退值 -->
<TextBlock Text="{Binding Name, FallbackValue='未知'}"/>

<!-- 源是 null 时的显示值 -->
<TextBlock Text="{Binding Name, TargetNullValue='(空)'}"/>

10.2 绑定的优先级

1
2
3
4
5
6
7
8


DP 的优先级（详见第 2 篇）和绑定结合：
 Local Value > Style > ...

绑定本身是 Local Value 级别
 → 你 SetValue(dp, value) 会覆盖绑定！

恢复绑定：
 BindingOperations.ClearBinding(textBlock, TextBlock.TextProperty);

10.3 Validation

1
2
3


// ViewModel 实现 IDataErrorInfo 或 INotifyDataErrorInfo
public string this[string columnName]
 => columnName == nameof(Name) && string.IsNullOrEmpty(Name) ? "必填" : null;

1
2


<TextBox Text="{Binding Name, ValidatesOnDataErrors=true,
 UpdateSourceTrigger=PropertyChanged}"/>

WPF 会自动给错误状态加红色边框（默认 ErrorTemplate）。

十一、实战：可过滤/排序的员工列表

不引入 MVVM，纯 code-behind 演示绑定机制。

11.1 Model

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


public class Employee : INotifyPropertyChanged
{
 private string _name;
 public string Name
 {
 get => _name;
 set => SetField(ref _name, value);
 }

 private string _department;
 public string Department
 {
 get => _department;
 set => SetField(ref _department, value);
 }

 private decimal _salary;
 public decimal Salary
 {
 get => _salary;
 set => SetField(ref _salary, value);
 }

 public event PropertyChangedEventHandler PropertyChanged;
 protected void SetField<T>(ref T field, T value, [CallerMemberName] string name = null)
 {
 if (!EqualityComparer<T>.Default.Equals(field, value))
 {
 field = value;
 PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
 }
 }
}

11.2 XAML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


<Window x:Class="BindingDemo.MainWindow"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 xmlns:scm="clr-namespace:System.ComponentModel;assembly=WindowsBase"
 Title="Employee Browser" Width="800" Height="500">
 <Window.Resources>
 <local:SalaryToStringConverter x:Key="salaryConv"/>
 </Window.Resources>

 <Grid Margin="12">
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="*"/>
 </Grid.RowDefinitions>

 <!-- 搜索栏 -->
 <StackPanel Grid.Row="0" Orientation="Horizontal" Margin="0,0,0,8">
 <TextBlock Text="搜索：" VerticalAlignment="Center"/>
 <TextBox x:Name="searchBox" Width="200" Margin="8,0,0,0"
 TextChanged="SearchBox_TextChanged"/>
 </StackPanel>

 <!-- 排序控制 -->
 <StackPanel Grid.Row="1" Orientation="Horizontal" Margin="0,0,0,8">
 <Button Content="按姓名" Click="SortByName" Margin="0,0,8,0"/>
 <Button Content="按薪资" Click="SortBySalary" Margin="0,0,8,0"/>
 <CheckBox x:Name="groupCheck" Content="按部门分组" Margin="0,0,8,0"
 Checked="GroupCheck_Changed" Unchecked="GroupCheck_Changed"/>
 </StackPanel>

 <!-- 列表 -->
 <ListBox Grid.Row="2" x:Name="employeeList" ItemsSource="{Binding}">
 <ListBox.ItemTemplate>
 <DataTemplate>
 <Grid Margin="4">
 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="200"/>
 <ColumnDefinition Width="150"/>
 <ColumnDefinition Width="*"/>
 </Grid.ColumnDefinitions>
 <TextBlock Grid.Column="0" Text="{Binding Name}" FontWeight="Bold"/>
 <TextBlock Grid.Column="1" Text="{Binding Department}"/>
 <TextBlock Grid.Column="2"
 Text="{Binding Salary, Converter={StaticResource salaryConv},
 StringFormat=C}"/>
 </Grid>
 </DataTemplate>
 </ListBox.ItemTemplate>
 <ListBox.GroupStyle>
 <GroupStyle>
 <GroupStyle.HeaderTemplate>
 <DataTemplate>
 <Border Background="LightBlue" Padding="4">
 <TextBlock Text="{Binding Name}" FontWeight="Bold"/>
 </Border>
 </DataTemplate>
 </GroupStyle.HeaderTemplate>
 </GroupStyle>
 </ListBox.GroupStyle>
 </ListBox>
 </Grid>
</Window>

11.3 Code-behind

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


public partial class MainWindow : Window
{
 private ObservableCollection<Employee> _employees;
 private ListCollectionView _view;

 public MainWindow()
 {
 InitializeComponent();

 _employees = new ObservableCollection<Employee>
 {
 new() { Name = "Alice", Department = "Engineering", Salary = 25000 },
 new() { Name = "Bob", Department = "Sales", Salary = 18000 },
 new() { Name = "Carol", Department = "Engineering", Salary = 30000 },
 new() { Name = "Dave", Department = "HR", Salary = 15000 },
 new() { Name = "Eve", Department = "Sales", Salary = 22000 },
 };

 DataContext = _employees;
 _view = (ListCollectionView)CollectionViewSource.GetDefaultView(_employees);
 }

 private void SearchBox_TextChanged(object sender, TextChangedEventArgs e)
 {
 var keyword = searchBox.Text?.Trim() ?? "";
 _view.Filter = item => item is Employee emp
 && (string.IsNullOrEmpty(keyword)
 || emp.Name.Contains(keyword, StringComparison.OrdinalIgnoreCase)
 || emp.Department.Contains(keyword, StringComparison.OrdinalIgnoreCase));
 }

 private void SortByName(object sender, RoutedEventArgs e)
 {
 _view.SortDescriptions.Clear();
 _view.SortDescriptions.Add(new SortDescription(nameof(Employee.Name), ListSortDirection.Ascending));
 }

 private void SortBySalary(object sender, RoutedEventArgs e)
 {
 _view.SortDescriptions.Clear();
 _view.SortDescriptions.Add(new SortDescription(nameof(Employee.Salary), ListSortDirection.Descending));
 }

 private void GroupCheck_Changed(object sender, RoutedEventArgs e)
 {
 if (groupCheck.IsChecked == true)
 _view.GroupDescriptions.Add(new PropertyGroupDescription(nameof(Employee.Department)));
 else
 _view.GroupDescriptions.Clear();
 }
}

public class SalaryToStringConverter : IValueConverter
{
 public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
 => value is decimal d ? $"{d:N0} 元/月" : value;

 public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
 => throw new NotSupportedException();
}

11.4 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


✅ DataContext 绑定（Window.DataContext = 集合）
✅ ObservableCollection 集合通知
✅ INPC 属性通知
✅ CollectionView 过滤/排序/分组
✅ DataTemplate 显示
✅ IValueConverter 类型转换
✅ StringFormat 格式化
✅ GroupStyle 分组 UI

观察：
 - 没用 MVVM，但已经是响应式 UI
 - 搜索框输入立即过滤（不用手动刷新 ListBox）
 - 改 Employee.Name，UI 立刻变（INPC 触发）
 - 排序按钮只改 SortDescriptions，UI 自动重排

十二、常见陷阱

12.1 DataContext 没设

1
2


<!-- ❌ DataContext 是 null -->
<TextBox Text="{Binding Name}"/> <!-- 绑定到 null.Name → 输出空 + 错误日志 -->

1
2


调试：检查 Output 窗口的 BindingExpression 错误
"BindingExpression path error: 'Name' property not found on 'object' ''Null'..."

12.2 属性没通知

1
2
3
4


// ❌ 改了字段但 UI 不更新
public string Name { get; set; }
vm.Name = "New";
// UI 还是旧的

12.3 绑定到值类型字段

1
2
3
4


// ❌ 字段不通知（即使 ObservableCollection 包装）
public struct Point { public int X; public int Y; }
ObservableCollection<Point> points;
// 改 points[0].X = 5 → UI 不知道

1

✅ Point 实现 INPC（或用 class 而不是 struct）

12.4 双向绑定死循环

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// ❌ 自我反馈循环
public string Name
{
 get => _name;
 set
 {
 _name = value;
 OnPropertyChanged(nameof(Name));
 // ❌ 这里又触发别的逻辑改 Name
 Normalize(); // 内部又 set Name → 死循环
 }
}

1
2
3
4
5
6


WPF 有部分防护：
 - 绑定系统检测"值相同"会跳过通知
 - 但如果不相等就会死循环

✅ 加 if (_name != value) 检查
✅ 把副作用放后台或显式标记

12.5 内存泄漏

1
2
3
4
5
6
7
8


// ❌ 短生命周期对象订阅长生命周期对象的 PropertyChanged
window.PropertyChanged += shortLived.Handler;
// shortLived 被持有，泄漏

// ✅ 用弱事件 WeakEventManager
PropertyChangedEventManager.AddHandler(window, shortLived.Handler, nameof(Window.Title));

// 绑定系统内部用弱事件 → 绑定不会泄漏

十三、与 ASP.NET Core / 前端的对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


ASP.NET Core 后端 WPF 绑定
──────────────────────────────────────────
ViewModel (Razor) DataContext
@Model.Property {Binding Property}
Model 不变 UI 不更新 INPC → UI 自动更新
显式渲染 隐式响应

Vue / React WPF 绑定
──────────────────────────────────────────
data() { } ObservableCollection + INPC
v-model Mode=TwoWay
computed IValueConverter + 依赖属性
watch PropertyChanged + 绑定

关键差异：
 - WPF 绑定是双向自动的（声明即响应）
 - Vue/React 也响应式但思路不同（虚拟 DOM diff vs 直接更新）
 - WPF 的"双向"是声明式，Vue 是 v-model 显式

十四、小结

本文深入 WPF 的数据绑定：

绑定本质：对象间声明式依赖
Binding 对象模型（Source / Path / Mode / Converter）
DataContext 继承链（隐式源）
三种源指定方式（DataContext / Source / ElementName / RelativeSource）
四种 Mode + UpdateSourceTrigger
INotifyPropertyChanged 与陷阱（线程/字符串/依赖属性）
IValueConverter / IMultiValueConverter / StringFormat
CollectionView（过滤/排序/分组）
ObservableCollection 与跨线程
实战：可过滤/排序/分组的员工列表

1
2
3
4


记住三句话：
 1. 绑定 = 声明式的事件订阅，源 INPC + 目标 DP
 2. DataContext 继承是绑定的根基——隐式源让 XAML 简洁
 3. CollectionView 是"列表的视图层"——过滤排序不污染原集合

下一篇将进入 WPF 的核心模式——命令与 MVVM。绑定解决了"显示"，命令解决"操作"，MVVM 把它们组合成完整架构。

WPF 学习笔记（四）：布局系统——Measure/Arrange 与面板

Fri, 01 May 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

WPF 的布局系统和 WinForms 是完全不同的范式。WinForms 是"绝对定位"——button.Location = new Point(10, 20)，所有控件都用屏幕坐标。WPF 是"两阶段布局"——父元素问子元素"你想多大？"（Measure），然后告诉子元素"你的最终位置和大小"（Arrange）。

这个范式差别，理解了之后写 WPF 布局就顺；不理解，会一直被"为什么我的 Grid 在 StackPanel 里高度变 0"这种问题困扰。

本文要回答：

为什么 WPF 用两阶段布局？各种 Panel 的度量公式是什么？怎么自定义 Panel？

一、为什么是两阶段布局

1.1 WinForms 的绝对定位

1
2
3
4


// WinForms
var button = new Button();
button.Location = new Point(10, 20);
button.Size = new Size(100, 30);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


特点：
 - 你写死坐标和尺寸
 - 父容器不参与"计算"
 - 简单直接

问题：
 - 窗口缩放，控件不动 → 丑陋
 - DPI 变化，控件位置乱
 - 国际化（标签变长）→ 控件重叠
 - 嵌套布局完全手动

1.2 WPF 的两阶段

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Measure（度量）：
 父问子："给你这么多空间，你想要多大？"
 子答："我想要 100x30。"（DesiredSize）

Arrange（安排）：
 父告诉子："你的最终位置是 (10, 20)，大小是 100x30。"
 子按这个尺寸渲染

为什么分两阶段？
 1. 父可能要让多个子共享空间（Grid 的 * 比例）
 → 必须先知道每个子要多少，再分配
 2. 嵌套布局需要递归
 → Window 问 Grid，Grid 问 Button，Button 问 Content
 3. 容器策略不同（StackPanel 累加，Grid 平均）
 → 但都遵循 Measure → Arrange 模式

1.3 触发时机

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


什么时候触发 layout：

1. 窗口初始化
2. 控件加进视觉树
3. Visibility 变化（Collapsed ↔ Visible）
4. Margin / Padding 变化
5. 字号、内容变化
6. 显式调用 InvalidateMeasure() / InvalidateArrange()

Layout 是异步的：
 - 你改一个属性，不会立刻 re-layout
 - 标记"脏"，等下一个 Layout Pass（Dispatcher 优先级 Layout）
 - 多次 InvalidateMeasure 在一次 Pass 里合并

 例外：UpdateLayout() 强制立即 layout（慎用，性能杀手）

二、Measure 与 Arrange

2.1 Measure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// FrameworkElement.Measure 的简化签名
public void Measure(Size availableSize)
{
 // 1. 检查 cache
 // 2. 调用 MeasureCore → MeasureOverride
 var desiredSize = MeasureOverride(availableSize);
 // 3. 缓存 desiredSize 到 this.DesiredSize
 this.DesiredSize = desiredSize;
}

protected virtual Size MeasureOverride(Size availableSize)
{
 // 子类（Panel）实现
 // 返回"我想要多大"
}

1
2
3
4
5
6
7
8
9


availableSize 的含义：
 - 父给子的"可用空间"
 - Size.Infinity 表示"无限"（StackPanel 给子元素无限主轴空间）
 - 具体数字表示"父有这么多空间给你"

DesiredSize 的含义：
 - 子返回的"想要大小"
 - 必须 ≤ availableSize（不强制，但 WPF 会裁剪）
 - 必须是有限值（不能返回 Infinity）

2.2 Arrange

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public void Arrange(Rect finalRect)
{
 // finalRect: 最终位置 + 大小（相对于父）
 // 调用 ArrangeCore → ArrangeOverride
 ArrangeOverride(finalRect);
}

protected virtual Size ArrangeOverride(Size finalSize)
{
 // 子类（Panel）实现
 // 安排每个子的位置和大小
 // 返回实际使用的大小（通常等于 finalSize）
}

1
2
3
4
5


finalRect 的含义：
 - X, Y：相对于父的位置
 - Width, Height：实际大小

 必须调用每个子的 Arrange，否则子不会渲染

2.3 完整流程示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


StackPanel（垂直）有 3 个 Button：

 Measure 阶段：
 StackPanel.MeasureOverride(availableSize):
 foreach child:
 child.Measure(availableSize with Width=infinity)
 desiredHeight += child.DesiredSize.Height
 return new Size(maxChildWidth, desiredHeight)

 Arrange 阶段：
 StackPanel.ArrangeOverride(finalSize):
 y = 0
 foreach child:
 child.Arrange(new Rect(0, y, finalSize.Width, child.DesiredSize.Height))
 y += child.DesiredSize.Height
 return finalSize

三、HorizontalAlignment / VerticalAlignment / Margin

3.1 三件套

1
2
3
4
5


Margin：子元素外边距
HorizontalAlignment：水平对齐（Left/Center/Right/Stretch）
VerticalAlignment：垂直对齐（Top/Center/Bottom/Stretch）

它们在 Arrange 阶段生效

3.2 Stretch 的特殊含义

1
2
3
4
5
6
7


<!-- Stretch（默认） -->
<Button HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/>
<!-- 子元素占满可用空间 -->

<!-- Left/Top -->
<Button HorizontalAlignment="Left" VerticalAlignment="Top"/>
<!-- 子元素在 DesiredSize 大小，贴左上 -->

1
2
3
4
5
6


Stretch 的副作用：
 StackPanel（垂直）的子元素 HorizontalAlignment 默认是 Stretch
 → 子元素的宽度 = StackPanel 的宽度（拉伸）

 但如果父容器高度有限，StackPanel 自己可能不占满高度
 → 嵌套布局需要逐层考虑 Stretch

3.3 Margin 的作用

1
2
3
4
5
6
7


Margin="10,5,10,5" ← 左,上,右,下

Measure 阶段：
 availableSize 减去 Margin 后再传给子

Arrange 阶段：
 finalRect 收缩 Margin 后才是子的实际矩形

四、内置 Panel 全家桶

4.1 Canvas（绝对定位）

1
2
3
4


<Canvas>
 <Button Canvas.Left="10" Canvas.Top="20" Content="A"/>
 <Button Canvas.Left="50" Canvas.Top="60" Content="B"/>
</Canvas>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


特点：
 - 类似 WinForms 的绝对定位
 - Canvas.Left/Top 附加属性定位
 - 子元素超出 Canvas 区域不裁剪（除非 ClipToBounds=true）
 - 不参与 measure（子元素 DesiredSize 直接用）

适用：
 - 图形 / 自定义绘图场景
 - 元素位置完全可控
 - 不适合业务 UI（不响应缩放、不国际化）

4.2 StackPanel（栈）

1
2
3
4
5
6
7


<StackPanel Orientation="Vertical">
 <Button/> <Button/> <Button/>
</StackPanel>

<StackPanel Orientation="Horizontal">
 <Button/> <Button/> <Button/>
</StackPanel>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


特点：
 - 单方向排列（垂直 / 水平）
 - 主轴累加，副轴 Stretch
 - 不滚动（超出区域就溢出）

 垂直模式：
 - 高度 = 所有子的高度之和
 - 宽度 = 父宽度（子 HorizontalAlignment=Stretch）

 水平模式：反过来

适用：
 - 简单列表
 - 工具栏

注意：
 - 不要用来装大数据！StackPanel 不虚拟化
 - 1000 个 Button 在 StackPanel 里 = 性能崩盘

4.3 WrapPanel（自动换行）

1
2
3


<WrapPanel Orientation="Horizontal" ItemWidth="100" ItemHeight="40">
 <Button/> <Button/> <Button/> ... <!-- 自动换行 -->
</WrapPanel>

1
2
3
4
5
6
7
8


特点：
 - 类似 StackPanel，但装不下时换行
 - 主轴到边界 → 跳到下一行/列

适用：
 - 标签云
 - 缩略图网格
 - 工具栏自动布局

4.4 DockPanel（停靠）

1
2
3
4
5
6
7


<DockPanel LastChildFill="True">
 <Button DockPanel.Dock="Top" Content="Top"/>
 <Button DockPanel.Dock="Bottom" Content="Bottom"/>
 <Button DockPanel.Dock="Left" Content="Left"/>
 <Button DockPanel.Dock="Right" Content="Right"/>
 <Button Content="Center (填充)"/>
</DockPanel>

1
2
3
4
5
6
7


特点：
 - DockPanel.Dock 附加属性
 - 子元素依次"贴边"
 - LastChildFill=true（默认）→ 最后一个填充剩余

适用：
 - 经典窗口布局（顶部工具栏 + 底部状态栏 + 主内容）

4.5 Grid（栅格）—— WPF 最复杂 Panel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<Grid>
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/> <!-- 自动高度 -->
 <RowDefinition Height="*"/> <!-- 占剩余 -->
 <RowDefinition Height="2*"/> <!-- 占 2/3 剩余 -->
 <RowDefinition Height="100"/> <!-- 固定 -->
 </Grid.RowDefinitions>

 <Grid.ColumnDefinitions>
 <ColumnDefinition Width="*"/>
 <ColumnDefinition Width="Auto"/>
 </Grid.ColumnDefinitions>

 <Button Grid.Row="0" Grid.Column="0" Content="A"/>
 <Button Grid.Row="1" Grid.Column="1" Grid.RowSpan="2" Content="B"/>
</Grid>

Grid 的度量公式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


Height 取值三种：
 Auto：根据内容算高度
 *（含 N*）：按比例瓜分剩余空间
 数字：固定像素

算法（行高度计算）：
 1. 先满足所有"固定数字"
 2. 然后满足所有 Auto（看内容的 DesiredSize）
 3. 剩余空间按 * 比例分配

例：
 总高度 600
 Row 0: Auto → 50（看内容）
 Row 1: * → 200（占 1/3 剩余 500）
 Row 2: 2* → 400（占 2/3）
 Row 3: 100 → 100（固定）
 剩余 = 600 - 50 - 100 = 450
 Row 1 = 450 / 3 = 150
 Row 2 = 450 * 2/3 = 300

1
2
3
4


适用：
 - 几乎所有业务 UI
 - 表单、对话框、仪表盘
 - 默认首选 Grid

4.6 UniformGrid（等分 Grid）

1
2
3


<UniformGrid Rows="3" Columns="2">
 <Button/> <Button/> <Button/> <Button/> <Button/> <Button/>
</UniformGrid>

1
2
3
4
5
6
7


特点：
 - 行列均分（不需要 RowDefinitions）
 - 简化版的 Grid（适合 N×M 等分）

适用：
 - 计算器数字键盘
 - 等宽缩略图

4.7 VirtualizingStackPanel（虚拟化栈）

1
2
3


<ListBox ItemsSource="{Binding Items}">
 <!-- ListBox 默认就用 VirtualizingStackPanel -->
</ListBox>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


特点：
 - StackPanel 的虚拟化版本
 - 只渲染可见区域的子元素
 - 滚动时动态创建/销毁

适用：
 - 大数据列表（1000+ 项）
 - 配合 ItemsControl 系列控件

启用条件：
 1. ItemsControl 派生控件（ListBox/ComboBox/ListView/DataGrid）
 2. 默认 Panel 是 VirtualizingStackPanel
 3. VirtualizingPanel.IsVirtualizing=true（默认开）

4.8 Panel 选型表

场景	推荐 Panel
业务表单 / 主窗口	Grid
简单垂直/水平列表	StackPanel
大数据列表	ListBox（VirtualizingStackPanel）
顶部工具栏 + 主区域	DockPanel
标签云 / 自动换行	WrapPanel
等分网格	UniformGrid
绝对定位（图形）	Canvas

五、DPI 感知与设备无关像素

5.1 DIP（Device Independent Pixel）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


WPF 的"1像素"不是物理像素，是 1/96 英寸

 1 DIP = 1/96 inch
 1 inch = 96 DIP

物理像素计算：
 显示器 DPI = 96（默认）→ 1 DIP = 1 物理像素
 显示器 DPI = 192（200% 缩放）→ 1 DIP = 2 物理像素
 显示器 DPI = 144（150% 缩放）→ 1 DIP = 1.5 物理像素

意义：
 - 你写 Width=100 → 任意 DPI 下都是 100 DIP
 - 高分屏自动缩放，不糊
 - 不需要写 dpi 适配代码

5.2 DPI 感知声明

1
2
3
4
5
6
7
8


<!-- app.manifest -->
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
 <application xmlns="urn:schemas-microsoft-com:asm.v3">
 <windowsSettings>
 <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
 </windowsSettings>
 </application>
</assembly>

1
2
3
4
5
6
7
8


PerMonitorV2：
 - 每个显示器独立 DPI（拖到不同屏幕自适应）
 - 现代 WPF 推荐
 - .NET 4.7+ 支持

不声明：
 - 系统级 DPI（DPI=Aware）→ 拖到不同屏幕糊
 - 或 DPI=Unaware → 全程被系统拉伸（最糊）

5.3 物理像素转换

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// DIP → 物理像素
var dpi = VisualTreeHelper.GetDpi(this);
double pixelsPerDip = dpi.PixelsPerDip; // 1.0 / 1.5 / 2.0 / ...

double dipWidth = 100;
double pixelWidth = dipWidth * pixelsPerDip;

// PresentationSource 旧 API
var matrix = PresentationSource.FromVisual(this).CompositionTarget.TransformToDevice;
double pixelWidth = dipWidth * matrix.M11;

六、布局槽与 Transform

6.1 LayoutSlot

1
2
3
4
5
6
7


每个 FrameworkElement 有一个 LayoutSlot（布局槽）
 = Arrange 时父给的 Rect
 = 在父坐标系里的位置和大小

可视化辅助（调试时打开 ShowLayoutGrid）：
 RenderTransform 不影响 LayoutSlot
 LayoutTransform 会影响 LayoutSlot（重新 measure）

6.2 RenderTransform vs LayoutTransform

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<!-- RenderTransform：渲染时变换，不触发 layout -->
<Button Content="A" RenderTransformOrigin="0.5,0.5">
 <Button.RenderTransform>
 <RotateTransform Angle="45"/>
 </Button.RenderTransform>
</Button>

<!-- LayoutTransform：变换后重新参与 layout -->
<Button Content="A">
 <Button.LayoutTransform>
 <RotateTransform Angle="45"/>
 </Button.LayoutTransform>
</Button>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


区别：
 RenderTransform：
 - 渲染时变换
 - 不影响周围元素布局
 - 性能好（动画用这个）
 - 可能与邻居重叠

 LayoutTransform：
 - 变换后影响 measure/arrange
 - 邻居会被推开
 - 性能稍差
 - 适合"永久性"变换（如旋转标签）

七、虚拟化深度

7.1 为什么需要虚拟化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


无虚拟化：
 ListBox 绑定 10000 项
 → ItemsControl 创建 10000 个 ItemContainer
 → 每个 ItemContainer 有完整视觉树
 → 内存爆炸 + 启动卡死

有虚拟化：
 → 只创建可见的 ~20 个
 → 滚动时回收/创建
 → 内存恒定

7.2 虚拟化的必要条件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


1. ItemsControl 派生（ListBox/ListView/DataGrid/ComboBox）
 - 普通 ItemsControl 默认不虚拟化
 - ListBox 以后默认虚拟化

2. ItemsPanel 必须是 VirtualizingStackPanel
 <ListBox>
 <ListBox.ItemsPanel>
 <ItemsPanelTemplate>
 <VirtualizingStackPanel/>
 </ItemsPanelTemplate>
 </ListBox.ItemsPanel>
 </ListBox>

3. VirtualizingPanel.IsVirtualizing=True（默认开）

4. VirtualizingPanel.VirtualizationMode=Standard（默认）
 或 Recycling（容器回收，性能更好）

7.3 影响虚拟化的属性

1
2
3
4
5


<ListBox VirtualizingPanel.IsVirtualizing="True"
 VirtualizingPanel.VirtualizationMode="Recycling"
 VirtualizingPanel.ScrollUnit="Pixel"
 VirtualizingPanel.CacheLength="2,2"
 VirtualizingPanel.CacheLengthUnit="Page">

1
2
3
4
5
6
7


ScrollUnit：
 Item（默认）：按 Item 滚动，可能不流畅
 Pixel：按像素滚动，更流畅

CacheLength：
 保留多少额外项（预渲染）
 "2,2" = 上下各预渲染 2 屏

八、实战：自定义 TimelinePanel

把两阶段布局用上——一个按时间轴排布子元素的 Panel。

8.1 需求

子元素带 DateTime 附加属性
按时间从左到右排布
同一时刻的元素垂直堆叠

8.2 附加属性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public static class Timeline
{
 public static readonly DependencyProperty TimeProperty =
 DependencyProperty.RegisterAttached(
 "Time",
 typeof(DateTime),
 typeof(Timeline),
 new PropertyMetadata(DateTime.Now));

 public static DateTime GetTime(DependencyObject obj)
 => (DateTime)obj.GetValue(TimeProperty);

 public static void SetTime(DependencyObject obj, DateTime value)
 => obj.SetValue(TimeProperty, value);
}

8.3 Panel 实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72


public class TimelinePanel : Panel
{
 public DateTime StartTime
 {
 get => (DateTime)GetValue(StartTimeProperty);
 set => SetValue(StartTimeProperty, value);
 }

 public static readonly DependencyProperty StartTimeProperty =
 DependencyProperty.Register(
 nameof(StartTime),
 typeof(DateTime),
 typeof(TimelinePanel),
 new FrameworkPropertyMetadata(
 DateTime.MinValue,
 FrameworkPropertyMetadataOptions.AffectsArrange));

 public DateTime EndTime
 {
 get => (DateTime)GetValue(EndTimeProperty);
 set => SetValue(EndTimeProperty, value);
 }

 public static readonly DependencyProperty EndTimeProperty =
 DependencyProperty.Register(
 nameof(EndTime),
 typeof(DateTime),
 typeof(TimelinePanel),
 new FrameworkPropertyMetadata(
 DateTime.MaxValue,
 FrameworkPropertyMetadataOptions.AffectsArrange));

 // 第一阶段：度量
 protected override Size MeasureOverride(Size availableSize)
 {
 double maxHeight = 0;
 foreach (UIElement child in InternalChildren)
 {
 child.Measure(availableSize);
 maxHeight = Math.Max(maxHeight, child.DesiredSize.Height);
 }
 return new Size(availableSize.Width, maxHeight);
 }

 // 第二阶段：安排
 protected override Size ArrangeOverride(Size finalSize)
 {
 var span = (EndTime - StartTime).TotalSeconds;
 if (span <= 0) return finalSize;

 // 跟踪每"列"已堆叠的高度
 var laneHeights = new Dictionary<int, double>();

 foreach (UIElement child in InternalChildren)
 {
 var time = Timeline.GetTime(child);
 var ratio = (time - StartTime).TotalSeconds / span;
 var x = ratio * finalSize.Width;

 // 简化：同一时间窗内堆叠
 int lane = (int)(x / 80); // 每列宽 80 DIP
 double y = laneHeights.GetValueOrDefault(lane, 0);

 var rect = new Rect(x, y, Math.Min(80, child.DesiredSize.Width), child.DesiredSize.Height);
 child.Arrange(rect);

 laneHeights[lane] = y + child.DesiredSize.Height + 4;
 }

 return finalSize;
 }
}

8.4 使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<Window xmlns:local="clr-namespace:MyApp">
 <local:TimelinePanel StartTime="2026-05-01" EndTime="2026-05-31" Height="300">
 <Border local:Timeline.Time="2026-05-03" Background="LightBlue" Width="70" Height="40">
 <TextBlock Text="事件 1"/>
 </Border>
 <Border local:Timeline.Time="2026-05-10" Background="LightCoral" Width="70" Height="40">
 <TextBlock Text="事件 2"/>
 </Border>
 <Border local:Timeline.Time="2026-05-10" Background="LightGreen" Width="70" Height="40">
 <TextBlock Text="事件 3"/>
 </Border>
 <Border local:Timeline.Time="2026-05-25" Background="LightYellow" Width="70" Height="40">
 <TextBlock Text="事件 4"/>
 </Border>
 </local:TimelinePanel>
</Window>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


效果：
 - 事件按时间从左到右
 - 同时间的（5-10）垂直堆叠
 - 改 StartTime/EndTime 触发 AffectsArrange 重新布局

知识点：
 ✅ MeasureOverride 返回所有子最大高度
 ✅ ArrangeOverride 按时间算 X，按 lane 算 Y
 ✅ 附加属性带"元数据"
 ✅ AffectsArrange 标记触发 re-layout

九、常见陷阱

9.1 StackPanel + Grid * 不工作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<!-- ❌ Grid 的 * 在 StackPanel 里失效 -->
<StackPanel>
 <Grid>
 <Grid.RowDefinitions>
 <RowDefinition Height="*"/> <!-- 想填充剩余 -->
 <RowDefinition Height="Auto"/>
 </Grid.RowDefinitions>
 </Grid>
</StackPanel>

<!-- StackPanel 给子元素无限高度
 Grid 的 * 不知道"剩余"是多少
 → * 行变 0 高度 -->

1
2
3
4
5
6
7
8
9


✅ 用 Grid 嵌套
<Grid>
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="*"/>
 <RowDefinition Height="Auto"/>
 </Grid.RowDefinitions>
 <!-- 内容 -->
</Grid>

9.2 用 Width 而不是 Margin 控制间距

1
2
3
4
5


<!-- ❌ 用 MinWidth 制造空隙 -->
<Button Content="OK" MinWidth="100" MinHeight="30"/>

<!-- ✅ 用 Margin / Padding -->
<Button Content="OK" Margin="10" Padding="20,5"/>

9.3 大数据用 StackPanel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- ❌ 10000 项在 StackPanel 里 = 内存爆炸 -->
<ItemsControl ItemsSource="{Binding Items}">
 <ItemsControl.ItemsPanel>
 <ItemsPanelTemplate>
 <StackPanel/>
 </ItemsPanelTemplate>
 </ItemsControl.ItemsPanel>
</ItemsControl>

<!-- ✅ 用 ListBox（自带虚拟化） -->
<ListBox ItemsSource="{Binding Items}"/>

9.4 DesiredSize 不能直接设

1
2
3
4
5
6


// ❌ 不能
button.DesiredSize = new Size(100, 30);

// ✅ 只能通过 Measure 让子元素自己算
button.Measure(new Size(double.PositiveInfinity, double.PositiveInfinity));
var desired = button.DesiredSize;

9.5 Canvas 子元素不响应父缩放

1
2
3
4
5
6
7


<!-- Canvas 里的子元素位置固定 -->
<Canvas Width="1000">
 <Button Canvas.Left="950" Content="靠右"/>
</Canvas>
<!-- Canvas 缩到 500 宽度，按钮还在 950 → 溢出 -->

<!-- Canvas 不适合响应式 UI -->

十、与 CSS Flex/Grid 的对比

后端工程师可能也写过前端。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


CSS Flex WPF StackPanel
─────────────────────────────────────────────
display: flex （默认 StackPanel）
flex-direction: row/column Orientation
justify-content HorizontalAlignment
align-items VerticalAlignment
gap Margin
flex-grow （StackPanel 不支持）

CSS Grid WPF Grid
─────────────────────────────────────────────
grid-template-columns ColumnDefinitions
1fr / auto * / Auto
grid-column: 1 / 3 Grid.ColumnSpan
gap Margin

关键差异：
 - CSS 用 fr（fraction），WPF 用 *（语义一致）
 - CSS 自动响应式，WPF 要手动（一般够用）
 - WPF 没有 CSS 的 gap（用 Margin 模拟）

十一、性能与调试

11.1 Layout 性能

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Layout 是 WPF 性能敏感区域：
 - 改一个属性触发 InvalidateMeasure → 整树重算
 - 复杂嵌套 Grid 在大窗口里慢

优化：
 1. 减少 Grid 嵌套（用 RowSpan/ColumnSpan 替代）
 2. 大数据用虚拟化
 3. 避免在 Loaded 里反复改 Margin/Width
 4. UIElement 而不是 FrameworkElement（如果不需要布局特征）
 5. 用 IsHitTestVisible=false 跳过命中测试

11.2 调试布局

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


Visual Studio WPF Designer：
 - 选中元素 → Properties → Layout
 - 实时看 ActualWidth/ActualHeight

WPF Performance Suite（旧 SDK）：
 - 可视化布局边界
 - 找到 measure 次数过多的元素

代码调试：
 Console.WriteLine($"Desired: {element.DesiredSize}");
 Console.WriteLine($"Render: {element.RenderSize}");
 Console.WriteLine($"Actual: {element.ActualWidth}x{element.ActualHeight}");

十二、小结

本文深入 WPF 的布局系统：

WinForms 绝对定位 vs WPF 两阶段布局
Measure（度量）与 Arrange（安排）
HorizontalAlignment/VerticalAlignment/Margin 三件套
内置 Panel 全家桶（Canvas/StackPanel/DockPanel/WrapPanel/Grid/UniformGrid/VirtualizingStackPanel）
Grid 的三种 Height（Auto/*/固定）与度量公式
DPI 感知与设备无关像素
RenderTransform vs LayoutTransform
虚拟化的必要条件与优化属性
实战：自定义 TimelinePanel（MeasureOverride + ArrangeOverride + 附加属性）

1
2
3
4


记住三句话：
 1. 布局是两阶段：Measure 问子多大，Arrange 告诉子去哪
 2. 业务 UI 优先 Grid，能用 Grid 就别嵌套 StackPanel
 3. 大数据列表必须虚拟化——这是从"卡死"到"丝滑"的开关

下一篇将进入 WPF 的核心特性——数据绑定。理解了 DP + 绑定，WPF 的"声明式响应式"就立起来了。

WPF 学习笔记（三）：路由事件——事件的三种传播策略

Mon, 27 Apr 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。

承接上一篇依赖属性。WPF 的另一个地基——路由事件（RoutedEvent）——和 DP 一脉相承。事实上，路由事件注册机制几乎是 DP 的翻版：EventManager.RegisterRoutedEvent 对应 DependencyProperty.Register，全局表 + 元数据的思路完全一致。

但路由事件在"行为"上和普通 .NET 事件差异巨大：它能在视觉树里向上或向下传播。这是 WPF 区别于 WinForms 的关键。

本文要回答：

为什么按钮内 Label 的 Click 事件，能被外层 Window 监听到？事件到底是怎么"路由"的？

一、CLR 事件的局限

1.1 普通 .NET 事件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public class Button
{
 public event EventHandler Click;

 protected virtual void OnClick()
 => Click?.Invoke(this, EventArgs.Empty);
}

// 订阅
button.Click += (s, e) => MessageBox.Show("Clicked");

1
2
3
4
5
6


CLR 事件的本质：
 - 一个委托链（多播委托）
 - 触发时依次调用所有订阅者
 - 严格 1:N 订阅模式

问题：WPF 的 UI 是树形结构，事件需要"沿树传播"

1.2 WPF 的痛点

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


场景：复杂 Button
 Button 内部有 Image + TextBlock（模板展开后）

 <Button Click="Handler">
 <StackPanel>
 <Image Source="ok.png"/>
 <TextBlock Text="OK"/>
 </StackPanel>
 </Button>

用户点击 Image 区域：
 WinForms 模型：只有 Image 收到 Click（要 Image 自己暴露事件）
 WPF 模型：Button 收到 Click（视觉树自动路由）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


CLR 事件做不到：
 1. Image 点击 → Image 内部触发 → 怎么"通知"外层 Button？
 - 在 Image 上挂 MouseLeftButtonDown，转发给 Button？崩溃
 - 在 Button 模板内每个元素挂事件？维护噩梦

 2. 同样的逻辑要在多个外层处理（Button、StackPanel、Window）？
 - 每个 handler 都要重新订阅？

WPF 的答案：路由事件
 事件不在"被点击的元素"上"原地触发"
 而是沿视觉树传播，每个节点都有机会处理

二、三种路由策略

2.1 总览

1
2
3
4
5


策略 方向 命名约定 触发顺序
─────────────────────────────────────────────────────────────
Tunneling 从根到目标 PreviewXxx 先发生
Bubbling 从目标到根 Xxx 后发生
Direct 仅目标 Xxx 不传播

2.2 Bubbling（冒泡）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


事件从被点击的元素开始，沿视觉树向上冒泡到根

 Window
 └─ Grid
 └─ Button ← 用户点击这里
 └─ Border
 └─ TextBlock ← 实际命中（鼠标精确点在文字上）

冒泡顺序：
 TextBlock → Border → Button → Grid → Window

每层都能：
 - 处理事件（订阅 handler）
 - 检查 e.Source（事件源）
 - 设置 e.Handled = true 终止进一步冒泡

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


适用：
 - 大部分输入事件：Click、MouseDown、KeyDown
 - 大部分业务场景都能用 Bubbling

典型应用：
 外层容器统一处理子元素的点击
 <StackPanel Button.Click="Panel_Click">
 <Button/> <Button/> <Button/>
 </StackPanel>
 三个按钮的点击都汇聚到 StackPanel 的 handler

2.3 Tunneling（隧道）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


事件从根开始，沿视觉树向下"挖"到目标元素

 Window ← PreviewMouseDown 先触发
 └─ Grid
 └─ Button
 └─ Border
 └─ TextBlock ← PreviewMouseDown 最后到这

隧道顺序：
 Window → Grid → Button → Border → TextBlock

然后 Bubbling 顺序相反：
 TextBlock → Border → Button → Grid → Window

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


命名约定：
 Preview + Bubbling 名字
 PreviewMouseDown (Tunneling)
 MouseDown (Bubbling)

适用：
 - 拦截/取消事件（"我不要让子元素收到 Click"）
 - 全局快捷键（窗口级 PreviewKeyDown 拦截所有键盘事件）

典型应用：
 <Window PreviewKeyDown="Window_PreviewKeyDown">
 <TextBox/> <!-- 想禁用某些键 -->
 </Window>

 在 Window_PreviewKeyDown 里 e.Handled = true
 → TextBox 收不到 KeyDown（因为 Preview 终止了隧道）

2.4 Direct（直接）

1
2
3
4
5
6
7


事件不传播，只在目标元素触发

适用：
 - 不需要传播的事件（如 MouseEnter、MouseLeave）
 - 概念上就是"元素本身的事件"（如 TextChanged）

Direct 事件和 CLR 事件几乎一样，只是用了路由事件的基础设施

2.5 完整对照

策略	方向	触发顺序	终止机制
Tunneling	根→目标	先	e.Handled=true
Bubbling	目标→根	后	e.Handled=true
Direct	不传播	仅目标	N/A

三、注册路由事件

3.1 注册代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


public class MyButton : Button
{
 // 1. 注册
 public static readonly RoutedEvent TapEvent = EventManager.RegisterRoutedEvent(
 name: "Tap", // 名称
 routingStrategy: RoutingStrategy.Bubbling, // 策略
 handlerType: typeof(RoutedEventHandler), // handler 类型
 ownerType: typeof(MyButton)); // 所属类型

 // 2. CLR 事件包装器
 public event RoutedEventHandler Tap
 {
 add => AddHandler(TapEvent, value);
 remove => RemoveHandler(TapEvent, value);
 }

 // 3. 触发
 protected virtual void OnTap()
 {
 RoutedEventArgs args = new RoutedEventArgs(TapEvent);
 RaiseEvent(args); // ← 注意：用 RaiseEvent 不是 Invoke
 }
}

3.2 注册内部

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


EventManager.RegisterRoutedEvent 内部：
 1. 创建 RoutedEvent 实例（不可变）
 2. 注册到全局表 RoutedEventList（key=OwnerType+Name）
 3. 返回 RoutedEvent 实例

RoutedEvent 的"身份"：
 - Name: "Tap"
 - RoutingStrategy: Bubbling
 - HandlerType: typeof(RoutedEventHandler)
 - GlobalIndex: int（全局唯一）

 和 DP 一模一样的模式：static field + 全局表 + GlobalIndex

3.3 CLR 包装器的作用

1
2
3
4
5


public event RoutedEventHandler Tap
{
 add => AddHandler(TapEvent, value);
 remove => RemoveHandler(TapEvent, value);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


注意两点：
 1. add/remove 用 AddHandler/RemoveHandler，不是 +=
 2. AddHandler 接受 RoutedEvent，不是普通委托

 CLR 事件只是给 XAML 提供语法糖：
 <local:MyButton Tap="Handler"/> ← XAML 解析时调 add

 也可以不通过 CLR 包装直接订阅：
 myButton.AddHandler(MyButton.TapEvent, (RoutedEventHandler)Handler);
 → 等价

四、e.Handled 的真相

这是路由事件最容易踩的坑。

4.1 表面行为

1
2
3
4


private void Button_Click(object sender, RoutedEventArgs e)
{
 e.Handled = true; // ← 设置后，事件不再向上冒泡
}

4.2 真相：Handled 不阻止已挂接的 handler

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


"e.Handled = true" 的实际语义：
 ✅ 终止事件的进一步路由（不再向上/向下传播）
 ❌ 不阻止"已经在当前节点挂接的 handler"

举例：
 Button 上挂了两个 Click handler：
 button.Click += Handler1;
 button.Click += Handler2;

 Handler1 设置 e.Handled = true
 → Handler2 仍然被调用！（同节点所有 handler 都调用）

 但事件不会再向 Button 的父级冒泡

4.3 handledEventsToo：强制监听

1
2
3
4
5
6


// 普通订阅：Handled=true 的不调用
button.Click += Handler;

// 强制订阅：Handled=true 也调用
button.AddHandler(Button.ClickEvent, new RoutedEventHandler(Handler),
 handledEventsToo: true);

1
2
3
4
5
6
7


应用场景：
 - 日志/审计：想知道所有点击事件（不管有没有被处理）
 - 全局监控：调试事件流
 - 不破坏业务逻辑的"旁观者"

 注意：handledEventsToo=true 的 handler 永远会调用
 → 即使别人 e.Handled=true 也阻止不了你

4.4 XAML 中无法直接 handledEventsToo

1
2
3
4
5
6
7


<!-- ❌ XAML 不支持 handledEventsToo 语法 -->
<Button Click="Handler" HandledEventsToo="true"/> <!-- 不存在 -->

<!-- ✅ 必须在代码后置中订阅 -->
<Button x:Name="myButton"/>
<!-- 代码 -->
myButton.AddHandler(Button.ClickEvent, handler, handledEventsToo: true);

五、Source 与 OriginalSource

RoutedEventArgs 有两个"源"。

5.1 两个源

1
2
3
4
5
6
7
8


public class RoutedEventArgs : EventArgs
{
 public object Source { get; set; } // 逻辑树源
 public object OriginalSource { get; } // 视觉树源（最深的命中）
 public RoutedEvent RoutedEvent { get; } // 事件标识
 public bool Handled { get; set; } // 处理状态
 public RoutingStrategy RoutingStrategy { get; }
}

5.2 区别

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


场景：Button 模板里有 Image
 <Button Click="Handler">
 <Image Source="ok.png"/>
 </Button>

用户点击 Image：
 OriginalSource = Image（视觉树最深的命中元素）
 Source = Button（逻辑树源，通常更"业务友好"）

WPF 自动维护：
 OriginalSource 永远是视觉树命中元素
 Source 默认 = OriginalSource，但有些事件会"提升"到逻辑父级

5.3 实战

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


private void Clickable_Click(object sender, RoutedEventArgs e)
{
 // sender = 挂接事件的元素（如 Button）
 // e.Source = "逻辑上"被点击的（通常是 Button 或逻辑子项）
 // e.OriginalSource = 视觉树最深命中（可能是个 Border 或 TextBlock）

 Console.WriteLine($"Sender: {sender}");
 Console.WriteLine($"Source: {e.Source}");
 Console.WriteLine($"OriginalSource: {e.OriginalSource}");
}

六、命中测试与视觉树传播

路由事件的传播路径，依赖于"命中测试"——哪个元素被点中了。

6.1 命中测试

1
2
3
4
5


鼠标点击屏幕坐标 → WPF 沿视觉树找到最深命中元素

 Point pt = e.GetPosition(null);
 HitTestResult result = VisualTreeHelper.HitTest(rootVisual, pt);
 var hitElement = result.VisualHit;

1
2
3
4
5
6
7
8


WPF 命中测试规则：
 1. 从根视觉元素开始
 2. 检查每个子元素的区域
 3. 找最深命中的元素（叶节点优先）
 4. 命中元素 OriginalSource

 Transparent 元素也能命中（不像 CSS）
 IsHitTestVisible=false 的元素不参与命中

6.2 路由路径

1
2
3
4
5
6
7
8
9


OriginalSource = TextBlock（命中元素）

Tunneling 路径（PreviewMouseDown）：
 Window → Grid → Button → Border → ContentPresenter → TextBlock
 （从根到最深命中的视觉父链）

Bubbling 路径（MouseDown）：
 TextBlock → ContentPresenter → Border → Button → Grid → Window
 （从最深命中的视觉父链反向到根）

七、附加事件（Attached Event）

类似附加属性，事件也可以"附加"。

7.1 XAML 中的附加事件

1
2
3
4
5
6
7
8
9


<StackPanel Button.Click="StackPanel_Click">
 <Button Content="1"/>
 <Button Content="2"/>
 <Button Content="3"/>
</StackPanel>

<!-- StackPanel 本身没有 Click 事件 -->
<!-- 但 Bubbling 的 Click 会冒泡经过它 -->
<!-- 用 Button.Click="..." 显式订阅 -->

7.2 底层机制

1
2


// XAML 解析时
stackPanel.AddHandler(Button.ClickEvent, new RoutedEventHandler(StackPanel_Click));

1
2
3
4
5


注意：
 - Bubbling 路由事件才有"附加订阅"意义
 - 直接订阅（Button.Click="..."）写在 Button 上等价
 - 写在外层 StackPanel 上利用冒泡
 - 一次订阅捕获所有子按钮的点击

7.3 实战：动态子元素的事件处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<ItemsControl ItemsSource="{Binding Items}">
 <ItemsControl.ItemsPanel>
 <ItemsPanelTemplate>
 <StackPanel Button.Click="Item_Click"/>
 </ItemsPanelTemplate>
 </ItemsControl.ItemsPanel>

 <ItemsControl.ItemTemplate>
 <DataTemplate>
 <Button Content="{Binding Name}" Tag="{Binding}"/>
 </DataTemplate>
 </ItemsControl.ItemTemplate>
</ItemsControl>

1
2
3
4
5
6
7
8
9


private void Item_Click(object sender, RoutedEventArgs e)
{
 if (e.Source is Button btn && btn.Tag is ItemModel item)
 {
 // 业务处理
 SelectItem(item);
 e.Handled = true; // 避免向上冒泡触发其他 handler
 }
}

八、Class Handlers vs Instance Handlers

路由事件有两类 handler。

8.1 Instance Handler

1

button.Click += MyHandler; // 实例级订阅

1
2
3
4


特点：
 - 针对单个实例
 - 在路由路径上每个节点订阅一次
 - 默认 Handled=true 时不调用

8.2 Class Handler

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 在静态构造函数中注册
static MyButton()
{
 EventManager.RegisterClassHandler(
 typeof(MyButton),
 Button.ClickEvent,
 new RoutedEventHandler(ClassClickHandler));
}

private static void ClassClickHandler(object sender, RoutedEventArgs e)
{
 // 所有 MyButton 实例的 Click 都会先到这里
}

1
2
3
4
5
6
7
8
9


特点：
 - 类型级（所有 MyButton 实例共享一个 handler）
 - 在 Instance Handler 之前调用
 - 可选 handledEventsToo（即使已被处理也调用）

WPF 内部大量使用 Class Handler：
 - Button 的 Click 由 MouseLeftButtonDown 的 Class Handler 触发
 - TextBox 的 TextChanged 在内部多处用 Class Handler
 - 这是"控件内部行为"的标准实现方式

8.3 调用顺序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


事件触发时执行顺序：

 1. Tunneling 阶段（Preview）
 - 各层的 Class Handler（Tunneling）
 - 各层的 Instance Handler（Tunneling）

 2. 目标元素
 - Class Handler
 - Instance Handler

 3. Bubbling 阶段
 - 各层的 Class Handler
 - 各层的 Instance Handler

九、内建路由事件速查

9.1 常用 Bubbling 事件

事件	触发条件	命名空间
Click	鼠标点击 Button 类控件	ButtonBase
MouseDown	鼠标按下	UIElement
MouseUp	鼠标抬起	UIElement
MouseMove	鼠标移动	UIElement
MouseWheel	滚轮	UIElement
KeyDown	键盘按下	UIElement
KeyUp	键盘抬起	UIElement
TextInput	文本输入	UIElement
SizeChanged	尺寸改变	FrameworkElement
Loaded	加载完成	FrameworkElement

9.2 对应的 Tunneling（Preview）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


PreviewMouseDown → MouseDown
PreviewMouseUp → MouseUp
PreviewMouseMove → MouseMove
PreviewMouseWheel → MouseWheel
PreviewKeyDown → KeyDown
PreviewKeyUp → KeyUp
PreviewTextInput → TextInput
PreviewDragEnter → DragEnter
...

每个 Bubbling 输入事件几乎都有 Preview 版本
注意：Click 没有 PreviewClick！
 （Click 是 MouseLeftButtonDown 的"组合事件"，由 ButtonBase 内部触发）

9.3 常用 Direct 事件

事件	说明
MouseEnter	鼠标进入元素
MouseLeave	鼠标离开元素
MouseDirect	直接设备事件
ToolTipOpening	工具提示打开
ContextMenuOpening	右键菜单打开

十、实战：全局快捷键 + 鼠标日志

把前面学的全用上——一个调试用的"全局事件监控"窗口。

10.1 需求

按 Ctrl+Shift+D 切换调试面板
监听所有键盘事件，显示按键日志
监听所有鼠标点击，显示命中元素

10.2 XAML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


<Window x:Class="EventMonitor.MainWindow"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 Title="Event Monitor" Width="800" Height="600"
 PreviewKeyDown="Window_PreviewKeyDown"
 PreviewMouseDown="Window_PreviewMouseDown">
 <Grid>
 <Grid.RowDefinitions>
 <RowDefinition Height="*"/>
 <RowDefinition Height="Auto"/>
 </Grid.RowDefinitions>

 <ScrollViewer Grid.Row="0" x:Name="logScroll">
 <StackPanel x:Name="logPanel"/>
 </ScrollViewer>

 <StatusBar Grid.Row="1">
 <TextBlock x:Name="statusText" Text="监控中"/>
 </StatusBar>
 </Grid>
</Window>

10.3 Code-behind

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69


public partial class MainWindow : Window
{
 private bool _monitoring = true;

 public MainWindow()
 {
 InitializeComponent();
 }

 // 全局快捷键：隧道事件先于子元素
 private void Window_PreviewKeyDown(object sender, KeyEventArgs e)
 {
 // Ctrl+Shift+D 切换监控
 if (e.Key == Key.D &&
 (Keyboard.Modifiers & ModifierKeys.Control) == ModifierKeys.Control &&
 (Keyboard.Modifiers & ModifierKeys.Shift) == ModifierKeys.Shift)
 {
 _monitoring = !_monitoring;
 statusText.Text = _monitoring ? "监控中" : "已暂停";
 e.Handled = true; // 阻止子元素收到
 return;
 }

 if (_monitoring)
 {
 LogEvent($"KEY: {e.Key} (Modifiers: {Keyboard.Modifiers})");
 }
 }

 private void Window_PreviewMouseDown(object sender, MouseButtonEventArgs e)
 {
 if (!_monitoring) return;

 var pos = e.GetPosition(this);
 LogEvent($"MOUSE: {e.ChangedButton} at ({pos.X:F0}, {pos.Y:F0})");

 // 找命中的视觉树路径
 var hit = VisualTreeHelper.HitTest(this, pos);
 if (hit?.VisualHit != null)
 {
 var path = new List<string>();
 var current = hit.VisualHit;
 while (current != null)
 {
 path.Add(current.GetType().Name);
 current = VisualTreeHelper.GetParent(current);
 }
 path.Reverse();
 LogEvent($"PATH: {string.Join(" → ", path)}");
 }
 }

 private void LogEvent(string text)
 {
 var entry = new TextBlock
 {
 Text = $"[{DateTime.Now:HH:mm:ss.fff}] {text}",
 FontFamily = new FontFamily("Consolas"),
 Margin = new Thickness(2)
 };
 logPanel.Children.Add(entry);

 // 限制日志数量
 if (logPanel.Children.Count > 200)
 logPanel.Children.RemoveAt(0);

 logScroll.ScrollToEnd();
 }
}

10.4 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


✅ Tunneling（PreviewKeyDown/PreviewMouseDown）拦截事件
✅ e.Handled = true 阻止子元素
✅ 视觉树路径遍历（VisualTreeHelper）
✅ 命中测试（HitTest）
✅ Keyboard.Modifiers 判断组合键
✅ 调试用日志面板

观察：
 - Preview 事件在 Window 级订阅，能拦到所有子元素的事件
 - e.Handled=true 阻止后续路由（子元素的 KeyDown 收不到）
 - VisualTreeHelper.HitTest 给出精确命中

十一、与 ASP.NET Core 中间件对比

后端工程师最容易理解的方式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


ASP.NET Core 中间件：
 pipeline ← 请求
 中间件 1（前）
 中间件 2
 ...
 终端处理器
 ...
 中间件 2
 中间件 1（后）
 pipeline → 响应

WPF 路由事件：
 Tunneling（前）
 外层 Preview
 内层 Preview
 目标元素
 内层
 外层
 Bubbling（后）

共同点：
 - 都是"链式处理"
 - 都有短路机制（context.Handled / e.Handled）
 - 都允许"中间层"介入处理

区别：
 - 中间件是"注册顺序"，路由事件是"视觉树层级"
 - 中间件可以"修改请求继续传"，路由事件不能改 e.Source
 - 中间件无 Preview/AFTER 区分，路由事件有 Tunneling/Bubbling

十二、常见陷阱

12.1 Preview 里不要做副作用

1
2
3
4
5
6
7


// ❌ 在 PreviewMouseDown 里改 UI
private void Window_PreviewMouseDown(...)
{
 someElement.Visibility = Visibility.Visible; // 改了布局
 // 此时路由还在进行，布局变化可能引发其他事件
 // → 死循环或异常
}

1
2
3


正确做法：
 - Preview 里只读 e，决定是否 e.Handled=true
 - 改 UI 留给 Bubbling 阶段或 dispatcher 异步

12.2 sender 不是 e.Source

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// StackPanel 上挂 Button.Click
<StackPanel Button.Click="Panel_Click">
 <Button/> <Button/>
</StackPanel>

private void Panel_Click(object sender, RoutedEventArgs e)
{
 // sender = StackPanel（挂事件的元素）
 // e.Source = Button（实际被点击的）
 // 不是同一个！

 var clickedButton = (Button)e.Source;
}

12.3 自定义路由事件别用 Click 命名

1
2
3
4
5
6


// ❌ 容易和基类 Click 混淆
public event RoutedEventHandler Click { ... }

// ✅ 用差异化名字
public event RoutedEventHandler Tap { ... }
public event RoutedEventHandler LongPress { ... }

12.4 路由事件的内存泄漏

1
2
3
4
5
6


// ❌ 短生命周期对象订阅长生命周期事件
window.MainMenu.Button.Click += shortLived.Handler;
// shortLived 死不掉（被 window 持有）

// ✅ 用弱事件或显式取消订阅
window.MainMenu.Button.Click -= shortLived.Handler;

十三、小结

本文深入 WPF 的路由事件系统：

CLR 事件为什么不够用（不能沿树传播）
三种路由策略（Tunneling / Bubbling / Direct）
RegisterRoutedEvent 与全局表
e.Handled 的真相（终止路由 ≠ 阻止已挂接的 handler）
Source vs OriginalSource 的语义差别
命中测试决定事件源
附加事件的语法本质
Class Handler 与 Instance Handler 的执行顺序
实战：全局事件监控窗口

1
2
3
4


记住三句话：
 1. 路由事件是"沿视觉树传播的事件"，不是普通委托
 2. e.Handled=true 只终止进一步路由，不阻止同节点其他 handler
 3. Preview 是隧道，能拦截子元素的事件——全局快捷键的标准武器

下一篇将进入 WPF 的布局系统——两阶段布局（Measure/Arrange）和内置 Panel 全家桶。

WPF 学习笔记（二）：依赖属性——WPF 的属性系统

Thu, 23 Apr 2026 10:00:00 +0800

写在前面

版本说明：基于 .NET 8 LTS。本文涉及的反编译代码基于 .NET 8 实际版本（可能因版本略有差异）。

依赖属性（DependencyProperty，简称 DP）是 WPF 的"地基"。绑定、样式、动画、模板、属性继承——所有 WPF 引以为傲的特性都建立在它之上。如果你写 WPF 但不理解 DP，就像写 C# 但不理解引用类型——能用，但出 bug 时一脸懵。

本文要回答的核心问题：

为什么 WPF 要重新发明一遍"属性"？它和普通 CLR 属性到底差在哪？

一、CLR 属性的局限

先理解问题，再看解决方案。

1.1 一个普通 CLR 属性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


public class Person
{
 private string _name;
 public string Name
 {
 get => _name;
 set
 {
 if (_name != value)
 {
 _name = value;
 OnPropertyChanged(nameof(Name));
 }
 }
 }
}

1
2


看起来挺完美，为什么 WPF 还要重新搞？
 → 因为 UI 框架对"属性"有更复杂的需求

1.2 UI 框架的四大需求

需求 1：默认值

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Button 默认 Background = SystemColors.ControlBrush
但 Button 类有几百个属性，全部用字段存默认值？
 → 一个 Button 实例 = 几百字段的内存开销
 → 一万个 Button = 几百万字段，全部都是默认值

CLR 属性的方案：
 private static readonly Brush DefaultBackground = ...;
 private Brush _background = DefaultBackground;
 → 每个实例还是有一个字段引用
 → 引用很便宜，但 WPF 控件属性多到不行，还是不能接受

需求 2：属性继承

1
2
3
4
5
6


Window 字号 16 → 子元素默认继承 16
Window.Foreground = Red → 子元素默认也是 Red

CLR 属性做不到：
 → 父级改了，子级怎么知道？
 → 你要么写循环遍历子元素（崩溃），要么用事件机制（繁琐）

需求 3：变更通知

1
2
3
4
5
6
7


Button.Width 改了 → 父容器要重新布局
Button.Background 改了 → 要重绘
Button.IsEnabled=false → 子元素也要禁用

CLR 属性：
 需要为每个属性手动写 INotifyPropertyChanged
 → 一堆样板代码

需求 4：样式覆盖

1
2
3
4
5
6


Button 默认 Background = Control
Style 改成 Red
本地又设置了 Background = Blue
最后值是？

CLR 属性只有一个值，没法表达"多层优先级"

1.3 WPF 的答案：依赖属性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


DependencyProperty 的核心思想：
 属性值不存"字段"，存"按需的稀疏字典"
 优先级、默认值、继承、通知，全部由属性系统统一管理

类比后端：
 CLR 属性 = 直接字段存储
 DP = Redis 式的"分层数据源 + 优先级合并 + 通知"

 多个值源（本地/样式/默认/继承/动画/...）→ 取优先级最高的
 任何一个值源变化 → 自动重新计算并通知

二、DependencyProperty.Register

2.1 第一个 DP

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


public class CircularProgress : Control
{
 // 1. 注册依赖属性
 public static readonly DependencyProperty ProgressProperty =
 DependencyProperty.Register(
 name: nameof(Progress), // 属性名
 propertyType: typeof(double), // 类型
 ownerType: typeof(CircularProgress), // 所属类型
 typeMetadata: new PropertyMetadata(
 defaultValue: 0.0, // 默认值
 propertyChangedCallback: OnProgressChanged // 变更回调
 ),
 validateValueCallback: IsValidProgress // 校验回调
 );

 // 2. CLR 属性包装器（用 GetValue/SetValue）
 public double Progress
 {
 get => (double)GetValue(ProgressProperty);
 set => SetValue(ProgressProperty, value);
 }

 // 3. 校验：必须是 0~100
 private static bool IsValidProgress(object value)
 => value is double d && d >= 0 && d <= 100;

 // 4. 变更回调（静态！实例通过 sender 拿到）
 private static void OnProgressChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
 {
 var control = (CircularProgress)d;
 var newProgress = (double)e.NewValue;
 control.InvalidateVisual(); // 触发重绘
 }
}

2.2 Register 干了什么

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


DependencyProperty.Register 内部：

1. 创建一个 DependencyProperty 实例（DP 是不可变对象）
2. 把它注册到全局哈希表 PropertyFromName
 key = (OwnerType, Name) 元组
 value = DependencyProperty 实例
3. 返回这个实例（通常存为 static readonly 字段）

属性标识：
 每个 DP 有唯一的 GlobalIndex（int）
 DP 的"身份"由 (OwnerType + Name) 或 GlobalIndex 唯一确定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// DependencyProperty 内部结构（简化）
public class DependencyProperty
{
 public string Name { get; } // "Progress"
 public Type PropertyType { get; } // typeof(double)
 public Type OwnerType { get; } // typeof(CircularProgress)
 public int GlobalIndex { get; } // 全局序号（int）
 public PropertyMetadata DefaultMetadata { get; } // 默认元数据
 public ValidateValueCallback ValidateValueCallback { get; }
}

2.3 全局哈希表

1
2
3
4
5
6


PropertyFromName（DP 的全局注册表）：
 key: (OwnerType, Name)
 value: DependencyProperty

注册一次永久存在，所有实例共享这个 DP 实例
→ 这是"稀疏存储"的前提：DP 本身不存值，只存"元数据"

三、稀疏存储：DependencyObject 内部

属性值存哪里？答案：在 DependencyObject 实例上的"稀疏数组"。

3.1 EffectiveValueEntry

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


// DependencyObject 内部（简化）
public abstract class DependencyObject : DispatcherObject
{
 // 数组：只存"被设置过"的属性
 private EffectiveValueEntry[] _effectiveValues;

 public object GetValue(DependencyProperty dp)
 {
 // 1. 在 _effectiveValues 中按 GlobalIndex 查
 var entry = FindEntry(dp.GlobalIndex);
 if (entry != null) return entry.Value;

 // 2. 没设置过 → 走默认值/继承/其他源
 return GetValueFromSources(dp);
 }

 public void SetValue(DependencyProperty dp, object value)
 {
 // 1. 校验
 if (!dp.ValidateValueCallback(value))
 throw new ArgumentException();

 // 2. 强制（Coerce）
 value = CoerceValue(dp, value);

 // 3. 写入 _effectiveValues
 SetEntry(dp.GlobalIndex, value);

 // 4. 触发 PropertyChanged 回调
 RaisePropertyChanged(dp, oldValue, value);
 }
}

3.2 稀疏存储的含义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


有效值数组的设计：
 - 控件有几百个属性，但实例上通常只设置几十个
 - 其他属性用默认值（不进数组）
 - 数组只占几十个槽位，而不是几百个字段

类比：
 一个 .NET 对象的实例字段 = 强制存储（每个字段都占位）
 DP 的 EffectiveValueEntry[] = 稀疏存储（只有非默认值才占位）

效果：
 - 1000 个 Button 实例 × 每个 Button 有 200 个 DP
 - 假设每个实例平均只设置 20 个非默认值
 - 内存 = 1000 × 20 entries ≈ 1000 × 20 × 32 字节 ≈ 640 KB
 - 如果用字段：1000 × 200 × 8 字节 ≈ 1.6 MB

3.3 DependencyPropertyKey（只读 DP）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


public class MyControl : Control
{
 // 只读 DP 需要用 RegisterReadOnly
 private static readonly DependencyPropertyKey IsMouseOverInternalPropertyKey =
 DependencyProperty.RegisterReadOnly(
 nameof(IsMouseOverInternal),
 typeof(bool),
 typeof(MyControl),
 new PropertyMetadata(false));

 // 公开的 DP 用 Key.DependencyProperty 暴露（不能 SetValue）
 public static readonly DependencyProperty IsMouseOverInternalProperty =
 IsMouseOverInternalPropertyKey.DependencyProperty;

 public bool IsMouseOverInternal
 {
 get => (bool)GetValue(IsMouseOverInternalProperty);
 // 注意：没有 set，外部不能赋值
 }

 // 内部可以用 Key 设置
 private void UpdateMouseOver(bool value)
 {
 SetValue(IsMouseOverInternalPropertyKey, value);
 }
}

1
2
3
4
5
6
7


为什么需要 DependencyPropertyKey？
 - 普通 DP 任何代码都能 SetValue（不安全）
 - 只读 DP 想让外部只读，但内部能改
 - 用 Key 作为 SetValue 的"令牌"，没 Key 就不能改
 - Key 是 private，外部访问不到 → 安全

常见只读 DP：IsMouseOver、IsKeyboardFocusWithin、HasItems

四、属性值优先级（11 级）

这是 DP 最容易被忽略、但实战最常踩坑的部分。一个属性的"最终值"由多个来源决定，按优先级取最高。

4.1 11 级优先级（从高到低）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


1. Coercion (CoerceValueCallback) ← 强制值（永远最高）
2. Active Animations ← 动画（占用的属性）
3. Local Value ← 本地值（XAML 直接写/SetValue）
4. TemplatedParent Template ← 模板内
5. Style Triggers ← 样式触发器
6. Template Triggers ← 模板触发器
7. Style Setters ← 样式 Setter
8. Theme Style Triggers ← 主题样式触发器
9. Theme Style Setters ← 主题样式 Setter
10. Inherited ← 继承（来自父级）
11. Default ← 默认值（永远最低）

4.2 优先级实战例子

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


<!-- 默认值（第 11 级） -->
<Button Content="OK"/>
<!-- Background = ButtonChrome 的默认色 -->

<!-- 样式 Setter（第 7 级） -->
<Button Content="OK">
 <Button.Style>
 <Style TargetType="Button">
 <Setter Property="Background" Value="Yellow"/>
 </Style>
 </Button.Style>
</Button>
<!-- Background = Yellow -->

<!-- 本地值（第 3 级，覆盖 Setter） -->
<Button Content="OK" Background="Red">
 <Button.Style>...</Button.Style>
</Button>
<!-- Background = Red -->

<!-- 动画（第 2 级，覆盖本地） -->
<Button Content="OK" Background="Red">
 <Button.Triggers>
 <EventTrigger RoutedEvent="Button.Loaded">
 <BeginStoryboard>
 <Storyboard>
 <ColorAnimation Storyboard.TargetProperty="(Button.Background).(SolidColorBrush.Color)"
 To="Green" Duration="0:0:1"/>
 </Storyboard>
 </BeginStoryboard>
 </EventTrigger>
 </Button.Triggers>
</Button>
<!-- 动画期间 Background = Green -->

4.3 调试技巧

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 查看一个 DP 的当前值来源
var source = button.GetLocalValueEnumerator();
while (source.MoveNext())
{
 var dp = source.Current.Property;
 var value = source.Current.Value;
 Console.WriteLine($"{dp.Name} = {value}");
}

// 看完整 effective value（含默认）
var current = button.GetValue(Button.BackgroundProperty);

五、PropertyMetadata 回调链

PropertyMetadata 提供三个回调，按固定顺序执行。

5.1 三个回调

1
2
3
4
5
6
7
8
9


DependencyProperty.Register(
 "Progress",
 typeof(double),
 typeof(CircularProgress),
 new PropertyMetadata(
 defaultValue: 0.0,
 propertyChangedCallback: OnProgressChanged, // ③ 变更后
 coerceValueCallback: CoerceProgress), // ② 强制
 validateValueCallback: IsValidProgress); // ① 校验

5.2 执行顺序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


SetValue(value) 调用时：

 ① ValidateValueCallback(value)
 → 返回 false 抛 ArgumentException
 → 用于"硬约束"（必须是 0~100、不能为 null）
 → 静态、无状态（不依赖实例）

 ② CoerceValueCallback(instance, value)
 → 返回"调整后的值"
 → 用于"软约束"（Progress 不能超过 MaxProgress）
 → 实例方法（可以访问其他属性）

 ③ 写入 EffectiveValueEntry

 ④ PropertyChangedCallback(instance, args)
 → OldValue → NewValue 通知
 → 触发重绘、布局、级联属性变更
 → 静态签名（但 d 参数是实例）

 ⑤ 触发绑定、动画、监听器

5.3 回调应用场景

回调	何时调用	典型用途
ValidateValueCallback	SetValue 前	类型/范围校验（必须 0~100）
CoerceValueCallback	Validate 后、写入前	关联约束（不超过 MaxProgress）
PropertyChangedCallback	写入后	触发副作用（重绘、级联、通知）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// 经典案例：MinWidth ≤ Width ≤ MaxWidth
public double Width
{
 get => (double)GetValue(WidthProperty);
 set => SetValue(WidthProperty, value);
}

private static object CoerceWidth(DependencyObject d, object baseValue)
{
 var control = (MyControl)d;
 var width = (double)baseValue;

 if (width < control.MinWidth) return control.MinWidth;
 if (width > control.MaxWidth) return control.MaxWidth;
 return width;
}

1
2
3
4
5
6
7
8


为什么 Coerce 在 PropertyChanged 之前？
 → Coerce 是"调整"，不是"拒绝"
 → 你给 Width=-10，它返回 MinWidth，然后正常处理
 → PropertyChanged 拿到的就是调整后的值

为什么 Validate 在 Coerce 之前？
 → Validate 是静态硬约束（拒绝非法值）
 → Coerce 是动态软约束（根据当前状态调整）

5.4 PropertyChangedCallback 是静态的

1
2
3
4
5
6
7
8
9


// ❌ 错误想法：实例方法
private void OnProgressChanged(DependencyObject d, ...) { ... }

// ✅ 实际签名：static
private static void OnProgressChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
 var control = (CircularProgress)d; // 通过 d 拿到实例
 ...
}

1
2
3
4
5
6
7
8


为什么是 static？
 → DP 注册是类型级别的（static field）
 → 回调要被多个实例共享
 → 如果是实例方法，每次 Register 都要绑定 this（不合理）
 → 通过 d 参数把实例传进来（标准模式）

后端类比：
 类似 ASP.NET Core 的中间件——签名是静态的，靠 context 拿请求实例

六、附加属性（Attached Property）

附加属性是一种特殊的 DP，“属于类型 A，但能设置在类型 B 的实例上”。

6.1 经典例子：Grid.Row

1
2
3
4
5
6
7
8
9


<Grid>
 <Grid.RowDefinitions>
 <RowDefinition/>
 <RowDefinition/>
 </Grid.RowDefinitions>

 <Button Grid.Row="0" Content="Row 0"/>
 <Button Grid.Row="1" Content="Row 1"/>
</Grid>

1
2
3
4
5
6
7
8
9


观察：
 - Button 没有 Row 属性
 - 但 Grid.Row="0" 写在 Button 上
 - 这是"附加属性"

含义：
 Grid 类型定义了 RowProperty
 但 RowProperty 的值存在 Button 实例上
 Grid 读取 Button 的 Row 时，从 Button 实例上拿

6.2 注册附加属性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


public class Grid : Panel
{
 public static readonly DependencyProperty RowProperty =
 DependencyProperty.RegisterAttached(
 "Row", // 名称
 typeof(int), // 类型
 typeof(Grid), // 所属类型
 new PropertyMetadata(0)); // 默认值

 // Get/Set 访问器（XAML 解析器约定）
 public static int GetRow(DependencyObject element)
 => (int)element.GetValue(RowProperty);

 public static void SetRow(DependencyObject element, int value)
 => element.SetValue(RowProperty, value);
}

1
2
3
4
5
6


RegisterAttached vs Register：
 - Register：DP 属于自己的类型，自己的实例用
 - RegisterAttached：DP 属于自己的类型，但其他类型实例上能设置

底层存储一样：都存在 DependencyObject 的 _effectiveValues 里
区别只在 API 表面（Get/Set 是静态方法）

6.3 附加属性的应用

1
2
3
4
5
6
7
8
9


布局：Grid.Row/Column、Canvas.Left/Top、DockPanel.Dock
布局相关：KeyboardNavigation.TabNavigation、ToolTipService.ToolTip
行为：SpellCheck.IsEnabled、ContextMenuService.ContextMenu

设计哲学：
 "把行为附加到任意元素上"
 → Button 本身不需要知道"我属于第几行"
 → 但布局系统（Grid）需要知道
 → 用附加属性让"无关类型"也能携带信息

6.4 自定义附加属性示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// 给任意 FrameworkElement 加"水印"附加属性
public static class WatermarkService
{
 public static readonly DependencyProperty WatermarkProperty =
 DependencyProperty.RegisterAttached(
 "Watermark",
 typeof(string),
 typeof(WatermarkService),
 new PropertyMetadata(null, OnWatermarkChanged));

 public static string GetWatermark(DependencyObject obj)
 => (string)obj.GetValue(WatermarkProperty);

 public static void SetWatermark(DependencyObject obj, string value)
 => obj.SetValue(WatermarkProperty, value);

 private static void OnWatermarkChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
 {
 // 给 TextBox 加水印逻辑
 if (d is TextBox tb)
 {
 // ... 实现水印
 }
 }
}

1

<TextBox local:WatermarkService.Watermark="请输入用户名"/>

七、属性继承（Property Inheritance）

某些 DP 会"从父级继承"。

7.1 哪些属性会继承

1
2
3
4
5
6
7
8
9


默认会继承的属性：
 - FontSize、FontFamily、FontWeight
 - Foreground、Background（部分）
 - CultureInfo
 - DataContext（最重要！）

继承的语义：
 子元素没设置这个属性 → 用父元素的值
 子元素设置了 → 用自己的值

7.2 注册时指定继承

1
2
3
4
5
6
7
8


public static readonly DependencyProperty MyFontSizeProperty =
 DependencyProperty.RegisterAttached(
 "MyFontSize",
 typeof(double),
 typeof(MyControl),
 new FrameworkPropertyMetadata(
 defaultValue: 12.0,
 flags: FrameworkPropertyMetadataOptions.Inherits)); // 标记可继承

1
2
3
4
5
6
7


FrameworkPropertyMetadataOptions：
 - Inherits：可继承
 - AffectsMeasure、AffectsArrange、AffectsRender：影响布局/绘制
 - BindsTwoWayByDefault：默认双向绑定
 - ...

 这就是为什么改 Window.FontSize，所有子控件字号也变

7.3 DataContext 继承

1
2
3
4
5
6


<Window DataContext="{Binding MainViewModel}">
 <StackPanel> <!-- 继承 DataContext -->
 <TextBox Text="{Binding Name}"/> <!-- 用 Window 的 DataContext -->
 <Button Content="{Binding Title}"/>
 </StackPanel>
</Window>

1
2
3
4
5


关键事实：
 - DataContext 是 DP 且默认可继承
 - 子元素没设置 → 用父级
 - 绑定默认从 DataContext 取值
 - 这是 WPF 数据绑定的根基（详见第 5 篇）

八、DP 与绑定的关系

DP 是绑定的"目标"载体。

8.1 双向通路

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


DP 作为绑定目标：
 <TextBox Text="{Binding Name}"/>
 → TextBox.Text 是 DP
 → 绑定系统监听 DP 的 PropertyChanged
 → 数据源变了，TextBox 自动更新

INotifyPropertyChanged 作为绑定源：
 ViewModel.Name 改变 → 触发 INPC
 → 绑定系统收到通知
 → TextBox.Text 自动更新

8.2 为什么绑定目标必须是 DP

1
2
3
4
5
6
7


绑定需要"属性变更通知"机制
 → CLR 属性没有内建通知
 → DP 的 PropertyChangedCallback 天然就是通知
 → 所以绑定目标必须是 DP

 TextBox.Text 是 DP ✅
 普通 POCO 的属性不能作为绑定目标 ❌

九、实战：CircularProgress 控件

把前面学的全部用上——一个带 Coerce 校验的进度环控件。

9.1 完整代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84


public class CircularProgress : FrameworkElement
{
 public static readonly DependencyProperty ProgressProperty =
 DependencyProperty.Register(
 nameof(Progress),
 typeof(double),
 typeof(CircularProgress),
 new FrameworkPropertyMetadata(
 defaultValue: 0.0,
 propertyChangedCallback: OnProgressChanged,
 affectsRender: true), // 改了要重绘
 validateValueCallback: IsValidProgress);

 public double Progress
 {
 get => (double)GetValue(ProgressProperty);
 set => SetValue(ProgressProperty, value);
 }

 public static readonly DependencyProperty StrokeColorProperty =
 DependencyProperty.Register(
 nameof(StrokeColor),
 typeof(Color),
 typeof(CircularProgress),
 new FrameworkPropertyMetadata(
 defaultValue: Colors.DodgerBlue,
 propertyChangedCallback: OnVisualPropChanged,
 affectsRender: true));

 public Color StrokeColor
 {
 get => (Color)GetValue(StrokeColorProperty);
 set => SetValue(StrokeColorProperty, value);
 }

 private static bool IsValidProgress(object value)
 => value is double d && !double.IsNaN(d) && !double.IsInfinity(d);

 private static void OnProgressChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
 {
 var control = (CircularProgress)d;
 // 在 0~100 之间是数据约束（用 Validate）
 // 这里只是触发副作用：调试日志
 Trace.WriteLine($"Progress: {e.OldValue} → {e.NewValue}");
 }

 private static void OnVisualPropChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
 {
 ((CircularProgress)d).InvalidateVisual();
 }

 protected override void OnRender(DrawingContext dc)
 {
 var size = Math.Min(ActualWidth, ActualHeight);
 var center = new Point(ActualWidth / 2, ActualHeight / 2);
 var radius = size / 2 - 10;

 // 背景圆
 dc.DrawEllipse(null, new Pen(Brushes.LightGray, 6), center, radius, radius);

 // 进度圆弧
 var angle = Progress / 100 * 360;
 var pen = new Pen(new SolidColorBrush(StrokeColor), 6);
 var start = new Point(center.X + radius, center.Y);
 var arcEnd = ComputeArcEnd(center, radius, angle);

 var geometry = new PathGeometry();
 geometry.Figures.Add(new PathFigure(
 start,
 new[] { new ArcSegment(arcEnd, new Size(radius, radius), 0,
 angle > 180 ? SweepDirection.Counterclockwise : SweepDirection.Clockwise, true) },
 false));

 dc.DrawGeometry(null, pen, geometry);
 }

 private static Point ComputeArcEnd(Point center, double radius, double angle)
 {
 var rad = angle * Math.PI / 180;
 return new Point(
 center.X + radius * Math.Cos(rad),
 center.Y + radius * Math.Sin(rad));
 }
}

9.2 使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<Window xmlns:local="clr-namespace:MyApp">
 <StackPanel>
 <local:CircularProgress
 Width="100" Height="100"
 Progress="75"
 StrokeColor="DodgerBlue"/>

 <Slider x:Name="slider" Minimum="0" Maximum="100" Value="75"/>
 <local:CircularProgress
 Width="100" Height="100"
 Progress="{Binding ElementName=slider, Path=Value}"
 StrokeColor="Orange"/>
 </StackPanel>
</Window>

9.3 知识点覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


✅ DependencyProperty.Register（注册）
✅ CLR 属性包装器
✅ ValidateValueCallback（范围校验）
✅ PropertyChangedCallback（触发重绘）
✅ FrameworkPropertyMetadata（AffectsRender）
✅ 绑定作为 DP 目标（Slider.Value → Progress）

调试场景：
 - Progress = -5 → ValidateValueCallback 返回 false → ArgumentException
 - Progress = 200 → 同样失败
 - Progress = 50.5 → 通过 → OnProgressChanged 触发 → OnRender 重绘

十、DP 与 CLR 属性的对比

维度	CLR 属性	依赖属性
存储	字段（每实例都有）	稀疏数组（只存非默认值）
通知	需手动 INotifyPropertyChanged	内建 PropertyChangedCallback
默认值	每实例字段引用	类型级共享
优先级	单一值	11 级优先级
继承	无	FrameworkPropertyMetadataOptions.Inherits
校验	set 内写 if	ValidateValueCallback
强制	set 内调整	CoerceValueCallback
绑定	不能作为目标	可以作为目标
动画	不能动画	可以动画
性能	字段访问快	GetValue/SetValue 略慢（但优化过）

1
2
3
4
5
6
7


后端视角总结：
 CLR 属性 = "字段 + 简单 getter/setter"
 DP = "字段 + 多源优先级合并 + 校验/强制/通知链 + 稀疏存储"

 DP 比 CLR 属性"重"，但提供了 UI 框架需要的一切
 WPF 的代价：每个属性访问多走一层 GetValue/SetValue
 WPF 的收益：绑定、动画、样式、继承全部白送

十一、常见陷阱

11.1 CLR 包装器里别写逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// ❌ 错误：包装器里写副作用
public double Progress
{
 get => (double)GetValue(ProgressProperty);
 set
 {
 SetValue(ProgressProperty, value);
 InvalidateVisual(); // ❌ 这里写没用！
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


为什么没用？
 - WPF 内部可能直接调 SetValue，绕过 CLR 包装器
 - 比如绑定、动画、样式 Setter 都不经过你的 wrapper
 - 副作用必须放在 PropertyChangedCallback

✅ 正确：
 private static void OnProgressChanged(DependencyObject d, ...)
 {
 ((CircularProgress)d).InvalidateVisual();
 }

11.2 默认值不能是引用类型实例

1
2
3
4


// ❌ 错误：所有实例共享同一个 Brush
new PropertyMetadata(new SolidColorBrush(Colors.Red))

// 修改默认值会"污染"所有实例

1
2
3
4


正确做法：
 1. 默认值用不可变类型（颜色、数字、字符串）
 2. 或在静态构造函数里注册默认值并 freeze
 3. 复杂类型默认值用 null + PropertyChanged 时延迟创建

11.3 不要用普通属性触发 DP 变更

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// ❌
public double Progress
{
 get => ...;
 set
 {
 _progress = value; // ❌ 直接改字段
 SetValue(ProgressProperty, value); // ✅ 必须走 SetValue
 }
}

11.4 注册时类型要匹配

1
2
3


// ❌ 注册类型是 int，但 CLR 属性是 double
DependencyProperty.Register("Progress", typeof(int), ...)
public double Progress { ... }

1
2
3


WPF 不会编译期检查这个匹配
运行时会抛 InvalidCastException（难调试）
→ 注册类型和 CLR 属性类型必须严格一致

十二、小结

本文深入 WPF 的属性系统：

CLR 属性的四大局限（默认值/继承/通知/优先级）
DependencyProperty.Register 与全局哈希表
稀疏存储模型（EffectiveValueEntry 数组）
属性值 11 级优先级
PropertyMetadata 三回调链（Validate → Coerce → PropertyChanged）
附加属性（RegisterAttached）的设计哲学
属性继承（FrameworkPropertyMetadataOptions.Inherits）
DP 作为绑定目标
实战：CircularProgress 控件（覆盖注册、校验、变更回调）

1
2
3
4


记住三句话：
 1. DP 不是"另一种属性"，是"分层属性系统"——多源优先级合并
 2. SetValue 是入口——校验、强制、通知、绑定、动画都从这进
 3. CLR 属性包装器只是"门面"，别在里面写逻辑（会被绕过）

下一篇将进入路由事件系统——WPF 的另一个地基。它和依赖属性一脉相承，理解了 DP，再看路由事件会非常顺。

WPF 学习笔记（一）：架构总览与 XAML 原理

Sun, 19 Apr 2026 10:00:00 +0800

写在前面

版本说明：本文基于 .NET 8 LTS + Visual Studio 2022，所有代码在 Windows 10/11 验证。

WPF（Windows Presentation Foundation）是微软 2006 年随 .NET Framework 3.0 发布的 UI 框架。当时它是一次彻底的重新设计——统一了 UI、文档、图形、媒体——但快 20 年过去了，WPF 既老又新：老在 API 表面（很多类从 3.0 没动过），新在运行时（.NET 8 上原生编译、性能持续优化）。

写这个系列是因为我自己从 ASP.NET Core 后端切到 WPF 桌面开发时踩了不少"概念陷阱"：依赖属性为什么和普通属性不一样？路由事件到底在路由什么？为什么 UI 必须单线程？这些问题不搞清楚，写出来的 WPF 代码就是"用 WinForms 思维写 WPF"——能跑但别扭。

本文是开篇，先建立 WPF 的心智模型：架构分层、视觉树/逻辑树、XAML 编译流水线。理解了这些，后续 11 篇才有共同语言。

一、WPF 是什么：与 WinForms 的根本区别

1.1 一个根本区别：保留模式 vs 立即模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


WinForms（立即模式 Immediate Mode 的近亲，本质是封装 User32）：
 - 控件是 Window Handle（HWND）的包装
 - 每次重绘：WM_PAINT → OnPaint → Graphics 画
 - 画完即"忘"，下次重绘重新画
 - 每个控件一个 HWND，靠 User32 GDI 渲染

WPF（保留模式 Retained Mode）：
 - 控件不是 HWND，是托管对象
 - 整个 UI 是一棵"视觉树"，常驻内存
 - 渲染由 DirectX 接管，WPF 把视觉树提交给 GPU
 - 一个窗口通常只有一个 HWND（顶层），内部全是自绘

1
2
3
4
5
6
7


类比：
 WinForms 像"画黑板"——你画一笔是一笔，擦了就没了
 WPF 像"摆积木"——你描述积木的位置和形状，渲染器替你画

后端视角：
 WinForms = 命令式 UI（你自己控制重绘）
 WPF = 声明式 UI（你描述树，框架渲染）

1.2 为什么要换一套

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


GDI / User32 的瓶颈（2006 年视角）：
 - 不支持硬件加速（GPU 没用上）
 - 不支持透明（Alpha 混合）
 - 文字渲染粗糙（ClearType 也救不了复杂排版）
 - 控件之间 HWND 隔离，做"圆角按钮+渐变背景"要subclass 黑魔法
 - DPI 处理粗糙（高分屏糊一脸）

WPF 用 DirectX 重写渲染层：
 - GPU 硬件加速
 - 矢量图形（缩放不失真）
 - 透明、抗锯齿、复杂文字排版
 - 设备无关像素（DPI 自动适配）
 - 一致的控件模型（一个 HWND，全部自绘）

1.3 WPF 的代价

1
2
3
4
5
6
7
8
9


代价 1：内存占用高（视觉树常驻）
代价 2：启动慢（要构建视觉树、加载 BAML、解析资源）
代价 3：线程模型严格（UI 单线程，Dispatcher 调度）
代价 4：学习曲线陡（XAML + DP + 绑定 + 路由事件 + MVVM）

但换来的是：
 ✅ 复杂 UI 容易做（动画、3D、文档、富绑定）
 ✅ 数据驱动的开发模式（声明式绑定）
 ✅ 设计师与工程师协作（XAML + Blend）

二、架构分层

2.1 自上而下分层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


┌─────────────────────────────────────────────────┐
│ 你的应用（Application + Views） │
├─────────────────────────────────────────────────┤
│ PresentationFramework.dll（托管） │
│ - 控件（Button/TextBox/ListBox...） │
│ - Style/Template/Binding │
│ - Application/Window/FrameworkElement │
├─────────────────────────────────────────────────┤
│ PresentationCore.dll（托管） │
│ - 视觉树核心：Visual/UIElement/ContentElement │
│ - DependencyProperty / RoutedEvent │
│ - Dispatcher │
├─────────────────────────────────────────────────┤
│ WindowsBase.dll（托管） │
│ - DispatcherObject │
│ - Freezable、Animatable │
│ - 基础数据结构 │
├─────────────────────────────────────────────────┤
│ milcore.dll（非托管，C++） │
│ - Media Integration Layer │
│ - 与 DirectX 通信 │
│ - Composition 线程 │
├─────────────────────────────────────────────────┤
│ DirectX / User32 / GDI │
│ - GPU 渲染 / 顶层 HWND │
└─────────────────────────────────────────────────┘

2.2 各层职责

层	程序集	职责
你的应用	-	XAML + ViewModel + 业务逻辑
PresentationFramework	PresentationFramework.dll	高层控件、样式、模板、应用模型
PresentationCore	PresentationCore.dll	视觉树核心、DP/RE、Dispatcher
WindowsBase	WindowsBase.dll	Dispatcher 基类、Freezable
milcore	milcore.dll（非托管）	DirectX 通信、Composition 线程
DirectX/User32	系统	GPU 渲染、HWND 管理

1
2
3
4
5
6
7


关键观察：
 1. 大部分代码在托管层（C#），但渲染核心 milcore 是非托管 C++
 2. milcore 跑在单独的 Composition 线程，与 UI 线程解耦
 → UI 线程算视觉树变化，Composition 线程提交 GPU
 → 这就是 WPF 动画"不卡 UI"的根本原因（动画在 Composition 线程）
 3. 一个窗口通常只有一个 HWND（HwndSource）
 → 内部所有控件没有独立 HWND（除非 Popup、WebBrowser 等互操作控件）

2.3 为什么分层这么细

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


后端类比：和 ASP.NET Core 的分层思路一致

ASP.NET Core 分层：
 你的应用 → MVC/Razor → HttpAbstractions → Kestrel → OS Socket

WPF 分层：
 你的应用 → Framework → Core → WindowsBase → milcore → DirectX

共同点：
 - 核心层（Core / Abstractions）只放"地基"概念
 - 高层（Framework / MVC）放具体功能
 - 这样可以单独替换高层（比如 WPF 自己换 Skin、ASP.NET Core 换 MVC/Razor Pages）

WPF 的具体体现：
 - DependencyProperty 在 PresentationCore（地基）
 - Button 这种控件在 PresentationFramework（上层）
 - 你要写"纯高性能绘图"，可以只用 PresentationCore 的 Visual，绕开 Framework 的控件开销

三、视觉树与逻辑树

WPF 内部其实有两棵树——视觉树（Visual Tree）和逻辑树（Logical Tree）。这两棵树大部分时候长得像，但语义不同。

3.1 逻辑树：XAML 的"骨架"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


XAML：
<Window>
 <Grid>
 <Button Content="OK"/>
 <Button Content="Cancel"/>
 </Grid>
</Window>

逻辑树：
 Window
 └─ Grid
 ├─ Button (OK)
 └─ Button (Cancel)

1
2
3
4


特点：
 - 就是 XAML 元素的父子关系
 - 用于：属性继承、资源查找、DataContext 流转
 - API：LogicalTreeHelper

3.2 视觉树：渲染的"实现细节"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


视觉树是逻辑树的"展开版"，包含所有渲染细节：

视觉树（Button "OK" 展开后）：
 Button
 └─ ButtonChrome（边框）
 └─ ContentPresenter
 └─ TextBlock（"OK" 文字）
 └─ Glyph（字模）

特点：
 - 比逻辑树更深，包含模板内部的元素
 - 用于：渲染、路由事件传播、命中测试
 - API：VisualTreeHelper

3.3 两棵树的对比

维度	逻辑树	视觉树
含义	XAML 结构	渲染结构（含模板展开）
深度	浅	深
用途	资源/属性继承/DataContext	渲染/路由事件/命中测试
API	LogicalTreeHelper	VisualTreeHelper
变化	XAML 改了才变	模板展开会动态变

1
2
3
4


实战意义：
 - 想找"父窗口"：用 LogicalTreeHelper（逻辑层级稳定）
 - 想找"鼠标点击的内部元素"：用 VisualTreeHelper.HitTest（视觉层级精确）
 - 想遍历所有 TextBlock：可能要遍历视觉树（模板内可能有）

3.4 实战：打印两棵树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


public static void DumpTrees(DependencyObject root)
{
 Console.WriteLine("=== Logical Tree ===");
 DumpLogical(root, 0);
 Console.WriteLine("\n=== Visual Tree ===");
 DumpVisual(root, 0);
}

static void DumpLogical(DependencyObject d, int depth)
{
 Console.WriteLine($"{new string(' ', depth * 2)}{d.GetType().Name}");
 foreach (var child in LogicalTreeHelper.GetChildren(d))
 if (child is DependencyObject dep)
 DumpLogical(dep, depth + 1);
}

static void DumpVisual(DependencyObject d, int depth)
{
 Console.WriteLine($"{new string(' ', depth * 2)}{d.GetType().Name}");
 for (int i = 0; i < VisualTreeHelper.GetChildrenCount(d); i++)
 DumpVisual(VisualTreeHelper.GetChild(d, i), depth + 1);
}

四、XAML 的本质

XAML 是 WPF 最显眼的特征。但它经常被误解为"另一种语言"。其实它是对象初始化的语法糖。

4.1 XAML = XML + 对象初始化

1
2


<!-- XAML -->
<Button Content="Click Me" Width="100" Height="30"/>

等价的 C#：

1
2
3
4


var button = new Button();
button.Content = "Click Me";
button.Width = 100;
button.Height = 30;

1
2
3
4
5


关键事实：
 - XAML 元素 = new 一个对象（类型 = xmlns 映射的 CLR 类型）
 - XAML 属性 = 给对象赋值
 - 嵌套元素 = 父子关系（Content / Children / Properties）
 - XAML 不是必须的，纯 C# 也能写 WPF（只是啰嗦）

4.2 命名空间映射

1
2


<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

1
2
3
4
5
6
7
8


http://schemas.microsoft.com/winfx/2006/xaml/presentation
 → 不是真的 URL，是"程序集命名空间的别名"
 → 映射到多个 CLR 命名空间：
 System.Windows、System.Windows.Controls、System.Windows.Media 等
 → 设计如此：让 XAML 不用每次写 xmlns:wb="clr-namespace:System.Windows..."

xmlns:x
 → x: 前缀，专门给 XAML 语言本身用（x:Class、x:Name、x:Key、x:Static）

自定义命名空间：

1
2
3
4
5
6


<!-- 引用自定义 CLR 命名空间 -->
xmlns:local="clr-namespace:MyApp.ViewModels"
xmlns:sys="clr-namespace:System;assembly=mscorlib"

<local:MainViewModel x:Key="vm"/>
<sys:Int32 x:Key="answer">42</sys:Int32>

4.3 属性的两种写法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<!-- 1. 属性特性（Attribute）—— 简单类型 -->
<Button Content="OK" Width="100"/>

<!-- 2. 属性元素（Property Element）—— 复杂类型 -->
<Button Width="100">
 <Button.Content>
 <StackPanel Orientation="Horizontal">
 <Image Source="ok.png" Width="16"/>
 <TextBlock Text="OK"/>
 </StackPanel>
 </Button.Content>
</Button>

1
2
3
4


规则：
 - 字符串/数字 → 直接 Attribute（TypeConverter 自动转换）
 - 复杂对象 → Property Element（外层是类型，内层 Class.Property）
 - 两者的等价关系：Content="OK" ↔ <Button.Content>OK</Button.Content>

4.4 ContentControl 与子元素

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<!-- Button 是 ContentControl，子元素就是 Content -->
<Button>
 <TextBlock Text="OK"/> <!-- 等价于 <Button.Content><TextBlock/></Button.Content> -->
</Button>

<!-- ItemsControl 的子元素是 Items -->
<ListBox>
 <ListBoxItem>Item 1</ListBoxItem>
 <ListBoxItem>Item 2</ListBoxItem>
</ListBox>

1
2
3
4
5
6
7
8


ContentControl 语义：
 - 有且只有一个 Content（可以是任意对象）
 - WPF 自动用 DataTemplate 渲染 Content
 - Button / CheckBox / Label / Window 都是 ContentControl

后端类比：
 ContentControl ≈ 一个"槽位"，框架帮你渲染槽位里的对象
 而不是你手动 new TextBlock() 加进去

五、XAML 编译流水线

这是 WPF 学习中最容易被忽略、但理解后受益最大的部分——XAML 到底怎么变成可执行代码的。

5.1 流水线总览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


源代码 编译产物
─────────────────────────────────────────────────
MainWindow.xaml ┐
 │ ① XAML → BAML（编译）
MainWindow.baml ┘ （BAML = Binary Application Markup Language）

MainWindow.xaml.cs ┐
 │ ② code-behind 编译成 IL
MainWindow.g.cs ┘ （自动生成的 partial 类）

合并到 MainWindow 类型（partial）：
 - 你写的 InitializeComponent override（如果有）
 - 生成的 InitializeComponent（从 g.cs）
 - 生成的 Connect（IComponentConnector）
 - 你写的事件处理、业务逻辑

最终在 .exe / .dll 里：
 - MainWindow.baml 作为资源嵌入（Embedded Resource）
 - MainWindow 类型的 IL

5.2 第一步：XAML → BAML

1
2
3
4
5
6
7
8


BAML 不是二进制 XAML，是"压缩的对象图"
 - 把 XAML 的元素/属性/值编译成一串 token
 - 比 XAML 体积小、加载快
 - 不是 IL，运行时还要解析

BAML 在哪里？
 - 编译后嵌入 assembly（Embedded Resource）
 - 运行时 Application.LoadComponent 读出来

5.3 第二步：生成 g.cs

MainWindow.g.cs 是 XAML 编译器自动生成的 partial 类，它做的事情：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


// MainWindow.g.cs（简化，反编译样貌）
public partial class MainWindow : Window, IComponentConnector
{
 // 1. XAML 里所有 x:Name 的元素都成了字段
 internal System.Windows.Controls.Button okButton;
 internal System.Windows.Controls.TextBox userNameBox;

 // 2. 自动生成 InitializeComponent
 public void InitializeComponent()
 {
 if (_contentLoaded) return;
 _contentLoaded = true;
 // 关键：加载 BAML 资源
 System.Uri resourceLocator = new System.Uri(
 "/MyApp;component/mainwindow.baml",
 System.UriKind.Relative);
 System.Windows.Application.LoadComponent(this, resourceLocator);
 }

 // 3. IComponentConnector.Connect：把 XAML 里的元素和事件接到这个对象上
 public void Connect(int connectionId, object target)
 {
 switch (connectionId)
 {
 case 1:
 this.okButton = (System.Windows.Controls.Button)target;
 break;
 case 2:
 this.userNameBox = (System.Windows.Controls.TextBox)target;
 #line 12 "..\\..\\MainWindow.xaml"
 ((System.Windows.Controls.Button)target).Click += this.OkButton_Click;
 #line default
 break;
 }
 }

 private bool _contentLoaded = false;
}

5.4 InitializeComponent 的真相

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 你的 MainWindow.xaml.cs
public partial class MainWindow : Window
{
 public MainWindow()
 {
 InitializeComponent(); // ← 这个方法在 g.cs 里
 // 之后才能用 okButton 字段
 }

 private void OkButton_Click(object sender, RoutedEventArgs e) { ... }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


执行顺序：
 1. new MainWindow()
 2. 构造函数调用 InitializeComponent()
 3. InitializeComponent 调 Application.LoadComponent(this, bamlUri)
 4. LoadComponent 解析 BAML，逐个 new 出 XAML 里的元素
 5. 每创建一个元素，调 Connect(connectionId, target) 接到字段
 6. BAML 解析完成，构造函数继续执行
 7. 之后访问 this.okButton 就是有效的

常见错误：
 - 在 InitializeComponent() 之前访问 okButton → NullReferenceException
 - 忘了写 InitializeComponent() → 窗口空白

5.5 x:Name 与 Name 的区别

1
2
3
4
5
6
7
8


<Button x:Name="okButton" Content="OK"/>
<Button Name="okButton" Content="OK"/> <!-- 等价，FrameworkElement 才有 Name -->

效果：
 - 都会在 g.cs 里生成 internal Button okButton; 字段
 - x:Name 通用（任何元素都行，包括非 FrameworkElement）
 - Name 只 FrameworkElement 有
 - 推荐 x:Name（一致 + 万能）

5.6 为什么 WPF 用 BAML + 反射，而不是直接编译成 IL

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


理论上有"更激进"的方案：
 - 把 XAML 直接编译成 new Button() { Content = "OK" } 这种 IL
 - 加载时零反射，性能更好

WPF 没这么做的原因：
 1. 资源需要在运行时可替换（主题、本地化）
 - BAML 是资源，可以打包成卫星程序集
 - 直接 IL 化就不能运行时替换
 2. 设计器需要解析 XAML/BAML
 - Visual Studio / Blend 要在没编译的情况下显示 UI
 3. 历史包袱（2006 年的决策）

代价：
 - 启动时反射开销（ILemit 优化只解决了一部分）
 - 部分场景下 NativeAOT 受限（详见第 12 篇）

六、MarkupExtension 与 TypeConverter

XAML 里那些 {...} 花括号到底在干什么？

6.1 MarkupExtension：花括号的本质

1
2
3
4
5


<!-- 这些都是 MarkupExtension -->
<Button Content="{Binding UserName}"/>
<Button Background="{StaticResource AccentBrush}"/>
<TextBlock Text="{x:Static sys:Environment.MachineName}"/>
<Grid DataContext="{DynamicResource ViewModel}"/>

1
2
3
4
5
6
7
8


{...} 的本质：
 - XAML 编译器看到 { 就知道要 new 一个 MarkupExtension
 - 然后调用它的 ProvideValue(IServiceProvider) 方法
 - 用返回值作为属性的最终值

后端类比：
 MarkupExtension ≈ "值工厂"
 你声明 "{...}"，框架运行时调用工厂拿值

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// Binding 的简化实现
public class Binding : MarkupExtension
{
 public string Path { get; set; }
 public object Source { get; set; }

 public override object ProvideValue(IServiceProvider serviceProvider)
 {
 // 解析 Binding 表达式，建立监听
 // 返回 BindingExpression
 return new BindingExpression(this);
 }
}

6.2 自定义 MarkupExtension

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 一个简单的"多语言翻译"扩展
public class TranslateExtension : MarkupExtension
{
 public string Key { get; set; }

 public TranslateExtension(string key) => Key = key;

 public override object ProvideValue(IServiceProvider serviceProvider)
 {
 // 从资源文件查翻译
 return Resources.ResourceManager.GetString(Key) ?? Key;
 }
}

1
2


<TextBlock Text="{Translate HelloWorld}"/>
<!-- 等价于 TextBlock.Text = Resources.HelloWorld -->

6.3 TypeConverter：字符串到对象的转换

1
2
3
4


<Button Background="Red"/> <!-- "Red" → SolidColorBrush -->
<Button Background="#FF0000"/> <!-- "#FF0000" → SolidColorBrush -->
<Button Width="100"/> <!-- "100" → int -->
<Button Margin="10,5,10,5"/> <!-- "10,5,10,5" → Thickness -->

1
2
3
4
5
6
7
8


TypeConverter 的角色：
 - XAML 属性是字符串，但 C# 属性是强类型
 - "Red" 怎么变成 SolidColorBrush？靠 BrushConverter
 - "100" 怎么变成 double？靠 LengthConverter

机制：
 - 每个类型用 [TypeConverter] 特性声明自己的转换器
 - XAML 解析时查表，找到对应 TypeConverter 调用 ConvertFrom

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 自己实现 TypeConverter（简化）
[TypeConverter(typeof(PointConverter))]
public struct Point { ... }

public class PointConverter : TypeConverter
{
 public override object ConvertFrom(ITypeDescriptorContext ctx, CultureInfo c, object value)
 {
 var s = value as string;
 var parts = s.Split(',');
 return new Point(double.Parse(parts[0]), double.Parse(parts[1]));
 }
}

七、实战：纯 C# vs XAML 对照

同一个登录窗口，两种写法对照，巩固 XAML 心智模型。

7.1 XAML 版

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


<!-- LoginWindow.xaml -->
<Window x:Class="MyApp.LoginWindow"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 Title="Login" Width="320" Height="200"
 WindowStartupLocation="CenterScreen">
 <Grid Margin="16">
 <Grid.RowDefinitions>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="Auto"/>
 <RowDefinition Height="*"/>
 <RowDefinition Height="Auto"/>
 </Grid.RowDefinitions>

 <TextBlock Grid.Row="0" Text="用户名" Margin="0,0,0,4"/>
 <TextBox Grid.Row="1" x:Name="userNameBox" Height="28"/>

 <TextBlock Grid.Row="2" Text="密码" Margin="0,12,0,4"/>
 <PasswordBox Grid.Row="3" x:Name="passwordBox" Height="28"/>

 <StackPanel Grid.Row="4" Orientation="Horizontal"
 HorizontalAlignment="Right" Margin="0,16,0,0">
 <Button Content="取消" Width="80" Margin="0,0,8,0" IsCancel="True"/>
 <Button Content="登录" Width="80" x:Name="loginButton" IsDefault="True"
 Click="LoginButton_Click"/>
 </StackPanel>
 </Grid>
</Window>

7.2 纯 C# 版（等价）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


public class LoginWindowPure : Window
{
 private TextBox userNameBox;
 private PasswordBox passwordBox;

 public LoginWindowPure()
 {
 Title = "Login";
 Width = 320; Height = 200;
 WindowStartupLocation = WindowStartupLocation.CenterScreen;

 var grid = new Grid { Margin = new Thickness(16) };
 grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Auto });
 grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Auto });
 grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Auto });
 grid.RowDefinitions.Add(new RowDefinition { Height = new GridLength(1, GridUnitType.Star) });
 grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Auto });

 var userLabel = new TextBlock { Text = "用户名", Margin = new Thickness(0, 0, 0, 4) };
 Grid.SetRow(userLabel, 0);
 grid.Children.Add(userLabel);

 userNameBox = new TextBox { Height = 28 };
 Grid.SetRow(userNameBox, 1);
 grid.Children.Add(userNameBox);

 var pwdLabel = new TextBlock { Text = "密码", Margin = new Thickness(0, 12, 0, 4) };
 Grid.SetRow(pwdLabel, 2);
 grid.Children.Add(pwdLabel);

 passwordBox = new PasswordBox { Height = 28 };
 Grid.SetRow(passwordBox, 3);
 grid.Children.Add(passwordBox);

 var buttonPanel = new StackPanel
 {
 Orientation = Orientation.Horizontal,
 HorizontalAlignment = HorizontalAlignment.Right,
 Margin = new Thickness(0, 16, 0, 0)
 };
 Grid.SetRow(buttonPanel, 4);

 var cancelButton = new Button { Content = "取消", Width = 80, Margin = new Thickness(0, 0, 8, 0), IsCancel = true };
 var loginButton = new Button { Content = "登录", Width = 80, IsDefault = true };
 loginButton.Click += LoginButton_Click;
 buttonPanel.Children.Add(cancelButton);
 buttonPanel.Children.Add(loginButton);
 grid.Children.Add(buttonPanel);

 Content = grid;
 }

 private void LoginButton_Click(object sender, RoutedEventArgs e)
 {
 MessageBox.Show($"Login: {userNameBox.Text}");
 }
}

7.3 对比观察

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


XAML 版（22 行）：
 ✅ 简洁、声明式
 ✅ 结构一目了然
 ✅ 设计器友好（VS/Blend 可视化）
 ✅ 编译时检查（缺 RowDefinition 会警告）
 ❌ 不能写循环/条件（要靠 ItemsControl）

C# 版（55 行）：
 ✅ 可写循环/条件
 ✅ 重构友好（重命名、提取方法）
 ❌ 啰嗦（每个属性单独 set）
 ❌ 视觉上看不出布局
 ❌ 设计器不支持

实践建议：
 - 99% 的 UI 用 XAML 写
 - 动态/复杂组合才用 C# 补充
 - ItemsControl + DataTemplate 是处理"循环"的标准武器（详见第 8 篇）

八、WPF 项目结构

8.1 一个标准 WPF 项目的目录

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


MyApp/
├── MyApp.csproj
├── App.xaml ← 应用入口、全局资源
├── App.xaml.cs
├── MainWindow.xaml ← 主窗口
├── MainWindow.xaml.cs
├── Views/ ← 子视图（Window / UserControl）
│ └── LoginView.xaml
├── ViewModels/ ← MVVM 的 ViewModel
│ └── MainViewModel.cs
├── Models/ ← 业务模型
│ └── User.cs
├── Services/ ← 业务服务（数据访问、API）
│ └── IUserService.cs
├── Styles/ ← 样式资源
│ └── Buttons.xaml
├── Themes/ ← 主题（自定义控件）
│ └── Generic.xaml
├── Assets/ ← 图标、图片
│ └── logo.png
└── Converters/ ← IValueConverter
 └── BoolToVisibilityConverter.cs

8.2 .csproj（.NET 8）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<Project Sdk="Microsoft.NET.Sdk">

 <PropertyGroup>
 <OutputType>WinExe</OutputType>
 <TargetFramework>net8.0-windows</TargetFramework>
 <Nullable>enable</Nullable>
 <UseWPF>true</UseWPF>
 <ImplicitUsings>enable</ImplicitUsings>
 <ApplicationManifest>app.manifest</ApplicationManifest>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.2"/>
 <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0"/>
 </ItemGroup>

</Project>

1
2
3
4
5


关键点：
 - OutputType=WinExe（不是 Exe，否则会弹出黑色控制台窗口）
 - TargetFramework=net8.0-windows（WPF 必须带 -windows）
 - UseWPF=true（启用 WPF SDK）
 - 8.0 不能跨平台（WPF 只跑 Windows）

8.3 App.xaml 与启动流程

1
2
3
4
5
6
7
8
9


<!-- App.xaml -->
<Application x:Class="MyApp.App"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 StartupUri="MainWindow.xaml">
 <Application.Resources>
 <!-- 全局资源 -->
 </Application.Resources>
</Application>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// App.xaml.cs
public partial class App : Application
{
 // 默认不需要写 Main，编译器自动生成
 // Main 内部调用 new App().Run()

 // 如果要自定义启动（如 DI、登录流程）：
 protected override void OnStartup(StartupEventArgs e)
 {
 base.OnStartup(e);
 // 初始化 DI、显示登录窗口等
 }
}

1
2
3
4
5
6
7


启动流程：
 1. 编译器自动生成 Main() → new App()
 2. App 构造函数 → InitializeComponent()（加载 App.xaml 的 BAML）
 3. App.Run() → 触发 Startup 事件
 4. StartupUri="MainWindow.xaml" → 自动 new MainWindow() + Show()
 5. Application.Run() 进入消息循环
 6. 主窗口关闭 → Shutdown → 进程退出

九、后端视角总结卡

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


ASP.NET Core 后端工程师看 WPF 的"翻译字典"

ASP.NET Core WPF
──────────────────────────────────────────────────
Razor 视图 XAML
ViewModel (Razor) DataContext
Tag Helpers MarkupExtension
_Layout.cshtml Window/App.Resources
appsettings.json App.config / Resources
Middleware 管道 Routed Event 路由
DI Container ServiceProvider（同样）
HttpContext Dispatcher（线程上下文）
async/await async/await（UI 线程行为不同）
SignalR Hub WCF 已死，用 gRPC 或 SignalR 客户端
EF Core EF Core（同样，桌面也可以用）
日志 Serilog Serilog（同样）

十、小结

本文建立了 WPF 的心智模型：

WPF 与 WinForms 的根本区别：保留模式 vs 立即模式
架构分层：Framework / Core / WindowsBase / milcore / DirectX
视觉树与逻辑树的两元结构
XAML 的本质：对象初始化的语法糖
XAML → BAML → g.cs 的编译流水线
InitializeComponent 的真相（LoadComponent + Connect）
MarkupExtension 与 TypeConverter 的角色
项目结构与启动流程

1
2
3
4


记住三句话：
 1. WPF 是声明式 UI——你描述"树"，框架渲染
 2. XAML 不是语言，是"对象初始化的 XML 序列化"
 3. InitializeComponent 是 XAML 和 C# 的缝合点——没它你的字段都是 null

下一篇将进入 WPF 的"地基"——依赖属性系统。这是 WPF 区别于其他 UI 框架的核心机制，理解它之后再看数据绑定、样式、动画都会豁然开朗。