Przegląd Załączone zdarzeniaAttached Events Overview

Extensible Application Markup Language (XAML) definiuje składnik języka i typ zdarzenia zwanego załączonym zdarzeniem.Extensible Application Markup Language (XAML) defines a language component and type of event called an attached event. Koncepcja dołączonego zdarzenia umożliwia dodanie procedury obsługi dla danego zdarzenia do dowolnego elementu, a nie do elementu, który faktycznie definiuje lub dziedziczy zdarzenie.The concept of an attached event enables you to add a handler for a particular event to an arbitrary element rather than to an element that actually defines or inherits the event. W takim przypadku ani obiekt, który potencjalnie nie może podnieść zdarzenia, ani docelowego wystąpienia obsługi definiuje lub w inny sposób "właścicielem" zdarzenia.In this case, neither the object potentially raising the event nor the destination handling instance defines or otherwise "owns" the event.

Wymagania wstępnePrerequisites

W tym temacie założono, że masz przegląd zdarzeń kierowanych do odczytu i Przegląd XAML (WPF).This topic assumes that you have read Routed Events Overview and XAML Overview (WPF).

Składnia dołączonego zdarzeniaAttached Event Syntax

Dołączone zdarzenia mają składnię języka XAML oraz wzorzec kodowania, który musi być używany przez kod zapasowy w celu obsługi dołączonego użycia zdarzenia.Attached events have a XAML syntax and a coding pattern that must be used by the backing code in order to support the attached event usage.

W składni XAML, dołączone zdarzenie jest określone nie tylko przez jego nazwę zdarzenia, ale przez jego typ, a także nazwę zdarzenia, oddzieloną kropką (.).In XAML syntax, the attached event is specified not just by its event name, but by its owning type plus the event name, separated by a dot (.). Ze względu na to, że nazwa zdarzenia jest kwalifikowana nazwą jego typu będącego właścicielem, podłączona składnia zdarzenia umożliwia dołączenie dowolnego dołączonego zdarzenia do dowolnego elementu, który można utworzyć wystąpienie.Because the event name is qualified with the name of its owning type, the attached event syntax allows any attached event to be attached to any element that can be instantiated.

Na przykład poniżej przedstawiono składnię XAML służącą do dołączania procedury obsługi dla niestandardowego zdarzenia dołączonego NeedsCleaning:For example, the following is the XAML syntax for attaching a handler for a custom NeedsCleaning attached event:

<aqua:Aquarium Name="theAquarium" Height="600" Width="800" aqua:AquariumFilter.NeedsCleaning="WashMe"/>

Zanotuj prefiks aqua:; prefiks jest wymagany w tym przypadku, ponieważ dołączone zdarzenie jest zdarzeniem niestandardowym, które pochodzi z niestandardowego zamapowanego xmlns.Note the aqua: prefix; the prefix is necessary in this case because the attached event is a custom event that comes from a custom mapped xmlns.

Jak WPF implementuje dołączone zdarzeniaHow WPF Implements Attached Events

W WPF dołączone zdarzenia są obsługiwane przez pole RoutedEvent i są kierowane przez drzewo po ich podniesieniu.In WPF, attached events are backed by a RoutedEvent field and are routed through the tree after they are raised. Zazwyczaj źródłem dołączonego zdarzenia (obiektu, który wywołuje zdarzenie) jest system lub źródło usługi, a obiekt, który uruchamia kod, który wywołuje zdarzenie, nie jest częścią drzewa elementu.Typically, the source of the attached event (the object that raises the event) is a system or service source, and the object that runs the code that raises the event is therefore not a direct part of the element tree.

Scenariusze dotyczące zdarzeń załączonychScenarios for Attached Events

W WPF dołączone zdarzenia są obecne w niektórych obszarach funkcji, w których istnieje Abstrakcja na poziomie usług, na przykład dla zdarzeń włączonych przez klasę Mouse static lub klasy Validation.In WPF, attached events are present in certain feature areas where there is service-level abstraction, such as for the events enabled by the static Mouse class or the Validation class. Klasy, które współdziałają z usługą lub używają usługi, mogą albo użyć zdarzenia w składni dołączonego zdarzenia, albo mogą zdecydować się na załączenie dołączonego zdarzenia jako zdarzenia kierowanego, które jest częścią sposobu integracji możliwości usługi przez klasę.Classes that interact with or use the service can either use the event in the attached event syntax, or they can choose to surface the attached event as a routed event that is part of how the class integrates the capabilities of the service.

