如何创建用户自定义控件Custom Control

一、先搞懂：UserControl vs CustomControl

1. UserControl（组合控件）

• 把一堆现成控件（Button、TextBox）包在一起
• XAML + 后台代码，强耦合
• 适合：快速做一个可复用模块（登录框、搜索条、卡片）
• 不能改模板

2. CustomControl（自定义控件）

• 继承自 Control 或更基础类
• 没有自己的 XAML，只有 Theme/Generic.xaml 里的默认样式
• UI 与逻辑完全分离
• 支持控件模板 重写、替换、复用
• 适合：做框架级控件、库控件、通用 UI 库（如 Button、TextBox 这种）

二、CustomControl 完整创建步骤（.NET 6 /.NET Framework 通用）

步骤 1：添加 → 自定义控件 (WPF)

右键项目 → 添加 → 新建项 → 自定义控件 (WPF)

 

命名：MyCustomControl.cs

 

自动生成两个东西：

1. MyCustomControl.cs（逻辑代码）
2. Themes/Generic.xaml（默认控件模板）

三、完整示例：创建一个带图标的按钮控件

1. 控件类 MyCustomControl.cs

using System.Windows;
using System.Windows.Controls;
using System.Windows.Media;

namespace WpfCustomControlDemo
{
    public class MyCustomControl : Control
    {
        // 静态构造：必须调用 DefaultStyleKey
        static MyCustomControl()
        {
            DefaultStyleKeyProperty.OverrideMetadata(
                typeof(MyCustomControl),
                new FrameworkPropertyMetadata(typeof(MyCustomControl))
            );
        }

        // ======================= 依赖属性 ===========================

        // 图标
        public ImageSource Icon
        {
            get => (ImageSource)GetValue(IconProperty);
            set => SetValue(IconProperty, value);
        }

        public static readonly DependencyProperty IconProperty =
            DependencyProperty.Register(
                nameof(Icon),
                typeof(ImageSource),
                typeof(MyCustomControl),
                new PropertyMetadata(null));

        // 文本
        public string Text
        {
            get => (string)GetValue(TextProperty);
            set => SetValue(TextProperty, value);
        }

        public static readonly DependencyProperty TextProperty =
            DependencyProperty.Register(
                nameof(Text),
                typeof(string),
                typeof(MyCustomControl),
                new PropertyMetadata(""));

        // 点击命令（可选，MVVM 用）
        public ICommand ClickCommand
        {
            get => (ICommand)GetValue(ClickCommandProperty);
            set => SetValue(ClickCommandProperty, value);
        }

        public static readonly DependencyProperty ClickCommandProperty =
            DependencyProperty.Register(
                nameof(ClickCommand),
                typeof(ICommand),
                typeof(MyCustomControl),
                new PropertyMetadata(null));
    }
}

2. 控件默认模板 Themes/Generic.xaml

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="clr-namespace:WpfCustomControlDemo">

    <Style TargetType="local:MyCustomControl">
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="local:MyCustomControl">
                    <!-- 控件外观 -->
                    <Border Background="LightBlue"
                            CornerRadius="8"
                            Margin="10">
                        <StackPanel Orientation="Horizontal"
                                    Margin="10">
                            <Image Source="{TemplateBinding Icon}"
                                   Width="24" Height="24"/>

                            <TextBlock Text="{TemplateBinding Text}"
                                       FontSize="16"
                                       Margin="10 0"/>
                        </StackPanel>
                    </Border>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>

</ResourceDictionary>

四、在窗口中使用自定义控件

MainWindow.xaml

<Window x:Class="WpfCustomControlDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="clr-namespace:WpfCustomControlDemo"
        Title="MainWindow" Height="450" Width="800">

    <Grid>
        <StackPanel>
            <!-- 使用自定义控件 -->
            <local:MyCustomControl
                Text="我的自定义控件"
                Icon="pack://application:,,,/icon.png"/>

            <!-- 可以放N个 -->
            <local:MyCustomControl
                Text="第二个控件"
                Icon="pack://application:,,,/icon2.png"/>
        </StackPanel>
    </Grid>
</Window>

五、CustomControl 核心机制（必须懂）

1. 关键：DefaultStyleKey

DefaultStyleKeyProperty.OverrideMetadata(
    typeof(MyCustomControl),
    new FrameworkPropertyMetadata(typeof(MyCustomControl))
);

作用：告诉 WPF

“去 Themes/Generic.xaml 里找我的样式”

 

2. TemplateBinding

模板绑定，用于控件模板内部绑定到控件的属性：

{TemplateBinding Icon}
{TemplateBinding Text}

3. Generic.xaml

WPF 规定：所有自定义控件的默认样式必须放在这里

• 生成属性：生成操作 = ResourceDictionary
• 不能改名，不能改路径

六、高级：给自定义控件加点击事件

 

在 MyCustomControl.cs 里重写 OnApplyTemplate：

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

    // 找到模板中的 Border 并注册点击
    if (GetTemplateChild("PART_Border") is Border border)
    {
        border.MouseLeftButtonDown += (s, e) =>
        {
            ClickCommand?.Execute(null);
        };
    }
}

模板里命名：

<Border x:Name="PART_Border" ...>

这就是 WPF 控件标准的 PART_ 命名约定。

七、什么时候用 CustomControl

• 你要做一个通用控件库
• 控件需要支持换肤、改模板
• 像系统控件 Button/TextBox 那样高度可定制
• 多人协作、UI 与逻辑分离

八、一句话总结

• UserControl = 打包现有控件，快速复用
• CustomControl = 从头造一个全新控件，高度可定制