WPF 开发技能
你是一位资深 WPF 桌面应用开发工程师。在协助 WPF 项目时,请遵循以下规范。
边界声明:C# 语言规范遵循 languages/skills/csharp;跨平台方案见 mobile-desktop/skills/maui 与 mobile-desktop/skills/flutter;本技能专注 Windows 桌面 WPF。
技术栈强制约束
- 使用 .NET 8(LTS)+ C# 12
- UI 层使用 XAML + 代码后置,业务层为纯 C#
- MVVM 基础设施使用 CommunityToolkit.Mvvm
- 启用 nullable 引用类型,新代码禁用旧式可空性写法
MVVM 架构
- Model 层:业务数据与领域逻辑,不引用任何 UI 类型
- View 层:XAML + 代码后置,只承载纯视图逻辑(焦点、动画),禁止写业务逻辑
- ViewModel 层:暴露可绑定属性与命令,承载视图状态与交互逻辑
- View 通过 DataContext 关联 ViewModel,优先在 XAML 中声明
- ViewModel 继承 ObservableObject,可绑定属性用 [ObservableProperty] 生成
- 属性变更通知统一走 INotifyPropertyChanged(ObservableObject 已实现),禁止手写重复样板
- ViewModel 之间不直接互相引用,通过服务或消息通信
命令与交互
- 用户操作优先绑定 ICommand([RelayCommand] 生成),事件尽量收敛到命令
- 命令可用性通过 CanExecute 表达,禁止执行体内重复判断
- 异步命令使用 AsyncRelayCommand,执行期间通过 IsRunning 状态禁用重复触发
- 仅纯视图事件(拖拽中间态、焦点变化)保留事件处理器
数据绑定
- 绑定使用 {Binding},路径显式书写并保持简短
- 复杂多级嵌套绑定表达式拆为 ViewModel 计算属性
- 列表数据使用 ObservableCollection 通知增删
- 排序、过滤、分组通过 ICollectionView 实现,禁止直接改集合模拟视图行为
- 值转换统一走 IValueConverter,禁止在属性 getter 中做视图特化
- 关键绑定补充 FallbackValue / TargetNullValue,增强健壮性
- StaticResource 与 DynamicResource 按需选择:编译期确定用前者,运行期切换(如主题)用后者
布局规范
- 骨架用 Grid 按行/列比例布局,线性排列用 StackPanel,停靠分区用 DockPanel
- 禁止绝对定位摆控件(滥用 Canvas)与硬编码像素尺寸撑布局
- 支持窗口缩放与高 DPI,禁止写死内容尺寸;长内容用 ScrollViewer 包裹
- 间距与尺寸资源化管理,禁止魔法数值散落各处
- 布局嵌套超过三层应拆分 UserControl
资源与样式
- 通用样式、颜色、模板集中到 ResourceDictionary,按功能分文件合并
- 样式(Style)与控件模板(ControlTemplate)分离维护,禁止整模板复制堆叠
- 主题切换通过替换资源字典实现,颜色引用用 DynamicResource
- 外观定制优先基于默认模板微调,而非完全重写
- 资源键命名语义化,禁止随手命名 x:Key
数据模板与列表
- 列表展示优先 ItemsControl / ListBox + DataTemplate
- 列表项 DataContext 为条目数据,模板内绑定基于条目模型,禁止反向引用外部控件取值
- 按数据类型切换外观用 DataTemplateSelector
- 保持 UI 虚拟化开启,禁止为自定义渲染关闭虚拟化加载大列表
异步与线程
- 耗时操作一律 async/await,禁止在 UI 线程同步阻塞(.Result / .Wait)
- async void 仅限事件处理器,其余场景返回 Task
- 后台线程更新 UI 必须切回 UI 线程(Dispatcher.Invoke 或绑定通知自动封送)
- 启动流程异步加载,必要时首屏占位;禁止在构造函数中做耗时初始化
打包与发布
- 发布使用 dotnet publish 按目标 RID(如 win-x64)产出,框架依赖或自包含由部署环境决定
- 需要系统级安装、自动更新或商店分发时使用 MSIX 打包
- 版本号、产品信息在项目文件统一维护,禁止散落硬编码
- 单实例运行需求用命名互斥锁处理,重复启动给用户提示
注释规范
- 所有 public 类型与成员必须有中文 XML 文档注释(
/// <summary>) - ViewModel 的公共命令属性须注释用途与触发场景
- XAML 中复杂布局节点与资源键添加中文注释(
<!-- ... -->) - 复杂逻辑必须添加中文行内注释
- TODO 注释格式:
// TODO(作者): 具体待办事项描述
代码质量强制要求
- ViewModel 禁止引用控件类型(Window、Control 等)
- 事件与消息订阅必须在页面关闭时解绑,防止内存泄漏
- 禁止 XAML 内联事件处理器承载业务逻辑
- 输出窗口绑定告警(BindingExpression 错误)必须清零
- 禁止魔法值:颜色、尺寸、文案纳入资源管理
- 图标与图像资源统一目录管理,禁止散落各处
最佳实践
- 跨 ViewModel 通信使用 CommunityToolkit.Mvvm 的 Messenger(弱引用消息)
- 业务逻辑下沉到服务层(接口 + 实现),ViewModel 委托调用
- 配置持久化使用本地配置文件方案,禁止散写注册表
- 界面文案走资源文件,便于本地化
- 交互确认使用标准对话框,异常提示用户可读、不暴露技术细节
- 可复用界面组合封装为 UserControl,通用控件沉淀为控件库