Chociaż WPF definiuje wiele załączonych zdarzeń, scenariusze, w których będzie można użyć lub obsłużyć dołączone zdarzenie, są bardzo ograniczone.Although WPF defines a number of attached events, the scenarios where you will either use or handle the attached event directly are very limited. Ogólnie rzecz biorąc, dołączone zdarzenie służy do zastosowania architektury, ale jest następnie przekazywane do niedołączonego (przy użyciu zdarzenia CLR "otoka").Generally, the attached event serves an architecture purpose, but is then forwarded to a non-attached (backed with a CLR event "wrapper") routed event.

Na przykład, bazowe dołączone zdarzenie Mouse.MouseDown może być łatwiej obsługiwane na dowolnym UIElement przy użyciu MouseDown na tym UIElement, a nie do zajmowania się składnią zdarzenia dołączonego w języku XAML lub kodzie.For instance, the underlying attached event Mouse.MouseDown can more easily be handled on any given UIElement by using MouseDown on that UIElement rather than dealing with attached event syntax either in XAML or code. Dołączone zdarzenie służy do osiągnięcia celu w architekturze, ponieważ pozwala na przyszłe rozszerzanie urządzeń wejściowych.The attached event serves a purpose in the architecture because it allows for future expansion of input devices. Hipotetyczne urządzenie będzie musiało podnieść Mouse.MouseDown w celu symulowania danych wejściowych myszy i nie musi pochodzić od Mouse, aby to zrobić.The hypothetical device would only need to raise Mouse.MouseDown in order to simulate mouse input, and would not need to derive from Mouse to do so. Jednak ten scenariusz obejmuje obsługę kodu zdarzeń, a obsługa XAML dołączonego zdarzenia nie ma znaczenia dla tego scenariusza.However, this scenario involves code handling of the events, and XAML handling of the attached event is not relevant to this scenario.

Obsługa dołączonego zdarzenia w WPFHandling an Attached Event in WPF

Proces obsługi dołączonego zdarzenia oraz kod programu obsługi, który zostanie zapisany, jest zasadniczo taki sam jak w przypadku zdarzenia kierowanego.The process for handling an attached event, and the handler code that you will write, is basically the same as for a routed event.

Ogólnie rzecz biorąc, dołączone zdarzenie WPF nie różni się od zdarzenia trasowanego WPF.In general, a WPF attached event is not very different from a WPF routed event. Różnice polegają na tym, jak Źródło zdarzenia i jak są udostępniane przez klasę jako element członkowski (co również ma wpływ na składnię procedury obsługi XAML).The differences are how the event is sourced and how it is exposed by a class as a member (which also affects the XAML handler syntax).

Jednak jak wspomniano wcześniej, istniejące zdarzenia dołączone do platformy WPF nie są szczególnie przeznaczone do obsługi w WPF.However, as noted earlier, the existing WPF attached events are not particularly intended for handling in WPF. Często celem zdarzenia jest włączenie elementu złożonego do raportowania stanu do elementu nadrzędnego w ramach składania, w którym to przypadku zdarzenie jest zwykle wywoływane w kodzie i opiera się na obsłudze klas w odpowiedniej klasie nadrzędnej.More often, the purpose of the event is to enable a composited element to report a state to a parent element in compositing, in which case the event is usually raised in code and also relies on class handling in the relevant parent class. Na przykład, elementy w Selector są oczekiwane na podniesienie dołączonego zdarzenia Selected, które jest następnie obsługiwane przez klasę Selector, a następnie możliwe do przekonwertowania przez klasę Selector na inne zdarzenie trasowane SelectionChanged.For instance, items within a Selector are expected to raise the attached Selected event, which is then class handled by the Selector class and then potentially converted by the Selector class into a different routed event, SelectionChanged. Aby uzyskać więcej informacji o rutowanych zdarzeniach i obsłudze klas, zobacz oznaczanie zdarzeń kierowanych jako obsłużone i obsługa klas.For more information on routed events and class handling, see Marking Routed Events as Handled, and Class Handling.

