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

Dołączona właściwość jest pojęciem zdefiniowanym przez język XAML. Dołączona właściwość jest przeznaczona do użycia jako typ właściwości globalnej, która jest settable dla dowolnego obiektu. 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".

Wymagany

W tym artykule założono, że rozumiesz właściwości zależności od perspektywy konsumenta istniejących właściwości zależności w Windows Presentation Foundation (WPF) klasach 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ślenie unikatowych wartości dla właściwości, która jest zdefiniowana w elemencie nadrzędnym. Określona aplikacja tego scenariusza ma elementy podrzędne, które informują element nadrzędny o tym, w jaki sposób mają być prezentowane w interfejs użytkownika (UI) . Przykładem jest DockPanel.Dock Właściwość. DockPanel.DockWłaściwość jest tworzona jako dołączona właściwość, ponieważ została zaprojektowana tak, aby była ustawiona dla elementów, które znajdują się w, DockPanel a nie na DockPanel samej samej. DockPanelKlasa definiuje DependencyProperty pole statyczne o nazwie DockProperty , a następnie udostępnia GetDock SetDock metody i jako publiczne dostęp do 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. Funkcja PropertyName

Poniżej przedstawiono przykład sposobu ustawienia DockPanel.Dock w języku XAML:

<DockPanel>
  <CheckBox DockPanel.Dock="Top">Hello</CheckBox>
</DockPanel>

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

Ponadto, ponieważ dołączona właściwość w języku XAML jest atrybutem ustawionym w znaczniku, tylko operacja ustawiania ma wszelkie istotność. 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 Style i tworzenia szablonów).

Załączona implementacja właściwości w WPF

W programie Windows Presentation Foundation (WPF) większość powiązanych właściwości związanych z interfejsem użytkownika w typach WPF jest implementowana jako właściwości zależności. Dołączone właściwości są koncepcją języka XAML, podczas gdy właściwości zależności są koncepcją WPF. Ponieważ właściwości dołączone do platformy WPF są właściwościami zależności, obsługują one koncepcje właściwości zależności, takie jak metadane właściwości i wartości domyślne z tego metadanych właściwości.

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

Mimo że dołączone właściwości są ustawiane na dowolnym obiekcie, który nie oznacza, że ustawienie właściwości spowoduje wygenerowanie wyniku materialnego lub że wartość będzie kiedykolwiek używana przez inny obiekt. Ogólnie rzecz biorąc, dołączone właściwości są zamierzone, aby obiekty pochodzące z szerokiej gamy hierarchii klas lub relacje logiczne mogły raportować typowe informacje do typu, który definiuje przyłączoną właściwość. Typ, który definiuje załączoną Właściwość zwykle jest zgodny z jednym z następujących modeli:

  • Typ, który definiuje załączoną właściwość jest zaprojektowana tak, aby mógł być elementem nadrzędnym elementów, które będą ustawiać wartości dla dołączonej właściwości. Typ, a następnie wykonuje iterację obiektów podrzędnych za pomocą logiki wewnętrznej względem niektórych struktur drzewa obiektów, uzyskuje wartości i działa na tych wartości w jakiś sposób.

  • Typ, który definiuje załączoną właściwość, będzie używany jako element podrzędny dla różnych możliwych elementów nadrzędnych i modeli zawartości.

  • Typ, który definiuje załączoną właściwość, reprezentuje usługę. Inne typy ustawiają wartości dla dołączonej właściwości. Następnie, gdy element ustawiający właściwość jest oceniany w kontekście usługi, wartości dołączonych właściwości są uzyskiwane za pomocą wewnętrznej logiki klasy usługi.

Przykład Parent-Defined dołączonej właściwości

Typowy scenariusz, w którym WPF definiuje dołączoną właściwość, gdy element nadrzędny obsługuje kolekcję elementów podrzędnych, a także implementuje zachowanie w przypadku, gdy szczegółowe informacje o zachowaniu są raportowane osobno dla każdego elementu podrzędnego.

