Metadane właściwości zależności (WPF .NET)

System Windows Presentation Foundation (WPF) zawiera system raportowania metadanych właściwości zależności. Informacje dostępne za pośrednictwem systemu raportowania metadanych przekraczają to, co jest dostępne za pośrednictwem odbicia lub ogólnych cech środowiska uruchomieniowego języka wspólnego (CLR). Podczas rejestrowania właściwości zależności możesz utworzyć i przypisać do niego metadane. Jeśli pochodzisz od klasy definiującej właściwość zależności, możesz przesłonić metadane dziedziczonej właściwości zależności. A jeśli dodasz klasę jako właściciela właściwości zależności, możesz przesłonić metadane dziedziczonej właściwości zależności.

Ważne

Dokumentacja przewodników klasycznych dla platform .NET 6 i .NET 5 (w tym .NET Core 3.1) jest w trakcie budowy.

Wymagania wstępne

W tym artykule założono, że masz podstawową wiedzę na temat właściwości zależności oraz że przeczytaliśmy artykuł Omówienie właściwości zależności. Aby postępować zgodnie z przykładami w tym artykule, warto zapoznać się z Extensible Application Markup Language (XAML) i pisania aplikacji WPF.

Jak są używane metadane

Możesz odpytać metadane właściwości zależności, aby sprawdzić charakterystykę właściwości zależności. Gdy system właściwości przetwarza właściwość zależności, uzyskuje dostęp do jej metadanych. Obiekt metadanych dla właściwości zależności zawiera następujące typy informacji:

  • Wartość domyślna właściwości zależności, która jest ustawiana przez system właściwości, gdy nie ma żadnych innych wartości, takich jak wartość lokalna, styl lub wartość dziedziczenia. Aby uzyskać więcej informacji na temat pierwszeństwa wartości podczas przypisywania wartości właściwości zależności w czasie wykonania, zobacz Pierwszeństwo wartości właściwości zależności.

  • Odwołania do wywołań zwrotnych wartości wywłaszczania i wywołań zwrotnych zmiany właściwości w typie właściciela. Odwołania można uzyskać tylko do wywołań zwrotnych, które mają public modyfikator dostępu lub znajdują się w dozwolonym zakresie dostępu. Aby uzyskać więcej informacji na temat wywołań zwrotnych właściwości zależności, zobacz Wywołania zwrotne właściwości zależności i walidacja.

  • Właściwości zależności na poziomie platformy WPF (jeśli właściwość zależności jest właściwością struktury WPF). Procesy WPF, takie jak aparat układu struktury i logika dziedziczenia właściwości, odpytuj metadane na poziomie platformy WPF. Aby uzyskać więcej informacji, zobacz Framework property metadata (Metadane właściwości struktury).

Interfejsy API metadanych

Klasa PropertyMetadata przechowuje większość metadanych używanych przez system właściwości. Wystąpienia metadanych można tworzyć i przypisywać za pomocą:

  • Typy rejestrujące właściwości zależności w systemie właściwości.

  • Typy dziedziczące z klasy definiującej właściwość zależności.

  • Typy, które dodają siebie jako właściciela właściwości zależności.

Jeśli typ rejestruje właściwość zależności bez określania metadanych, system PropertyMetadata właściwości przypisuje obiekt z wartościami domyślnymi dla tego typu do właściwości dependency.

Aby pobrać metadane dla właściwości zależności, wywołaj jedno GetMetadata z przeciążeń identyfikatora DependencyProperty . Metadane są zwracane jako PropertyMetadata obiekt .

Bardziej szczegółowe klasy metadanych pochodzące z klasy PropertyMetadataistnieją dla różnych obszarów architektury. Na przykład program obsługuje UIPropertyMetadata raportowanie animacji i obsługuje FrameworkPropertyMetadata właściwości platformy WPF. Właściwości zależności można również zarejestrować w klasach PropertyMetadata pochodnych. Mimo GetMetadata że zwraca obiekt PropertyMetadata , jeśli ma to zastosowanie, można rzutować na typ pochodny, aby zbadać właściwości specyficzne dla typu.

Właściwości, które są udostępniane przez FrameworkPropertyMetadata są czasami określane jako flagi. Podczas tworzenia wystąpienia FrameworkPropertyMetadata można przekazać wystąpienie typu wyliczenia do FrameworkPropertyMetadataOptions konstruktora FrameworkPropertyMetadata . FrameworkPropertyMetadataOptions Umożliwia określenie flag metadanych w kombinacji bitowej. Używa FrameworkPropertyMetadata , FrameworkPropertyMetadataOptions aby zachować długość sygnatury konstruktora uzasadnione. W przypadku rejestracji właściwości zależności flagi metadanych FrameworkPropertyMetadataOptionsFrameworkPropertyMetadataBoolean ustawione w programie są udostępniane jako właściwości, a nie bitowa kombinacja flag, aby właściwości metadanych zapytań było bardziej intuicyjne.

