【WPF】路由事件详细使用

WPF路由事件详细使用指南

一、路由事件概述

1.1 什么是路由事件

路由事件（RoutedEvent）是WPF中专门设计用于在元素树中传递的事件。与传统的.NET事件不同，路由事件可以在UI元素树中向上或向下传播，允许在事件传播路径上的多个元素处理同一个事件。

路由事件是一个通用的事件传播框架，它的核心价值在于：

统一的传播机制（冒泡/隧道/直接）
父容器可以统一处理子元素事件
可以在传播路径上拦截和修改事件

1.2 路由事件的特点

跨元素传播：事件可以在父子元素之间传播
三种传播策略：冒泡、隧道、直接
支持事件处理程序的灵活绑定
可以被多个元素处理

1.3 路由事件的完整分类

表格

事件大类	包含内容	是否路由事件
鼠标事件	`Click`, `MouseDown`, `MouseUp`, `MouseMove`, `MouseEnter`, `MouseWheel`...	✅ 是
键盘事件	`KeyDown`, `KeyUp`, `PreviewKeyDown`, `PreviewKeyUp`	✅ 是
焦点事件	`GotFocus`, `LostFocus`, `PreviewGotFocus`...	✅ 是
文本事件	`TextChanged`	✅ 是
拖放事件	`DragEnter`, `DragOver`, `Drop`, `DragLeave`...	✅ 是
触控事件	`TouchDown`, `TouchUp`, `TouchMove`...	✅ 是
手势事件	`ManipulationStarted`, `ManipulationDelta`...	✅ 是
数据事件	`Selected`, `SelectionChanged`, `Expanded`, `Collapsed`...	✅ 是
滚动事件	`Scroll`, `PreviewScroll`	✅ 是
工具提示事件	`ToolTipOpening`, `ToolTipClosing`	✅ 是
上下文菜单事件	`ContextMenuOpening`, `ContextMenuClosing`	✅ 是
加载事件	`Loaded`, `Unloaded`	✅ 是

二、路由事件的三种传播策略

表格

传播策略	传播方向	典型事件	用途
冒泡（Bubble）	从子元素 → 父元素	`Click`, `MouseDown`, `TextChanged`	父容器统一处理子元素事件
隧道（Tunnel）	从父元素 → 子元素	`PreviewKeyDown`, `PreviewMouseDown`	父容器提前拦截/预处理事件
直接（Direct）	仅在源元素触发	`Loaded`, `Unloaded`	只在特定元素上处理

2.1 冒泡路由事件（Bubble）

事件从源元素向上冒泡到根元素。

cs 复制代码

// 注册冒泡路由事件
public static readonly RoutedEvent TapEvent = 
    EventManager.RegisterRoutedEvent(
        "Tap", 
        RoutingStrategy.Bubble,  // 冒泡策略
        typeof(RoutedEventHandler), 
        typeof(OwnerType));

传播路径示例：

Button → StackPanel → Grid → Window

2.2 隧道路由事件（Tunnel）

事件从根元素向下隧道到源元素。

cs 复制代码

// 隧道路由事件通常以"Preview"开头
public static readonly RoutedEvent PreviewTapEvent = 
    EventManager.RegisterRoutedEvent(
        "PreviewTap", 
        RoutingStrategy.Tunnel,  // 隧道策略
        typeof(RoutedEventHandler), 
        typeof(OwnerType));

传播路径示例：

Window → Grid → StackPanel → Button

2.3 直接路由事件（Direct）

事件只在源元素上处理，不进行传播。

cs 复制代码

public static readonly RoutedEvent DirectEvent = 
    EventManager.RegisterRoutedEvent(
        "Direct", 
        RoutingStrategy.Direct,  // 直接策略
        typeof(RoutedEventHandler), 
        typeof(OwnerType));

三、自定义路由事件的完整步骤

3.1 注册路由事件

cs 复制代码

public class CustomButton : Button
{
    // 1. 注册路由事件
    public static readonly RoutedEvent ReportTimeEvent = 
        EventManager.RegisterRoutedEvent(
            "ReportTime",                    // 事件名称
            RoutingStrategy.Bubble,          // 路由策略
            typeof(EventHandler<ReportTimeEventArgs>),  // 事件处理程序类型
            typeof(CustomButton));           // 所有者类型
}

3.2 添加CLR事件包装器

cs 复制代码

public class CustomButton : Button
{
    // 2. CLR事件包装器
    public event EventHandler<ReportTimeEventArgs> ReportTime
    {
        add { AddHandler(ReportTimeEvent, value); }
        remove { RemoveHandler(ReportTimeEvent, value); }
    }
}

3.3 创建触发事件的方法

cs 复制代码

public class CustomButton : Button
{
    // 3. 触发路由事件的方法
    protected virtual void OnReportTime(ReportTimeEventArgs e)
    {
        RaiseEvent(e);
    }
    
    // 实际使用示例
    private void OnTimerTick(object sender, EventArgs e)
    {
        ReportTimeEventArgs args = new ReportTimeEventArgs(
            ReportTimeEvent, this, DateTime.Now);
        OnReportTime(args);
    }
}

3.4 完整的自定义路由事件示例

cs 复制代码

// 自定义事件参数
public class ReportTimeEventArgs : RoutedEventArgs
{
    public DateTime Time { get; set; }
    