DockPanel definiuje DockPanel.Dock załączoną Właściwość i DockPanel ma kod na poziomie klasy jako część logiki renderowania (w odniesieniu MeasureOverride i ArrangeOverride ). DockPanelWystąpienie będzie zawsze sprawdzać, czy którykolwiek z jego bezpośrednich elementów podrzędnych ustawił wartość dla DockPanel.Dock . Jeśli tak, te wartości staną się danymi wejściowymi dla logiki renderowania zastosowanej do danego elementu podrzędnego. DockPanelWystąpienia zagnieżdżone każda traktują swoje własne bezpośrednie kolekcje elementów, ale takie zachowanie jest specyficzne dla implementacji dla DockPanel procesów DockPanel.Dock . Teoretycznie możliwe jest dołączenie właściwości, które mają wpływ na elementy poza bezpośrednim elementem nadrzędnym. Jeśli DockPanel.Dock dołączona właściwość jest ustawiona dla elementu, który nie ma DockPanel elementu nadrzędnego do działania, żaden błąd lub wyjątek nie zostanie zgłoszony. Oznacza to po prostu, że wartość właściwości globalnej została ustawiona, ale nie ma bieżącego DockPanel elementu nadrzędnego, który mógłby wykorzystać te informacje.

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

Dołączone właściwości w WPF nie mają typowych metod "otoki" środowiska CLR w celu ułatwienia dostępu do usługi get/set. Wynika to z faktu, ż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 mieć możliwość ustawiania tych wartości podczas analizowania kodu XAML. Aby można było obsługiwać efektywne dołączone właściwości, typ właściciela dołączonej właściwości musi implementować metody dostępu dedykowanego w formularzu Get * PropertyName* i *Set PropertyName * * *. Te dedykowane metody dostępu są również przydatne do pobierania lub ustawiania dołączonej właściwości w kodzie. W perspektywie kodu dołączona właściwość jest podobna do pola zapasowego, które ma metody dostępu do właściwości, i że pole zapasowe może istnieć na dowolnym obiekcie, a nie musi być jawnie zdefiniowane.

Poniższy przykład pokazuje, jak można ustawić przyłą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 języka XAML, jeśli myCheckBox nie został jeszcze dodany jako element podrzędny myDockPanel przez czwarty wiersz kodu, piąty wiersz kodu nie zgłosi wyjątku, ale wartość właściwości nie będzie współdziałać z DockPanel elementem nadrzędnym i w rezultacie nic nie rób. Tylko DockPanel.Dock wartość ustawiona w elemencie podrzędnym, w połączeniu z obecność DockPanel elementu nadrzędnego, spowoduje efektywne zachowanie w renderowanej aplikacji. (W tym przypadku można ustawić przyłączoną właściwość, a następnie dołączyć do drzewa. Możesz też dołączyć do drzewa, a następnie ustawić przyłączoną właściwość. Każda kolejność akcji daje ten sam wynik.)

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

Podczas rejestrowania właściwości, FrameworkPropertyMetadata jest ustawione na określanie właściwości właściwości, na przykład czy właściwość wpływa na renderowanie, pomiar i tak dalej. Metadane dołączonej właściwości zwykle nie są inne niż w przypadku właściwości zależności. Jeśli określisz wartość domyślną w metadanych przesłonięcia do dołączonej właściwości, ta wartość będzie wartością domyślną niejawnej dołączonej właściwości w wystąpieniach klasy zastępującej. W zależności od tego wartość domyślna jest raportowana, jeśli niektóre zapytania procesu dla wartości właściwości dołączonej przez Get metodę dostępu metody dla tej właściwości określają wystąpienie klasy, w której określono metadane, a wartość tej dołączonej właściwości nie została ustawiona.

Aby włączyć dziedziczenie wartości właściwości dla właściwości, należy użyć dołączonych właściwości, a nie niedołą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 należy utworzyć dołączoną Właściwość

Można utworzyć przyłączoną właściwość, gdy istnieje powód, dla którego jest dostępny mechanizm ustawienia właściwości dla klas innych niż Klasa definiująca. Najbardziej typowym scenariuszem tego jest układ. Przykłady istniejących właściwości układu to DockPanel.Dock , Panel.ZIndex , i Canvas.Top . Scenariusz włączony tutaj polega na tym, że elementy, które istnieją jako elementy podrzędne do układu sterujące elementy, są w stanie wyznaczać wymagania układu dla elementów nadrzędnych układu osobno, każde ustawienie wartości właściwości, która została zdefiniowana jako dołączona właściwość.

Innym scenariuszem korzystania z dołączonej właściwości jest to, że Klasa reprezentuje usługę, i chcesz, aby klasy mogły zintegrować usługę w sposób bardziej niewidoczny.

Jeszcze innym scenariuszem jest otrzymanie obsługi projektanta Visual Studio WPF, takich jak edytowanie okna Właściwości . Aby uzyskać więcej informacji, zobacz temat Tworzenie kontroli — przegląd.