Przesłaniać lub utworzyć nowe metadane?

Gdy dziedziczysz właściwość zależności, możesz zmienić właściwości zależności przez zastąpienie jej metadanych. Jednak może nie być zawsze możliwe zrealizowanie scenariusza właściwości zależności przez zastąpienie metadanych, a czasami konieczne jest zdefiniowanie niestandardowej właściwości zależności w klasie przy użyciu nowych metadanych. Niestandardowe właściwości zależności mają takie same możliwości jak właściwości zależności zdefiniowane przez typy WPF. Aby uzyskać więcej informacji, zobacz Właściwości zależności niestandardowych.

Jedną z cech właściwości zależności, których nie można przesłonić, jest jej typ wartości. Jeśli dziedziczona właściwość zależności ma przybliżone zachowanie, które jest potrzebne, ale scenariusz wymaga innego typu wartości, rozważ zaimplementowanie niestandardowej właściwości zależności. Możesz połączyć wartości właściwości za pośrednictwem konwersji typu lub innej implementacji w klasie pochodnej.

Scenariusze zastępowania metadanych

Przykładowe scenariusze zastępowania istniejących metadanych właściwości zależności to:

  • Zmiana wartości domyślnej, co jest powszechnym scenariuszem.

  • Zmiana lub dodanie wywołań zwrotnych zmiany właściwości, co może być konieczne, jeśli dziedziczona właściwość zależności współdziała z innymi właściwościami zależności w inny sposób niż jej podstawowa implementacja. Jedną z cech modelu programowania, który obsługuje kod i znacznik, jest to, że wartości właściwości mogą być ustawiane w dowolnej kolejności. Ten czynnik może mieć wpływ na sposób implementacji wywołań zwrotnych zmiany właściwości. Aby uzyskać więcej informacji, zobacz Wywołania zwrotne właściwości zależności i walidacja.

  • Zmiana opcji metadanych właściwości platformy WPF. Zazwyczaj opcje metadanych są ustawiane podczas rejestracji nowej właściwości zależności, ale można je określić w wywołań OverrideMetadata lub AddOwner . Aby uzyskać więcej informacji na temat zastępowania metadanych właściwości struktury, zobacz Określanie metadanych. Aby dowiedzieć się, jak ustawić opcje metadanych właściwości struktury podczas rejestrowania właściwości zależności, zobacz Właściwości zależności niestandardowych.

Uwaga

Ponieważ wywołania zwrotne weryfikacji nie są częścią metadanych, nie można ich zmienić przez zastąpienie metadanych. Aby uzyskać więcej informacji, zobacz Wywołania zwrotne weryfikacji.

Zastępowanie metadanych

Podczas implementowania nowej właściwości zależności można ustawić jej metadane przy użyciu przeciążeń Register metody . Jeśli klasa dziedziczy właściwość zależności, możesz zastąpić dziedziczone wartości metadanych przy użyciu OverrideMetadata metody . Na przykład można użyć funkcji , OverrideMetadata aby ustawić wartości specyficzne dla typu. Aby uzyskać więcej informacji i przykłady kodu, zobacz Przesłanianie metadanych dla właściwości zależności.

Przykładem właściwości zależności WPF jest Focusable. Klasa FrameworkElement rejestruje klasę Focusable. Klasa Control pochodzi od klasy FrameworkElement, dziedziczy właściwość Focusable zależności i zastępuje dziedziczone metadane właściwości. Przesłonięcie zmienia domyślną wartość właściwości z false na true, ale zachowuje inne dziedziczone wartości metadanych.

Ponieważ większość istniejących właściwości zależności nie jest właściwościami wirtualnymi, dziedziczona implementacja przesłania istniejący członek. Gdy zastąpisz cechę metadanych, nowa wartość metadanych zastępuje oryginalną wartość lub jest scalona:

  • W przypadku DefaultValuewartości nowa wartość zastąpi istniejącą wartość domyślną. Jeśli nie określisz obiektu w DefaultValue metadanych przesłonięcia, wartość pochodzi z najbliższego elementu nadrzędnego określonego w DefaultValue metadanych.

  • W przypadku PropertyChangedCallbackobiektu domyślna logika scalania PropertyChangedCallback przechowuje wszystkie wartości w tabeli, a wszystkie są wywoływane po zmianie właściwości. Kolejność wywołania zwrotnego jest określana na podstawie głębokości klasy, gdzie wywołanie zwrotne zarejestrowane przez klasę bazową w hierarchii zostanie uruchomione jako pierwsze.

  • W przypadku CoerceValueCallbackwartości nowa wartość zastąpi istniejącą CoerceValueCallback wartość. Jeśli nie określisz obiektu w CoerceValueCallback metadanych przesłonięcia, wartość pochodzi z najbliższego elementu nadrzędnego określonego w CoerceValueCallback metadanych.

