我们先跳出代码，用一个生活中的例子来理解什么是“Tunnelling（隧道/预览）”和“Bubbling（冒泡）”。
1. 形象理解：快递员送货（路由策略）
假设你住在一个大庄园里：庄园 -> 别墅 -> 房间。
-
冒泡事件 (Bubbling - WPF 常用): 你在房间里打碎了一个花瓶。首先是你（房间）知道了，然后惊动了整栋别墅，最后整个庄园的主人都知道了。信号由内向外。
-
隧道事件 (Tunnelling - WPF 的 Preview 事件): 快递员进庄园送货。首先大门口（庄园）拦截了快递检查，然后别墅管家接手，最后才送到你（房间）手里。信号由外向内。
在 WPF 中：
为了区分这两种方向，WPF 给隧道事件专门起了一个名字，叫 PreviewMouseDown。
在 Avalonia 中：
Avalonia 觉得：“我没必要为同一个动作起两个名字（MouseDown 和 PreviewMouseDown），我只需要一个 MouseDown，但在你订阅它的时候，你告诉我你想在哪个阶段拦截它就行了。”
2. 核心区别对照表
| 特性 | WPF 的做法 | Avalonia 的做法 |
|---|---|---|
| 隧道事件 (外 -> 内) | 使用专用名称：PreviewKeyDown |
使用统一名称 + RoutingStrategies.Tunnel |
| 冒泡事件 (内 -> 外) | 使用普通名称：KeyDown |
使用统一名称 + RoutingStrategies.Bubble |
| 订阅方式 | 直接 += 即可 |
必须使用 AddHandler(...) 方法 |
3. 代码实战：如何拦截“隧道”事件
假设你有一个 StackPanel，里面装了一个 Button。你想在按钮点击之前，先在 StackPanel 层面拦截这个点击动作。
在 WPF 中（你可能熟悉的）：
// WPF 专门提供了一个带 Preview 开头的事件名
myStackPanel.PreviewMouseDown += MyHandler; 在 Avalonia 中（文档里提到的做法）：
Avalonia 没有 PreviewMouseDown 这个成员，你得这么写：
using Avalonia.Interactivity; // 必须引用这个命名空间// 参数 1: 想要监听的事件（注意是静态只读字段 PointerPressedEvent）
// 参数 2: 你的处理函数
// 参数 3: 路由策略。RoutingStrategies.Tunnel 表示“隧道阶段”（从外向内时触发）
this.AddHandler(InputElement.PointerPressedEvent, OnPointerPressed, RoutingStrategies.Tunnel);// 处理函数
private void OnPointerPressed(object? sender, PointerPressedEventArgs e)
{// 这里的代码会在子控件（比如按钮）收到点击信号之前执行Debug.WriteLine("隧道阶段：庄园大门拦截到了点击！");
}4. 为什么要用 AddHandler 这么麻烦？
你可能会觉得 += 这种写法多简洁啊，为什么 Avalonia 要推推搡搡地让你用 AddHandler？
- 更少的冗余：Avalonia 不需要为每个事件定义两套 C# 包装器（如
KeyDown和PreviewKeyDown），减小了框架体积。 - 更精细的控制：通过
AddHandler，你可以明确指定是否处理“已经被标记为已处理（Handled）”的事件。 - 性能优化：这种显式的订阅方式让事件系统的内存管理更加高效。
5. 总结：你该怎么做？
如果你在迁移 WPF 代码时，发现找不到 PreviewXXXX 这样的事件：
- 找到对应的普通事件名（比如
KeyDown对应InputElement.KeyDownEvent）。 - 不要用
+=。 - 使用
this.AddHandler(..., RoutingStrategies.Tunnel)。