预览事件，也称为隧道事件，是从应用程序根元素向下遍历元素树到引发事件的元素的路由事件。 引发事件的元素在事件数据中报告为Source
。 并非所有事件场景都支持或需要预览事件。 本文介绍了预览事件存在的位置以及应用程序或组件如何与其交互。
本文假定你对路由事件有基本的了解，并且已阅读路由事件概述
。 若要遵循本文中的示例，如果熟悉 Extensible Application Markup Language (XAML) 并知道如何编写 Windows Presentation Foundation (WPF) 应用程序，将会很有帮助。
在事件数据中将预览事件标记为“已处理”时要谨慎。 将预览事件标记为已在引发该事件的元素之外的其他元素上处理，可阻止引发该事件的元素处理该事件。 有时，将预览事件标记为“已处理”是有意的。 例如，复合控件可能会禁止由单个组件引发的事件，并将它们替换为由完整控件引发的事件。 控件的自定义事件可以根据组件状态关系提供自定义的事件数据和触发器。
对于
输入事件，事件数据由每个事件的预览和非预览（浮升）等效项共享。 如果使用预览事件类处理程序将输入事件标记为“已处理”，则通常不会调用浮升输入事件的类处理程序。 或者，如果使用预览事件实例处理程序将事件标记为“已处理”，则通常不会调用浮升输入事件的实例处理程序。 尽管即使将事件标记为“已处理”，你也可以配置要调用的类和实例处理程序，但该处理程序配置并不常见。
并非所有预览事件都是隧道
事件。 例如，PreviewMouseLeftButtonDown?输入事件通过元素树跟踪向下路由，但它是由路径中的每个?UIElement?引发和重新引发的
直接路由事件。
一些复合控件在组件级别禁止输入事件，以便将其替换为自定义的高级事件。 例如，WPF?ButtonBase?将?MouseLeftButtonDown?浮升输入事件标记为在其?OnMouseLeftButtonDown?方法中处理并引发?Click?事件。?MouseLeftButtonDown?事件及其事件数据仍沿元素树路径继续，但由于该事件在事件数据中标记为?Handled，因此将仅调用配置为响应“已处理”事件的处理程序。
如果希望由应用程序根目录的其他元素处理标记为“已处理”的路由事件，则可以执行以下操作：
通过调用?UIElement.AddHandler(RoutedEvent, Delegate, Boolean)?方法并将参数?handledEventsToo?设置为?true?来附加处理程序。 此方法需要在获取要附加到的元素的对象引用后，在代码隐藏中附加事件处理程序。
如果标记为“已处理”的事件是浮升事件，则附加等效预览事件的处理程序（如果可用）。 例如，如果控件禁止了?MouseLeftButtonDown?事件，则可以改为附加?PreviewMouseLeftButtonDown?事件的处理程序。 此方法仅适用于实现
隧道和
浮升路由策略并共享事件数据的基元素输入事件。
以下示例实现了一个名为?componentWrapper?的基本自定义控件，其中包含一个?TextBox。 控件被添加到名为?outerStackPanel?的?StackPanel。
<StackPanel Name="outerStackPanel"
VerticalAlignment="Center"
custom:ComponentWrapper.CustomKey="Handler_PrintEventInfo"
TextBox.KeyDown="Handler_PrintEventInfo"
TextBox.PreviewKeyDown="Handler_PrintEventInfo" >
<custom:ComponentWrapper
x:Name="componentWrapper"
TextBox.KeyDown="ComponentWrapper_KeyDown"
custom:ComponentWrapper.CustomKey="Handler_PrintEventInfo"
HorizontalAlignment="Center">
<TextBox Name="componentTextBox" Width="200" KeyDown="Handler_PrintEventInfo" />
</custom:ComponentWrapper>
</StackPanel>
每当发生击键操作时，componentWrapper?控件都会侦听由其?TextBox?组件引发的?KeyDown?浮升事件。 在这种情况下，componentWrapper?控件：
将?KeyDown?浮升路由事件标记为“已处理”以禁止该事件。 因此，只会触发在代码隐藏中配置为响应“已处理”KeyDown?事件的?outerStackPanel?处理程序。 不会调用在 XAML 中为?KeyDown?事件附加的?outerStackPanel?处理程序。
引发名为?CustomKey?的自定义浮升路由事件，该事件触发?CustomKey?事件的?outerStackPanel?处理程序。
public partial class MainWindow : Window
{
public MainWindow()
{
InitializeComponent();
// Attach a handler on outerStackPanel that will be invoked by handled KeyDown events.
outerStackPanel.AddHandler(KeyDownEvent, new RoutedEventHandler(Handler_PrintEventInfo),
handledEventsToo: true);
}
private void ComponentWrapper_KeyDown(object sender, System.Windows.Input.KeyEventArgs e)
{
Handler_PrintEventInfo(sender, e);
Debug.WriteLine("KeyDown event marked as handled on componentWrapper.\r\n" +
"CustomKey event raised on componentWrapper.");
// Mark the event as handled.
e.Handled = true;
// Raise the custom click event.
componentWrapper.RaiseCustomRoutedEvent();
}
private void Handler_PrintEventInfo(object sender, System.Windows.Input.KeyEventArgs e)
{
string senderName = ((FrameworkElement)sender).Name;
string sourceName = ((FrameworkElement)e.Source).Name;
string eventName = e.RoutedEvent.Name;
string handledEventsToo = e.Handled ? " Parameter handledEventsToo set to true." : "";
Debug.WriteLine($"Handler attached to {senderName} " +
$"triggered by {eventName} event raised on {sourceName}.{handledEventsToo}");
}
private void Handler_PrintEventInfo(object sender, RoutedEventArgs e)
{
string senderName = ((FrameworkElement)sender).Name;
string sourceName = ((FrameworkElement)e.Source).Name;
string eventName = e.RoutedEvent.Name;
string handledEventsToo = e.Handled ? " Parameter handledEventsToo set to true." : "";
Debug.WriteLine($"Handler attached to {senderName} " +
$"triggered by {eventName} event raised on {sourceName}.{handledEventsToo}");
}
// Debug output:
//
// Handler attached to outerStackPanel triggered by PreviewKeyDown event raised on componentTextBox.
// Handler attached to componentTextBox triggered by KeyDown event raised on componentTextBox.
// Handler attached to componentWrapper triggered by KeyDown event raised on componentTextBox.
// KeyDown event marked as handled on componentWrapper.
// CustomKey event raised on componentWrapper.
// Handler attached to componentWrapper triggered by CustomKey event raised on componentWrapper.
// Handler attached to outerStackPanel triggered by CustomKey event raised on componentWrapper.
// Handler attached to outerStackPanel triggered by KeyDown event raised on componentTextBox. Parameter handledEventsToo set to true.
}
public class ComponentWrapper : StackPanel
{
// Register a custom routed event using the Bubble routing strategy.
public static readonly RoutedEvent CustomKeyEvent =
EventManager.RegisterRoutedEvent(
name: "CustomKey",
routingStrategy: RoutingStrategy.Bubble,
handlerType: typeof(RoutedEventHandler),
ownerType: typeof(ComponentWrapper));
// Provide CLR accessors for assigning an event handler.
public event RoutedEventHandler CustomKey
{
add { AddHandler(CustomKeyEvent, value); }
remove { RemoveHandler(CustomKeyEvent, value); }
}
public void RaiseCustomRoutedEvent()
{
// Create a RoutedEventArgs instance.
RoutedEventArgs routedEventArgs = new(routedEvent: CustomKeyEvent);
// Raise the event, which will bubble up through the element tree.
RaiseEvent(routedEventArgs);
}
}
该示例演示了两种解决方法，用于获取禁止的?KeyDown?路由事件以调用附加到?outerStackPanel?的事件处理程序：
将?PreviewKeyDown?事件处理程序附加到?outerStackPanel。 由于预览输入路由事件先于等效的浮升路由事件，因此示例中的?PreviewKeyDown?处理程序在?KeyDown?处理程序之前运行，后者通过共享事件数据禁止预览和浮升事件。
使用代码隐藏中的?UIElement.AddHandler(RoutedEvent, Delegate, Boolean)?方法将?KeyDown?事件处理程序附加到?outerStackPanel，并将?handledEventsToo?参数设置为?true。
?备注
将输入事件的预览或非预览等效项标记为“已处理”都是禁止控件组件引发的事件的策略。 使用的方法取决于应用程序要求。