Przegląd Właściwości dołączone

Artykuł
06/21/2023

Dołączona właściwość jest koncepcją zdefiniowaną przez język XAML. Dołączona właściwość ma być używana jako typ właściwości globalnej, która jest ustawiana na dowolnym obiekcie zależności. W programie Windows Presentation Foundation (WPF) dołączone właściwości są zwykle definiowane jako wyspecjalizowana forma właściwości zależności, która nie ma konwencjonalnej właściwości "otoka".

Wymagania wstępne

W tym artykule założono, że rozumiesz właściwości zależności z perspektywy konsumenta istniejących właściwości zależności w klasach Windows Presentation Foundation (WPF) i zapoznaj się z omówieniem właściwości zależności. Aby postępować zgodnie z przykładami w tym artykule, należy również zrozumieć język XAML i wiedzieć, jak pisać aplikacje WPF.

Dlaczego warto używać dołączonych właściwości

Jednym z celów dołączonej właściwości jest umożliwienie różnym elementom podrzędnym określania unikatowych wartości właściwości zdefiniowanej w elemercie nadrzędnym. Konkretną aplikacją tego scenariusza jest posiadanie elementów podrzędnych, które informują element nadrzędny o tym, jak mają być prezentowane w interfejsie użytkownika. Przykładem jest DockPanel.Dock właściwość . Właściwość DockPanel.Dock jest tworzona jako właściwość dołączona, ponieważ została zaprojektowana tak, aby była ustawiana na elementach, które znajdują się w obiekcie, DockPanel a nie na DockPanel samym sobie. Klasa DockPanel definiuje pole statyczne DependencyProperty o nazwie DockProperty, a następnie udostępnia GetDock metody i SetDock jako publiczne metody dostępu dla dołączonej właściwości.

Dołączone właściwości w języku XAML

W języku XAML ustawiasz dołączone właściwości przy użyciu składni AttachedPropertyProvider.Propertyname

Poniżej przedstawiono przykład sposobu ustawiania DockPanel.Dock kodu XAML:

<DockPanel>
    <TextBox DockPanel.Dock="Top">Enter text</TextBox>
</DockPanel>

Użycie jest nieco podobne do właściwości statycznej; Zawsze odwołujesz się do typu DockPanel , który jest właścicielem i rejestruje dołączoną właściwość, zamiast odwoływać się do dowolnego wystąpienia określonego przez nazwę.

Ponadto, ponieważ dołączona właściwość w języku XAML jest atrybutem ustawionym w adiustacji, tylko operacja zestawu ma jakiekolwiek znaczenie. Nie można bezpośrednio uzyskać właściwości w języku XAML, chociaż istnieją pewne mechanizmy pośrednie do porównywania wartości, takich jak wyzwalacze w stylach (aby uzyskać szczegółowe informacje, zobacz Styling and Templating).

Implementacja dołączonej właściwości w WPF

W programie Windows Presentation Foundation (WPF) większość dołączonych właściwości interfejsu użytkownika w typach WPF jest implementowana jako właściwości zależności. Dołączone właściwości są koncepcją XAML, natomiast właściwości zależności są koncepcją WPF. Ponieważ właściwości dołączone w WPF są właściwościami zależności, obsługują pojęcia właściwości zależności, takie jak metadane właściwości i wartości domyślne z tych metadanych właściwości.

Jak dołączone właściwości są używane przez typ będący właścicielem

Mimo że dołączone właściwości są ustawiane na dowolnym obiekcie, nie oznacza to automatycznie, że ustawienie właściwości spowoduje wygenerowanie namacalnego wyniku lub że wartość będzie kiedykolwiek używana przez inny obiekt. Ogólnie rzecz biorąc, dołączone właściwości są przeznaczone tak, aby obiekty pochodzące z szerokiej gamy możliwych hierarchii klas lub relacji logicznych mogły zgłaszać typowe informacje do typu definiującego dołączoną właściwość. Typ definiujący dołączoną właściwość zwykle jest zgodny z jednym z następujących modeli:

