Přehled připojených vlastností (WPF .NET)

Článek
10/18/2023

Připojená vlastnost je koncept jazyka XAML (Extensible Application Markup Language). Připojené vlastnosti umožňují nastavit extra páry property/value u libovolného elementu XAML, který je odvozen z DependencyObject, i když prvek nedefinuje tyto dodatečné vlastnosti ve svém objektovém modelu. Další vlastnosti jsou globálně přístupné. Připojené vlastnosti jsou obvykle definovány jako specializovaná forma vlastnosti závislosti, která nemá konvenční obálku vlastností.

Důležité

Dokumentace k desktopové příručce pro .NET 7 a .NET 6 se právě připravuje.

Předpoklady

V článku se předpokládá základní znalost vlastností závislostí a že jste si přečetli přehled vlastností závislostí. Pokud chcete postupovat podle příkladů v tomto článku, pomůže vám to, pokud znáte XAML a víte, jak psát aplikace Windows Presentation Foundation (WPF).

Proč používat připojené vlastnosti

Připojená vlastnost umožňuje podřízené element určit jedinečnou hodnotu vlastnosti, která je definována v nadřazeném elementu. Běžným scénářem je podřízený prvek určující, jak se má vykreslit v uživatelském rozhraní nadřazeným prvkem. Je to například připojená vlastnost, DockPanel.Dock protože je nastavena na podřízené prvky objektu , DockPanelnikoli DockPanel samotné. Třída DockPanel definuje statické DependencyProperty pole s názvem DockPropertya poté poskytuje GetDock a SetDock metody jako veřejné přístupové objekty pro připojenou vlastnost.

Připojené vlastnosti v XAML

V JAZYCE XAML nastavíte připojené vlastnosti pomocí syntaxe <attached property provider type>.<property name>, kde připojený zprostředkovatel vlastností je třída, která definuje připojenou vlastnost. Následující příklad ukazuje, jak podřízený prvek DockPanel může nastavit DockPanel.Dock hodnotu vlastnosti.

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

Použití je podobné statické vlastnosti, ve které odkazujete na typ, který vlastní a registruje připojenou vlastnost (například DockPanel), nikoli název instance.

Když zadáte připojenou vlastnost pomocí atributu XAML, je použitelná pouze nastavená akce. Hodnotu vlastnosti nelze přímo získat prostřednictvím XAML, i když existují některé nepřímé mechanismy pro porovnávání hodnot, jako jsou triggery ve stylech.

Připojené vlastnosti ve WPF

Připojené vlastnosti jsou koncept XAML, vlastnosti závislostí jsou konceptEM WPF. Ve WPF se většina připojených vlastností uživatelského rozhraní u typů WPF implementuje jako vlastnosti závislosti. Připojené vlastnosti WPF implementované jako vlastnosti závislosti podporují koncepty vlastností závislostí, jako jsou metadata vlastností včetně výchozích hodnot z metadat.

Modely využití připojených vlastností

I když jakýkoli objekt může nastavit připojenou hodnotu vlastnosti, neznamená to, že nastavení hodnoty vytvoří hmatatelný výsledek nebo hodnota bude použita jiným objektem. Hlavním účelem připojených vlastností je poskytnout způsob, jak pro objekty z široké škály hierarchií tříd a logických relací hlásit běžné informace typu, který definuje připojenou vlastnost. Využití připojených vlastností se obvykle řídí jedním z těchto modelů:

Typ, který definuje připojenou vlastnost je nadřazený elementy, které nastavují hodnoty pro připojenou vlastnost. Nadřazený typ iteruje své podřízené objekty interní logikou, která funguje na struktuře stromu objektů, získá hodnoty a působí na tyto hodnoty nějakým způsobem.
Typ, který definuje připojenou vlastnost, se používá jako podřízený prvek pro různé možné nadřazené elementy a con režim stanu ls.
Typ, který definuje připojenou vlastnost představuje službu. Jiné typy nastavují hodnoty pro připojenou vlastnost. Poté, když prvek, který nastaví vlastnost je vyhodnocen v kontextu služby, připojené hodnoty vlastnosti jsou získány prostřednictvím interní logiky třídy služby.

Příklad připojené vlastnosti definované nadřazeným objektem

Typický scénář, kdy WPF definuje připojenou vlastnost je, když nadřazený prvek podporuje podřízenou kolekci elementů a nadřazený prvek implementuje chování na základě dat hlášených jednotlivými jeho podřízenými prvky.

DockPanel definuje připojenou DockPanel.Dock vlastnost. DockPanelmá kód na úrovni třídy, konkrétně a ArrangeOverride, který je součástí své logiky MeasureOverride vykreslování. Instance DockPanel zkontroluje, zda některé z jeho bezprostředních podřízených prvků nastavily hodnotu pro DockPanel.Dock. Pokud ano, tyto hodnoty se stanou vstupy do logiky vykreslování použité pro každý podřízený prvek. I když je teoreticky možné, aby připojené vlastnosti ovlivnily prvky nad rámec bezprostředního nadřazeného objektu, definované chování vnořené DockPanel instance je pouze interakci s okamžitou podřízenou kolekcí elementů. Pokud tedy nastavíte DockPanel.Dock prvek, který nemá nadřazený DockPanel prvek, nebude vyvolána žádná chyba nebo výjimka a vytvořili byste globální hodnotu vlastnosti, která nebude spotřebována žádným DockPanel.