Definiowanie własnych załączonych zdarzeń jako zdarzeń kierowanychDefining Your Own Attached Events as Routed Events

Jeśli pochodzą ze wspólnych klas bazowych WPF, można zaimplementować własne dołączone zdarzenia przez dołączenie określonych metod wzorca w klasie oraz przy użyciu metod narzędziowych, które są już obecne w klasach bazowych.If you are deriving from common WPF base classes, you can implement your own attached events by including certain pattern methods in your class and by using utility methods that are already present on the base classes.

Wzorzec jest następujący:The pattern is as follows:

  • Procedura AddEventName z dwoma parametrami.A method AddEventNameHandler with two parameters. Pierwszy parametr jest wystąpieniem, do którego zostanie dodana procedura obsługi zdarzeń.The first parameter is the instance to which the event handler is added. Drugi parametr jest programem obsługi zdarzeń, który ma zostać dodany.The second parameter is the event handler to add. Metoda musi mieć public i static, bez wartości zwracanej.The method must be public and static, with no return value.

  • Procedura usuwania metodyEventName z dwoma parametrami.A method RemoveEventNameHandler with two parameters. Pierwszy parametr to wystąpienie, z którego jest usuwana procedura obsługi zdarzeń.The first parameter is the instance from which the event handler is removed. Drugi parametr jest programem obsługi zdarzeń do usunięcia.The second parameter is the event handler to remove. Metoda musi mieć public i static, bez wartości zwracanej.The method must be public and static, with no return value.

Metoda dostępu do procedury obsługi DodajEventName ułatwia przetwarzanie kodu XAML, gdy atrybuty programu obsługi zdarzeń dołączone są zadeklarowane w elemencie.The AddEventNameHandler accessor method facilitates XAML processing when attached event handler attributes are declared on an element. Metody obsługi DodajEventName i RemoveEventName umożliwiają również dostęp kodu do magazynu obsługi zdarzeń dla dołączonego zdarzenia.The AddEventNameHandler and RemoveEventNameHandler methods also enable code access to the event handler store for the attached event.

Ten ogólny wzorzec nie jest jeszcze wystarczająco precyzyjny dla praktycznej implementacji w strukturze, ponieważ każda implementacja czytnika XAML może mieć różne schematy do identyfikowania podstawowych zdarzeń w języku i architekturze pomocniczej.This general pattern is not yet precise enough for practical implementation in a framework, because any given XAML reader implementation might have different schemes for identifying underlying events in the supporting language and architecture. Jest to jedna z powodów, w których WPF implementuje dołączone zdarzenia jako zdarzenia kierowane; Identyfikator do użycia dla zdarzenia (RoutedEvent) jest już zdefiniowany przez system zdarzeń WPF.This is one of the reasons that WPF implements attached events as routed events; the identifier to use for an event (RoutedEvent) is already defined by the WPF event system. Ponadto kierowanie zdarzenia jest naturalnym rozszerzeniem implementacji na koncepcji poziomu języka XAML dołączonego zdarzenia.Also, routing an event is a natural implementation extension on the XAML language-level concept of an attached event.

Implementacja programu obsługi DodajEventName dla zdarzenia dołączonego do platformy WPF składa się z wywołania AddHandler z kierowanym zdarzeniem i programem obsługi jako argumentami.The AddEventNameHandler implementation for a WPF attached event consists of calling the AddHandler with the routed event and handler as arguments.

Ta strategia implementacji i system zdarzeń kierowanych w ogólny sposób obsługują zdarzenia dołączone do UIElement klas pochodnych lub ContentElement klas pochodnych, ponieważ tylko te klasy mają implementacje AddHandler.This implementation strategy and the routed event system in general restrict handling for attached events to either UIElement derived classes or ContentElement derived classes, because only those classes have AddHandler implementations.

Na przykład poniższy kod definiuje NeedsCleaning dołączonego zdarzenia w klasie Owner Aquariumprzy użyciu strategii zdarzeń dołączonej WPF w celu zadeklarowania dołączonego zdarzenia jako zdarzenia kierowanego.For example, the following code defines the NeedsCleaning attached event on the owner class Aquarium, using the WPF attached event strategy of declaring the attached event as a routed event.

