预览事件 (WPF .NET)

项目
10/24/2024

预览事件，也称为隧道事件，是从应用程序根元素向下遍历元素树到引发事件的元素的路由事件。引发事件的元素在事件数据中报告为 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);
    }
}

Partial Public Class MainWindow
        Inherits Window

        Public Sub New()
        InitializeComponent()

        ' Attach a handler on outerStackPanel that will be invoked by handled KeyDown events.
        outerStackPanel.[AddHandler](KeyDownEvent, New RoutedEventHandler(AddressOf Handler_PrintEventInfo),
                                     handledEventsToo:=True)
    End Sub

    Private Sub ComponentWrapper_KeyDown(sender As Object, e As KeyEventArgs)
        Handler_PrintEventInfo(sender, e)
        Debug.WriteLine("KeyDown event marked as handled on componentWrapper." &
                        vbCrLf & "CustomKey event raised on componentWrapper.")

        ' Mark the event as handled.
        e.Handled = True

        ' Raise the custom click event.
        componentWrapper.RaiseCustomRoutedEvent()
    End Sub

    Private Sub Handler_PrintEventInfo(sender As Object, e As KeyEventArgs)
        Dim senderName As String = CType(sender, FrameworkElement).Name
        Dim sourceName As String = CType(e.Source, FrameworkElement).Name
        Dim eventName As String = e.RoutedEvent.Name
        Dim handledEventsToo As String = If(e.Handled, " Parameter handledEventsToo set to true.", "")
        Debug.WriteLine($"Handler attached to {senderName} " &
                        $"triggered by {eventName} event raised on {sourceName}.{handledEventsToo}")
    End Sub

    Private Sub Handler_PrintEventInfo(sender As Object, e As RoutedEventArgs)
        Dim senderName As String = CType(sender, FrameworkElement).Name
        Dim sourceName As String = CType(e.Source, FrameworkElement).Name
        Dim eventName As String = e.RoutedEvent.Name
        Dim handledEventsToo As String = If(e.Handled, " Parameter handledEventsToo set to true.", "")
        Debug.WriteLine($"Handler attached to {senderName} " &
                        $"triggered by {eventName} event raised on {sourceName}.{handledEventsToo}")
    End Sub

    ' 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.
End Class

    Public Class ComponentWrapper
        Inherits StackPanel

        ' Register a custom routed event with the Bubble routing strategy.
        Public Shared ReadOnly CustomKeyEvent As RoutedEvent =
            EventManager.RegisterRoutedEvent(
                name:="CustomKey",
                routingStrategy:=RoutingStrategy.Bubble,
                handlerType:=GetType(RoutedEventHandler),
                ownerType:=GetType(ComponentWrapper))

        ' Provide CLR accessors to support event handler assignment.
        Public Custom Event CustomKey As RoutedEventHandler

            AddHandler(value As RoutedEventHandler)
                [AddHandler](CustomKeyEvent, value)
            End AddHandler

            RemoveHandler(value As RoutedEventHandler)
                [RemoveHandler](CustomKeyEvent, value)
            End RemoveHandler

            RaiseEvent(sender As Object, e As RoutedEventArgs)
                [RaiseEvent](e)
            End RaiseEvent

        End Event

    Public Sub RaiseCustomRoutedEvent()
        ' Create a RoutedEventArgs instance & raise the event,
        ' which will bubble up through the element tree.
        Dim routedEventArgs As New RoutedEventArgs(routedEvent:=CustomKeyEvent)
            [RaiseEvent](routedEventArgs)
        End Sub
    End Class

该示例演示了两种解决方法，用于获取禁止的 KeyDown 路由事件以调用附加到 outerStackPanel 的事件处理程序：

将 PreviewKeyDown 事件处理程序附加到 outerStackPanel。由于预览输入路由事件先于等效的浮升路由事件，因此示例中的 PreviewKeyDown 处理程序在 KeyDown 处理程序之前运行，后者通过共享事件数据禁止预览和浮升事件。
使用代码隐藏中的 UIElement.AddHandler(RoutedEvent, Delegate, Boolean) 方法将 KeyDown 事件处理程序附加到 outerStackPanel，并将 handledEventsToo 参数设置为 true。

注意

将输入事件的预览或非预览等效项标记为“已处理”都是禁止控件组件引发的事件的策略。使用的方法取决于应用程序要求。

通过

预览事件 (WPF .NET)

先决条件

预览标记为“已处理”的事件

通过控件解决事件禁止问题

另请参阅

其他资源