Připojené vlastnosti v kódu

Připojené vlastnosti ve WPF nemají typické metody CLR get a set obálky, protože vlastnosti mohou být nastaveny mimo obor názvů CLR. Aby procesor XAML nastavil tyto hodnoty při analýze XAML, třída, která definuje připojenou vlastnost, musí implementovat vyhrazené metody přístupového objektu ve formě Get<property name> a Set<property name>.

K získání a nastavení připojené vlastnosti v kódu můžete použít také vyhrazené metody přístupového objektu, jak je znázorněno v následujícím příkladu. V tomto příkladu myTextBox je instance TextBox třídy.

DockPanel myDockPanel = new();
TextBox myTextBox = new();
myTextBox.Text = "Enter text";

// Add child element to the DockPanel.
myDockPanel.Children.Add(myTextBox);

// Set the attached property value.
DockPanel.SetDock(myTextBox, Dock.Top);

Dim myDockPanel As DockPanel = New DockPanel()
Dim myTextBox As TextBox = New TextBox()
myTextBox.Text = "Enter text"

' Add child element to the DockPanel.
myDockPanel.Children.Add(myTextBox)

' Set the attached property value.
DockPanel.SetDock(myTextBox, Dock.Top)

Pokud nepřidáte myTextBox jako podřízený prvek myDockPanel, volání SetDock nevyvolá výjimku nebo nebude mít žádný účinek. Vykreslení může ovlivnit pouze hodnota nastavená DockPanel.Dock na podřízený prvek DockPanel a vykreslování bude stejné, zda nastavíte hodnotu před nebo po přidání podřízeného prvku do objektu DockPanel.

Z pohledu kódu je připojená vlastnost jako záložní pole, které má přístupové objekty metody místo přístupových objektů vlastností, a lze je nastavit u libovolného objektu, aniž by bylo nutné nejprve definovat na těchto objektech.

Metadata připojených vlastností

Metadata připojené vlastnosti se obecně neliší od vlastnosti závislosti. Při registraci připojené vlastnosti použijte FrameworkPropertyMetadata k určení charakteristik vlastnosti, jako je například to, zda vlastnost ovlivňuje vykreslování nebo měření. Když zadáte výchozí hodnotu přepsáním metadat připojených vlastností, tato hodnota se stane výchozí pro implicitní připojenou vlastnost u instancí přepsání třídy. Pokud připojená hodnota vlastnosti není jinak nastavena, je výchozí hodnota hlášena při dotazování vlastnosti pomocí přístupového Get<property name> objektu s instancí třídy, ve které jste zadali metadata.

Chcete-li povolit dědičnost hodnot vlastností u vlastnosti, použijte připojené vlastnosti místo vlastností závislosti, které nejsou připojené. Další informace naleznete v tématu Dědičnost hodnot vlastností.

Vlastní připojené vlastnosti

Kdy vytvořit připojenou vlastnost

Vytvoření připojené vlastnosti je užitečné v následujících případech:

Potřebujete mechanismus nastavení vlastností, který je k dispozici pro jiné třídy, než je definice třídy. Běžným scénářem je například rozložení DockPanel.Dockuživatelského rozhraní , Panel.ZIndexa Canvas.Top jsou to všechny příklady existujících vlastností rozložení. Ve scénáři rozložení můžou podřízené prvky elementu řízení rozložení vyjádřit požadavky rozložení na nadřazené rozložení a nastavit hodnotu pro připojenou vlastnost definovanou nadřazenou položkou.
Jedna z vašich tříd představuje službu a chcete, aby ostatní třídy integrovali službu transparentněji.
Chcete, aby návrhář WPF sady Visual Studio podporoval, například možnost upravit vlastnost prostřednictvím okna Vlastnosti . Další informace najdete v tématu Přehled vytváření obsahu ovládacích prvků.
Chcete použít dědičnost hodnot vlastností.

Vytvoření připojené vlastnosti

Pokud vaše třída definuje připojenou vlastnost výhradně pro použití jinými typy, pak vaše třída nemusí odvozovat .DependencyObject V opačném případě postupujte podle modelu WPF mít připojenou vlastnost také závislost vlastnost odvozením třídy z DependencyObject.

Definujte připojenou vlastnost jako závislost v definování třídy deklarováním public static readonly pole typu DependencyProperty. Pak přiřaďte návratové RegisterAttached hodnoty metody do pole, které se také označuje jako identifikátor vlastnosti závislosti. Postupujte podle konvence pojmenování vlastností WPF, které rozlišují pole od vlastností, které představují, pojmenováním pole <property name>Propertyidentifikátoru . Také poskytněte statické Get<property name> a Set<property name> přístupové metody, které umožňují systému vlastností přistupovat k připojené vlastnosti.