public static readonly RoutedEvent NeedsCleaningEvent = EventManager.RegisterRoutedEvent("NeedsCleaning", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(AquariumFilter));
public static void AddNeedsCleaningHandler(DependencyObject d, RoutedEventHandler handler)
{
    UIElement uie = d as UIElement;
    if (uie != null)
    {
        uie.AddHandler(AquariumFilter.NeedsCleaningEvent, handler);
    }
}
public static void RemoveNeedsCleaningHandler(DependencyObject d, RoutedEventHandler handler)
{
    UIElement uie = d as UIElement;
    if (uie != null)
    {
        uie.RemoveHandler(AquariumFilter.NeedsCleaningEvent, handler);
    }
}
Public Shared ReadOnly NeedsCleaningEvent As RoutedEvent = EventManager.RegisterRoutedEvent("NeedsCleaning", RoutingStrategy.Bubble, GetType(RoutedEventHandler), GetType(AquariumFilter))
Public Shared Sub AddNeedsCleaningHandler(ByVal d As DependencyObject, ByVal handler As RoutedEventHandler)
    Dim uie As UIElement = TryCast(d, UIElement)
    If uie IsNot Nothing Then
        uie.AddHandler(AquariumFilter.NeedsCleaningEvent, handler)
    End If
End Sub
Public Shared Sub RemoveNeedsCleaningHandler(ByVal d As DependencyObject, ByVal handler As RoutedEventHandler)
    Dim uie As UIElement = TryCast(d, UIElement)
    If uie IsNot Nothing Then
        uie.RemoveHandler(AquariumFilter.NeedsCleaningEvent, handler)
    End If
End Sub

Należy pamiętać, że metoda użyta do ustanowienia pola identyfikatora dołączonego zdarzenia, RegisterRoutedEvent, jest w tej samej metodzie, która jest używana do rejestrowania niedołączonego zdarzenia kierowanego.Note that the method used to establish the attached event identifier field, RegisterRoutedEvent, is actually the same method that is used to register a non-attached routed event. Zdarzenia dołączone i zdarzenia kierowane są rejestrowane w scentralizowanym magazynie wewnętrznym.Attached events and routed events all are registered to a centralized internal store. Ta implementacja magazynu zdarzeń umożliwia zagadnienia dotyczące pojęć "zdarzenia jako interfejs" omówione w temacie Omówienie zdarzeń kierowanych.This event store implementation enables the "events as an interface" conceptual consideration that is discussed in Routed Events Overview.

Wywoływanie zdarzenia dołączonego do platformy WPFRaising a WPF Attached Event

Zazwyczaj nie trzeba zgłaszać istniejących zdarzeń, które zostały dołączone przez WPF z kodu.You do not typically need to raise existing WPF-defined attached events from your code. Te zdarzenia są zgodne z ogólnym modelem koncepcyjnym "usługa", a klasy usług, takie jak InputManager są odpowiedzialne za podnoszenie poziomu zdarzeń.These events follow the general "service" conceptual model, and service classes such as InputManager are responsible for raising the events.

Jednakże w przypadku definiowania niestandardowego zdarzenia dołączonego na podstawie modelu WPF zdarzenia dołączonego na RoutedEvent, można użyć RaiseEvent, aby zgłosić dołączone zdarzenie z dowolnego UIElement lub ContentElement.However, if you are defining a custom attached event based on the WPF model of basing attached events on RoutedEvent, you can use RaiseEvent to raise an attached event from any UIElement or ContentElement. Podnoszenie zdarzenia kierowanego (dołączonego lub nie) wymaga zadeklarowania określonego elementu w drzewie elementów jako źródła zdarzenia; to źródło jest zgłaszane jako obiekt wywołujący RaiseEvent.Raising a routed event (attached or not) requires that you declare a particular element in the element tree as the event source; that source is reported as the RaiseEvent caller. Określenie, który element jest raportowany jako źródło w drzewie, jest odpowiedzialnością usługiDetermining which element is reported as the source in the tree is your service's responsibility

Zobacz takżeSee also