Uwaga

Domyślna logika scalania jest implementowany przez Merge metodę . Niestandardową logikę scalania można określić w klasie pochodnej, która dziedziczy właściwość zależności, przesłaniając Merge ją w tej klasie.

Dodawanie klasy jako właściciela

Aby "dziedziczyć" właściwość zależności zarejestrowaną w innej hierarchii klas, użyj AddOwner metody . Ta metoda jest zwykle używana, gdy klasa dodawania nie pochodzi od typu, który zarejestrował właściwość zależności. W wywołaniu AddOwner klasa dodawania może tworzyć i przypisywać metadane specyficzne dla typu dla dziedziczonej właściwości zależności. Aby być pełnym uczestnikiem systemu właściwości, za pomocą kodu i znaczników klasa dodawania powinna implementować te publiczne składowe:

  • Pole identyfikatora właściwości zależności. Wartość identyfikatora właściwości zależności jest zwracaną wartością wywołania AddOwner . To pole powinno być polem public static readonly typu DependencyProperty.

  • Otoka CLR, która implementuje i getset klasy dostępu. Za pomocą otoki właściwości użytkownicy właściwości zależności mogą uzyskać lub ustawić wartości właściwości zależności, tak jak każdą inną właściwość CLR. Klasy get dostępu i set współdziałają z bazowym systemem właściwości za DependencyObject.GetValue pośrednictwem funkcji i DependencyObject.SetValue , przekazując identyfikator właściwości zależności jako parametr. Zaim implementuj otokę w taki sam sposób, jak podczas rejestrowania niestandardowej właściwości zależności. Aby uzyskać więcej informacji, zobacz Właściwości zależności niestandardowych

Klasa, która wywołuje AddOwner klasę, ma takie same wymagania dotyczące uwypowienia modelu obiektów dziedziczonej właściwości zależności jako klasy definiującej nową niestandardową właściwość zależności. Aby uzyskać więcej informacji, zobacz Dodawanie typu właściciela dla właściwości zależności.

Dołączone metadane właściwości

W WPF większość właściwości dołączonych powiązanych z interfejsem użytkownika w typach WPF jest implementowane jako właściwości zależności. Dołączone właściwości zaimplementowane jako właściwości zależności obsługują koncepcje właściwości zależności, takie jak metadane, które klasy pochodne mogą przesłonić. Metadane dołączonej właściwości zazwyczaj nie różnią się od metadanych właściwości zależności. Można przesłonić wartość domyślną, wywołania zwrotne zmian właściwości i właściwości platformy WPF dla dziedziczonej dołączonej właściwości w wystąpieniach klasy zastępującej. Aby uzyskać więcej informacji, zobacz Dołączone metadane właściwości

Uwaga

Zawsze używaj elementu RegisterAttached do rejestrowania właściwości, w których Inherits określasz w metadanych. Chociaż dziedziczenie wartości właściwości może wydawać się działać w przypadku niedołączonych właściwości zależności, zachowanie dziedziczenia wartości dla niedołączonej właściwości za pośrednictwem niektórych dzielenia obiektów w drzewie środowiska uruchomieniowego jest niezdefiniowane. Właściwość Inherits nie ma znaczenia dla niedołączanych właściwości. Aby uzyskać więcej informacji, zobacz RegisterAttached(String, Type, Type, PropertyMetadata)i sekcję uwagi .Inherits

Dodawanie klasy jako właściciela dołączonej właściwości

Aby dziedziczyć właściwość dołączona z innej klasy, ale uwidocznić ją jako niedołączoną właściwość zależności w klasie:

  • Wywołaj AddOwner element , aby dodać klasę jako właściciela dołączonej właściwości zależności.

  • Przypisz wartość zwracaną wywołania AddOwner do pola public static readonly do użycia jako identyfikator właściwości zależności.

  • Zdefiniuj otokę CLR, która dodaje właściwość jako członka klasy i obsługuje niedołąkowane użycie właściwości.

Zobacz też