Následující příklad ukazuje, jak zaregistrovat vlastnost závislosti pomocí RegisterAttached metody a jak definovat metody přístupového objektu. V příkladu je název připojené vlastnosti HasFish, takže pole identifikátoru je pojmenováno HasFishPropertya metody přístupového objektu jsou pojmenovány GetHasFish a SetHasFish.

public class Aquarium : UIElement
{
    // Register an attached dependency property with the specified
    // property name, property type, owner type, and property metadata.
    public static readonly DependencyProperty HasFishProperty = 
        DependencyProperty.RegisterAttached(
      "HasFish",
      typeof(bool),
      typeof(Aquarium),
      new FrameworkPropertyMetadata(defaultValue: false,
          flags: FrameworkPropertyMetadataOptions.AffectsRender)
    );

    // Declare a get accessor method.
    public static bool GetHasFish(UIElement target) =>
        (bool)target.GetValue(HasFishProperty);

    // Declare a set accessor method.
    public static void SetHasFish(UIElement target, bool value) =>
        target.SetValue(HasFishProperty, value);
}

Public Class Aquarium
    Inherits UIElement

    ' Register an attached dependency property with the specified
    ' property name, property type, owner type, and property metadata.
    Public Shared ReadOnly HasFishProperty As DependencyProperty =
        DependencyProperty.RegisterAttached("HasFish", GetType(Boolean), GetType(Aquarium),
            New FrameworkPropertyMetadata(defaultValue:=False,
                flags:=FrameworkPropertyMetadataOptions.AffectsRender))

    ' Declare a get accessor method.
    Public Shared Function GetHasFish(target As UIElement) As Boolean
        Return target.GetValue(HasFishProperty)
    End Function

    ' Declare a set accessor method.
    Public Shared Sub SetHasFish(target As UIElement, value As Boolean)
        target.SetValue(HasFishProperty, value)
    End Sub

End Class

Přístupové objekty Get

Podpis get metody přístupového objektu je public static object Get<property name>(DependencyObject target), kde:

target je vlastnost DependencyObject , ze které se připojená vlastnost čte. Typ target může být konkrétnější než DependencyObject. Například metoda přístupového DockPanel.GetDock objektu target zadá jako UIElement , protože připojená vlastnost je určena k nastavení na UIElement instancích. UiElement nepřímo vychází z DependencyObject.
Návratový typ může být konkrétnější než object. Například metoda zadá vrácenou hodnotu jakoDock, GetDock protože návratová hodnota by měla být Dock výčet.

Poznámka:

Přístup get k připojené vlastnosti je vyžadován pro podporu datových vazeb v nástrojích pro návrh, jako je Visual Studio nebo Blend pro Visual Studio.

Nastavení přístupového objektu

Podpis set metody přístupového objektu je public static void Set<property name>(DependencyObject target, object value), kde:

target je vlastnost DependencyObject , na které je připojena vlastnost zapsána. Typ target může být konkrétnější než DependencyObject. Například metoda zadá target jakoUIElement, SetDock protože připojená vlastnost je určena k nastavení na UIElement instancích. UiElement nepřímo vychází z DependencyObject.
Typ value může být konkrétnější než object. Například SetDock metoda vyžaduje Dock hodnotu. Zavaděč XAML musí být schopen vygenerovat value typ z řetězce značek, který představuje připojenou hodnotu vlastnosti. Proto musí existovat podpora převodu typu, serializátoru hodnot nebo rozšíření značek pro typ, který používáte.

Atributy připojené vlastnosti

WPF definuje několik atributů .NET, které poskytují informace o připojených vlastnostech k procesům reflexe a také spotřebitelům reflexe a informací o vlastnostech, jako jsou návrháři. Návrháři používají atributy .NET definované wpf k omezení vlastností zobrazených v okně vlastností, aby se zabránilo zahlcení uživatelů globálním seznamem všech připojených vlastností. Můžete zvážit použití těchto atributů na vlastní připojené vlastnosti. Účel a syntaxe atributů .NET je popsána na těchto referenčních stránkách:

Další informace

Další informace o vytvoření připojené vlastnosti naleznete v tématu Registrace připojené vlastnosti.
Pokročilejší scénáře použití vlastností závislostí a připojených vlastností najdete v tématu Vlastní vlastnosti závislostí.
Vlastnost můžete zaregistrovat jako připojenou vlastnost i vlastnost závislosti a zahrnout běžné obálky vlastností. Tímto způsobem lze vlastnost nastavit u elementu pomocí obálky vlastností a také na jakýkoli jiný prvek pomocí syntaxe připojené vlastnosti XAML. Příklad naleznete v tématu FrameworkElement.FlowDirection.