    public ReportTimeEventArgs(RoutedEvent routedEvent, object source, DateTime time)
        : base(routedEvent, source)
    {
        Time = time;
    }
}

// 自定义控件
public class TimeButton : Button
{
    // 1. 注册路由事件
    public static readonly RoutedEvent ReportTimeEvent = 
        EventManager.RegisterRoutedEvent(
            "ReportTime", 
            RoutingStrategy.Bubble, 
            typeof(EventHandler<ReportTimeEventArgs>), 
            typeof(TimeButton));
    
    // 2. CLR事件包装器
    public event EventHandler<ReportTimeEventArgs> ReportTime
    {
        add { AddHandler(ReportTimeEvent, value); }
        remove { RemoveHandler(ReportTimeEvent, value); }
    }
    
    // 3. 触发事件
    protected virtual void OnReportTime(ReportTimeEventArgs e)
    {
        RaiseEvent(e);
    }
    
    // 实际触发
    private void Timer_Tick(object sender, EventArgs e)
    {
        ReportTimeEventArgs args = new ReportTimeEventArgs(
            ReportTimeEvent, this, DateTime.Now);
        OnReportTime(args);
    }
}

四、XAML中使用路由事件

4.1 在XAML中绑定事件处理程序

cs 复制代码

<Window x:Class="WpfApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="MainWindow" Height="450" Width="800">
    
    <Grid Name="mainGrid" Button.Click="Grid_Click">
        <StackPanel Name="stackPanel" Button.Click="StackPanel_Click">
            <Button Content="Click Me" Click="Button_Click"/>
        </StackPanel>
    </Grid>
</Window>

4.2 事件处理程序代码

cs 复制代码

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }
    
    private void Button_Click(object sender, RoutedEventArgs e)
    {
        MessageBox.Show("Button Clicked!");
        // e.Handled = true; // 阻止事件继续传播
    }
    
    private void StackPanel_Click(object sender, RoutedEventArgs e)
    {
        MessageBox.Show("StackPanel Clicked!");
    }
    
    private void Grid_Click(object sender, RoutedEventArgs e)
    {
        MessageBox.Show("Grid Clicked!");
    }
}

五、事件传播控制

5.1 阻止事件继续传播

cs 复制代码

private void Button_Click(object sender, RoutedEventArgs e)
{
    MessageBox.Show("Button Clicked!");
    e.Handled = true;  // 阻止事件继续向上冒泡
}

5.2 使用AddHandler添加处理程序（即使e.Handled=true）

cs 复制代码

// 即使事件被标记为Handled，这个处理程序也会执行
button.AddHandler(Button.ClickEvent, 
    new RoutedEventHandler(Button_Click), 
    true);  // handledEventsToo = true

六、Source和OriginalSource的区别

cs 复制代码

private void Grid_Click(object sender, RoutedEventArgs e)
{
    // Source: 事件处理程序附加到的元素
    UIElement source = e.Source as UIElement;
    
    // OriginalSource: 最初触发事件的元素
    UIElement originalSource = e.OriginalSource as UIElement;
    
    // 在冒泡过程中，Source和OriginalSource可能不同
}

七、实际应用场景

7.1 统一处理多个子元素的事件

cs 复制代码

<ListBox Name="listBox" SelectionChanged="ListBox_SelectionChanged">
    <ListBoxItem Content="Item 1"/>
    <ListBoxItem Content="Item 2"/>
    <ListBoxItem Content="Item 3"/>
</ListBox>

cs 复制代码

private void ListBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    // 统一处理所有ListBoxItem的选中事件
    var selectedItem = listBox.SelectedItem;
    // 处理逻辑...
}

7.2 预处理事件（隧道事件）

cs 复制代码

<Window PreviewKeyDown="Window_PreviewKeyDown">
    <TextBox PreviewKeyDown="TextBox_PreviewKeyDown"/>
</Window>

cs 复制代码

private void Window_PreviewKeyDown(object sender, KeyEventArgs e)
{
    // 先于TextBox处理KeyDown事件
    if (e.Key == Key.Escape)
    {
        this.Close();
        e.Handled = true;
    }
}

八、最佳实践

命名规范：
- 隧道事件：以"Preview"开头（如PreviewMouseDown）
- 冒泡事件：直接命名（如MouseDown）
事件处理顺序：
- 隧道事件先于冒泡事件触发
- 父元素的隧道事件先于子元素的隧道事件
性能考虑：
- 避免在大量元素上注册相同的路由事件
- 使用事件聚合器模式处理跨控件通信
调试技巧：
- 使用Snoop等工具查看事件传播路径
- 在事件处理程序中输出Source和OriginalSource信息

九、常见问题

9.1 为什么事件没有触发？

检查事件名称是否正确
确认事件处理程序签名是否匹配
检查元素是否在可视树中

9.2 如何确定事件传播路径？

使用调试工具查看逻辑树结构
在每个可能的处理程序中添加日志输出

9.3 何时使用路由事件？

需要在父元素处理子元素事件时
需要事件在多个层级间传播时
实现自定义控件需要事件支持时

路由事件是WPF强大的特性之一，理解其工作原理对于开发复杂的WPF应用程序至关重要。通过合理使用路由事件，可以大大简化事件处理逻辑，提高代码的可维护性。