Jak wspomniano wcześniej, należy zarejestrować się jako właściwość dołączona, 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ść wyłącznie do użycia w innych typach, Klasa nie musi dziedziczyć od DependencyObject . Jednak należy utworzyć wynik z DependencyObject , jeśli spełniasz ogólny model WPF, że dołączona właściwość również jest właściwością zależności.

Zdefiniuj załączoną właściwość jako właściwość zależności przez zadeklarowanie public static readonly pola typu DependencyProperty . To pole jest definiowane przy użyciu wartości zwracanej przez RegisterAttached metodę. Nazwa pola musi być zgodna z nazwą dołączonej właściwości, dołączoną do ciągu Property , aby postępować zgodnie z ustalonym wzorcem WPF określającym nazwy pól identyfikujących i właściwości, które reprezentują. Dostawca dołączonej właściwości musi również dostarczyć static Get * PropertyName* i Set * PropertyName* metody jako metod dostępu dla dołączonej właściwości; nie można wykonać tych rezultatów, ponieważ system właściwości nie może użyć dołączonej właściwości.

Uwaga

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

Metoda dostępu get

Sygnatura metody dostępu Get * PropertyName* musi być:

public static object GetPropertyName(object target)

  • targetObiekt może być określony jako bardziej konkretny typ w implementacji. Na przykład Metoda określa DockPanel.GetDock parametr jako UIElement , ponieważ dołączona właściwość jest przeznaczona tylko do ustawiania w UIElement wystąpieniach.

  • Wartość zwracana może być określona jako bardziej konkretny typ w implementacji. Na przykład Metoda ta jest GetDock Dock określana jako, ponieważ wartość może być ustawiona tylko na to wyliczenie.

Metoda dostępu set

Sygnaturą metody dostępu Set * PropertyName* musi być:

public static void SetPropertyName(object target, object value)

  • targetObiekt może być określony jako bardziej konkretny typ w implementacji. Na przykład Metoda ta SetDock UIElement jest typu, ponieważ dołączona właściwość jest przeznaczona tylko do ustawiania w UIElement wystąpieniach.

  • valueObiekt może być określony jako bardziej konkretny typ w implementacji. Na przykład Metoda ta jest SetDock Dock określana jako, ponieważ wartość może być ustawiona tylko na to wyliczenie. Należy pamiętać, że wartość tej metody jest wartością wejściową pochodzącą z modułu ładującego XAML podczas napotkania dołączonej właściwości we właściwości użycie dołączonej w znaczniku. To dane wejściowe to wartość określona jako wartość atrybutu XAML w znaczniku. W związku z tym, należy dokonać konwersji typu, serializatora wartości lub rozszerzenia znacznika dla używanego typu, aby można było utworzyć odpowiedni typ na podstawie wartości atrybutu (która jest ostatecznie tylko ciągiem).

Poniższy przykład przedstawia rejestrację właściwości zależności (przy użyciu RegisterAttached metody), a także metod dostępu Get * PropertyName* i Set * PropertyName*. W przykładzie nazwa dołączonej właściwości to IsBubbleSource . W związku z tym, metody dostępu muszą mieć nazwę 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 są przeznaczone do przekazywania informacji o właściwościach dołączonych do procesów odbicia, oraz do typowych użytkowników odbicia i informacji o właściwościach, takich jak projektanci. Ponieważ dołączone właściwości mają typ nieograniczonego zakresu, projektanci muszą mieć możliwość uniknięcia przeciążania użytkowników z globalną listą wszystkich dołączonych właściwości, które są zdefiniowane w określonej implementacji technologicznej, która używa języka XAML. Atrybuty .NET, które program WPF definiuje 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żna rozważyć zastosowanie tych atrybutów do własnych niestandardowych właściwości dołączanych. Zastosowanie i składnia atrybutów .NET jest opisana na odpowiednich stronach odniesienia:

Dowiedz się więcej na temat dołączonych właściwości

  • 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 dla 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 właściwość dołączoną, a jako właściwość zależności, a następnie nadal ujawniać implementacje "otoka". W takim przypadku Właściwość można ustawić na tym elemencie lub w dowolnym elemencie za pomocą składni właściwości dołączonej XAML. Przykładem właściwości z odpowiednim scenariuszem dla standardowych i dołączonych użycia jest FrameworkElement.FlowDirection .

Zobacz też