WPF自定义控件分UserControl与模板化控件两类：UserControl适合封装固定UI，需x:Name命名、公开属性、避免构造函数中访问布局属性；模板化控件继承Control、配Generic.xaml、用TemplateBinding、必须声明依赖属性和路由事件。

WPF自定义用户控件：用 UserControl 快速封装可复用界面

适合把一组固定 UI（比如带标签的文本框、搜索栏）打包成一个逻辑单元，不涉及模板替换或样式深度定制。本质是 XAML + 后台代码的组合封装，编译后仍是普通元素。

• 新建项目时选 UserControl 模板，它会自动生成 .xaml 和 .xaml.cs 两个文件
• 在 UserControl 的 XAML 中写布局，用 x:Name 给子元素命名，后台代码里直接当字段访问（如 txtInput）
• 公开属性要加 public + get/set，绑定时才生效；别忘了在构造函数里调用 InitializeComponent()
• 别在 UserControl 构造函数里访问 this.ActualWidth 这类依赖布局的属性——此时还没测量，值是 0.0

WPF模板化控件：继承 Control 并定义 DefaultStyleKey

当你需要让用户彻底换皮肤（比如按钮变圆角、变图标、变动画），或者控件行为和外观解耦（像 ComboBox 那样），就得走模板化路线。核心是分离逻辑与表现。

C#

"避开 C# 常见错误——空陷阱、异步陷阱、LINQ 陷阱及资源泄漏。"

下载

• 新建类继承 Control，在静态构造函数里设置 DefaultStyleKeyProperty： DefaultStyleKeyProperty.OverrideMetadata(typeof(MyButton), new FrameworkPropertyMetadata(typeof(MyButton)));
• 控件模板必须放在 Themes/Generic.xaml（路径和文件名不能错），且 ResourceDictionary 的 xmlns 要包含控件所在命名空间
• Generic.xaml 里的模板用 TargetType="{x:Type local:MyButton}" 关联，不是 x:Key
• 控件内部要用 TemplateBinding 绑定模板属性（如 Background），而不是 Binding；否则模板外设的值传不进来

依赖属性和路由事件：让自定义控件真正“可绑定”“可响应”

没声明依赖属性，外部就无法绑定数据或样式触发器；没暴露路由事件，父容器就监听不到点击、值变化等动作。这两项是模板化控件的硬门槛。

• 依赖属性必须用 DependencyProperty.Register 注册，名称必须是 XXXProperty（如 TextProperty），对应 CLR 属性只做包装器
• 不要在依赖属性的 PropertyChangedCallback 里直接操作 UI 元素（比如改 TextBox.Text）——此时模板可能还没应用，GetTemplateChild 返回 null
• 路由事件用 EventManager.RegisterRoutedEvent 声明，触发用 RaiseEvent(new RoutedEventArgs(MyClickEvent))，别用普通事件 += 那套
• 如果控件需要响应鼠标/键盘，优先重写 OnMouseLeftButtonDown 等虚方法，而不是监听 PreviewMouseDown —— 更可靠，也避免被外层拦截

调试常见错误：找不到模板、属性不更新、事件不触发

这些问题基本都卡在资源加载时机或属性注册细节上，不是逻辑问题，而是 WPF 的隐式约定没满足。

• 模板不生效？检查 Generic.xaml 是否在 Themes 文件夹下、是否设为 Page 生成操作、是否在 AssemblyInfo.cs 里加了 [assembly: ThemeInfo(...)]
• 绑定的属性没反应？确认依赖属性注册时用了正确的 PropertyMetadata，且回调函数签名是 static void OnTextChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
• 自定义事件监听不到？确认事件声明时用了 RoutedEvent 类型，且 RoutedEventArgs 构造时传了正确的 RoutedEvent 实例
• 在设计器里显示空白？多半是 Generic.xaml 路径错或 TargetType 命名空间没对齐，Visual Studio 不报错但静默失败

WPF 自定义控件最难的不是写代码，而是理解“模板何时加载”“依赖属性何时可用”“资源字典怎么被发现”这些隐式生命周期节点。很多问题表面是功能没实现，实际是某个环节提前或延后了一步。