Typ definiujący dołączoną właściwość jest zaprojektowany tak, aby mógł być elementem nadrzędnym elementów, które będą ustawiać wartości dla dołączonej właściwości. Następnie typ iteruje swoje obiekty podrzędne za pomocą logiki wewnętrznej względem struktury drzewa obiektów, uzyskuje wartości i działa na tych wartościach w jakiś sposób.
Typ definiujący dołączoną właściwość będzie używany jako element podrzędny dla różnych możliwych elementów nadrzędnych i con tryb namiotu ls.
Typ definiujący dołączoną właściwość reprezentuje usługę. Inne typy ustawiają wartości dla dołączonej właściwości. Następnie, gdy element, który ustawi właściwość jest obliczany w kontekście usługi, dołączone wartości właściwości są uzyskiwane za pomocą wewnętrznej logiki klasy usługi.

Przykład właściwości dołączonej zdefiniowanej nadrzędnie

Najbardziej typowym scenariuszem, w którym WPF definiuje dołączoną właściwość, jest to, że element nadrzędny obsługuje kolekcję elementów podrzędnych, a także implementuje zachowanie, w którym szczegóły zachowania są zgłaszane indywidualnie dla każdego elementu podrzędnego.

DockPanel definiuje dołączoną DockPanel.Dock właściwość i DockPanel ma kod na poziomie klasy w ramach logiki renderowania (w szczególności MeasureOverride i ArrangeOverride). Wystąpienie DockPanel zawsze sprawdza, czy którykolwiek z jego natychmiastowych elementów podrzędnych ma ustawioną wartość .DockPanel.Dock Jeśli tak, te wartości stają się danymi wejściowymi logiki renderowania zastosowanej do tego konkretnego elementu podrzędnego. Wystąpienia zagnieżdżone DockPanel traktują własne kolekcje elementów podrzędnych, ale takie zachowanie jest specyficzne dla DockPanel DockPanel.Dock sposobu przetwarzania wartości. Teoretycznie możliwe jest, aby dołączone właściwości wpływające na elementy poza bezpośrednim elementem nadrzędnym. DockPanel.Dock Jeśli dołączona właściwość jest ustawiona na element, który nie DockPanel ma elementu nadrzędnego do działania, nie zostanie zgłoszony błąd lub wyjątek. Oznacza to po prostu, że ustawiono wartość właściwości globalnej, ale nie ma bieżącego DockPanel elementu nadrzędnego, który może wykorzystywać informacje.

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

Dołączone właściwości w WPF nie mają typowych metod "otoki" CLR w celu łatwego uzyskiwania/ustawiania dostępu. Jest to spowodowane tym, że dołączona właściwość nie musi być częścią przestrzeni nazw CLR dla wystąpień, w których właściwość jest ustawiona. Jednak procesor XAML musi być w stanie ustawić te wartości, gdy kod XAML jest analizowany. Aby zapewnić obsługę efektywnego użycia dołączonych właściwości, typ właściciela dołączonej właściwości musi zaimplementować dedykowane metody dostępu w formularzu Get PropertyName i SetPropertyName. Te dedykowane metody dostępu są również przydatne do pobierania lub ustawiania dołączonej właściwości w kodzie. Z perspektywy kodu dołączona właściwość jest podobna do pola zapasowego, które ma metody dostępu zamiast metod dostępu do właściwości, a pole zapasowe może istnieć na dowolnym obiekcie, a nie musi być specjalnie zdefiniowane.

W poniższym przykładzie pokazano, jak ustawić dołączoną właściwość w kodzie. W tym przykładzie myCheckBox jest wystąpieniem CheckBox klasy .

DockPanel myDockPanel = new DockPanel();
CheckBox myCheckBox = new CheckBox();
myCheckBox.Content = "Hello";
myDockPanel.Children.Add(myCheckBox);
DockPanel.SetDock(myCheckBox, Dock.Top);

Dim myDockPanel As New DockPanel()
Dim myCheckBox As New CheckBox()
myCheckBox.Content = "Hello"
myDockPanel.Children.Add(myCheckBox)
DockPanel.SetDock(myCheckBox, Dock.Top)

Podobnie jak w przypadku XAML, jeśli myCheckBox nie został jeszcze dodany jako element myDockPanel podrzędny czwartego wiersza kodu, piąty wiersz kodu nie zgłosi wyjątku, ale wartość właściwości nie wchodzi w interakcję z elementem nadrzędnym DockPanel i w ten sposób nic nie zrobi. Tylko wartość ustawiona DockPanel.Dock dla elementu podrzędnego w połączeniu z obecnością elementu nadrzędnego DockPanel spowoduje skuteczne zachowanie w renderowanej aplikacji. (W tym przypadku można ustawić dołączoną właściwość, a następnie dołączyć do drzewa. Możesz też dołączyć do drzewa, a następnie ustawić dołączoną właściwość. Każda kolejność akcji zawiera ten sam wynik.

Metadane dołączonej właściwości

Podczas rejestrowania właściwości FrameworkPropertyMetadata jest ustawiana wartość określająca cechy właściwości, takie jak to, czy właściwość ma wpływ na renderowanie, pomiar itd. Metadane dołączonej właściwości zwykle nie różnią się od właściwości zależności. Jeśli określisz wartość domyślną w zastąpieniu dołączonych metadanych właściwości, ta wartość stanie się wartością domyślną niejawnej dołączonej właściwości w wystąpieniach zastępowanej klasy. W szczególności wartość domyślna jest zgłaszana, jeśli niektóre procesy wysyła zapytania o wartość dołączonej właściwości za pośrednictwem Get metody dostępu dla tej właściwości, określając wystąpienie klasy, w którym określono metadane, a wartość tej dołączonej właściwości nie została ustawiona.

Jeśli chcesz włączyć dziedziczenie wartości właściwości we właściwości, należy użyć dołączonych właściwości, a nie dołączonych właściwości zależności. Aby uzyskać szczegółowe informacje, zobacz Dziedziczenie wartości właściwości.

Niestandardowe dołączone właściwości

Kiedy utworzyć dołączoną właściwość

Możesz utworzyć dołączoną właściwość, gdy istnieje powód, aby mechanizm ustawiania właściwości był dostępny dla klas innych niż klasa definiująca. Najbardziej typowym scenariuszem jest układ. Przykłady istniejących właściwości układu to DockPanel.Dock, Panel.ZIndexi Canvas.Top. W tym scenariuszu włączono, że elementy, które istnieją jako elementy podrzędne do elementów sterujących układem, są w stanie wyrazić wymagania układu do ich elementów nadrzędnych układu indywidualnie, z których każdy ustawia wartość właściwości zdefiniowanej przez element nadrzędny jako dołączoną właściwość.

Innym scenariuszem użycia dołączonej właściwości jest to, że klasa reprezentuje usługę i chcesz, aby klasy mogły integrować usługę w sposób bardziej przejrzysty.

Kolejnym scenariuszem jest otrzymanie obsługi Projektant WPF programu Visual Studio, na przykład edytowanie okna właściwości. Aby uzyskać więcej informacji, zobacz Omówienie tworzenia kontrolek.

Jak wspomniano wcześniej, należy zarejestrować się jako dołączoną właściwość, jeśli chcesz użyć dziedziczenia wartości właściwości.

Jak utworzyć dołączoną właściwość

Jeśli klasa definiuje dołączoną właściwość ściśle do użycia w innych typach, klasa nie musi pochodzić z klasy DependencyObject. Ale musisz pochodzić z DependencyObject , jeśli przestrzegasz ogólnego modelu WPF posiadania dołączonej właściwości również być właściwością zależności.

Zdefiniuj dołączoną właściwość jako właściwość zależności, deklarując public static readonly pole typu DependencyProperty. To pole definiuje się przy użyciu wartości zwracanej RegisterAttached metody . Nazwa pola musi być zgodna z dołączoną nazwą właściwości, dołączoną do ciągu Property, aby postępować zgodnie z ustalonym wzorcem WPF nazewnictwa pól identyfikujących w porównaniu z właściwościami, które reprezentują. Dołączony dostawca właściwości musi również podać statyczne metody GetPropertyName i SetPropertyName jako metody dostępu dla dołączonej właściwości; nie można tego zrobić w systemie właściwości nie może użyć dołączonej właściwości.

Uwaga

Jeśli pominięto metodę dostępu dołączonej właściwości, powiązanie danych we właściwości nie będzie działać w narzędziach projektowych, takich jak Visual Studio i Blend for Visual Studio.

Uzyskiwanie dostępu

Sygnatura metody dostępu GetPropertyName musi być następująca:

public static object GetPropertyName(object target)

Obiekt target można określić jako bardziej konkretny typ w implementacji. Na przykład DockPanel.GetDock metoda typuje parametr jako UIElement, ponieważ dołączona właściwość ma być ustawiana tylko na UIElement wystąpieniach.
Wartość zwracaną można określić jako bardziej konkretny typ w implementacji. Na przykład GetDock metoda wpisze ją jako Dock, ponieważ wartość można ustawić tylko na tę wyliczenie.

Zestaw akcesoriów

Sygnatura metody dostępu SetPropertyName musi być następująca:

public static void SetPropertyName(object target, object value)

Obiekt target można określić jako bardziej konkretny typ w implementacji. Na przykład SetDock metoda wpisze ją jako UIElement, ponieważ dołączona właściwość ma być ustawiana tylko na UIElement wystąpieniach.
Obiekt value można określić jako bardziej konkretny typ w implementacji. Na przykład SetDock metoda wpisze ją jako Dock, ponieważ wartość można ustawić tylko na tę wyliczenie. Pamiętaj, że wartość tej metody to dane wejściowe pochodzące z modułu ładującego XAML, gdy napotka on dołączoną właściwość w dołączonym użyciu właściwości w adiustacji. Te dane wejściowe są wartością określoną jako wartość atrybutu XAML w adiustacji. W związku z tym musi istnieć konwersja typu, serializator wartości lub obsługa rozszerzenia znaczników dla używanego typu, tak aby można było utworzyć odpowiedni typ na podstawie wartości atrybutu (która ostatecznie jest tylko ciągiem).

Poniższy przykład przedstawia rejestrację właściwości zależności (przy użyciu RegisterAttached metody), a także metody GetPropertyName i SetPropertyName metodę dostępu. W tym przykładzie dołączona nazwa właściwości to IsBubbleSource. W związku z tym metody dostępu muszą mieć nazwy GetIsBubbleSource i SetIsBubbleSource.

public static readonly DependencyProperty IsBubbleSourceProperty = DependencyProperty.RegisterAttached(
  "IsBubbleSource",
  typeof(Boolean),
  typeof(AquariumObject),
  new FrameworkPropertyMetadata(false, FrameworkPropertyMetadataOptions.AffectsRender)
);
public static void SetIsBubbleSource(UIElement element, Boolean value)
{
  element.SetValue(IsBubbleSourceProperty, value);
}
public static Boolean GetIsBubbleSource(UIElement element)
{
  return (Boolean)element.GetValue(IsBubbleSourceProperty);
}

Public Shared ReadOnly IsBubbleSourceProperty As DependencyProperty = DependencyProperty.RegisterAttached("IsBubbleSource", GetType(Boolean), GetType(AquariumObject), New FrameworkPropertyMetadata(False, FrameworkPropertyMetadataOptions.AffectsRender))
Public Shared Sub SetIsBubbleSource(ByVal element As UIElement, ByVal value As Boolean)
    element.SetValue(IsBubbleSourceProperty, value)
End Sub
Public Shared Function GetIsBubbleSource(ByVal element As UIElement) As Boolean
    Return CType(element.GetValue(IsBubbleSourceProperty), Boolean)
End Function

Atrybuty dołączonej właściwości

WPF definiuje kilka atrybutów platformy .NET, które mają dostarczać informacje o dołączonych właściwościach do procesów odbicia oraz typowych użytkowników informacji o odbiciem i właściwościach, takich jak projektanci. Ponieważ dołączone właściwości mają typ nieograniczonego zakresu, projektanci potrzebują sposobu, aby uniknąć przeciążenia użytkowników z globalną listą wszystkich dołączonych właściwości zdefiniowanych w określonej implementacji technologii korzystającej z języka XAML. Atrybuty platformy .NET zdefiniowane przez WPF dla dołączonych właściwości mogą służyć do określania zakresu sytuacji, w których dana dołączona właściwość powinna być wyświetlana w oknie właściwości. Możesz również rozważyć zastosowanie tych atrybutów dla własnych niestandardowych dołączonych właściwości. Przeznaczenie i składnia atrybutów platformy .NET są opisane na odpowiednich stronach referencyjnych:

Edukacja więcej informacji o dołączonych właściwościach

Aby uzyskać więcej informacji na temat tworzenia dołączonej właściwości, zobacz Rejestrowanie dołączonej właściwości.
Aby uzyskać bardziej zaawansowane scenariusze użycia właściwości zależności i dołączonych właściwości, zobacz Niestandardowe właściwości zależności.
Możesz również zarejestrować właściwość jako dołączoną właściwość i jako właściwość zależności, ale nadal uwidaczniać implementacje "otoki". W takim przypadku właściwość można ustawić na tym elemecie lub na dowolnym elemecie za pomocą składni właściwości dołączonej XAML. Przykładem właściwości z odpowiednim scenariuszem dla użycia standardowego i dołączonego jest FrameworkElement.FlowDirection.