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

Článek
11/05/2024

Připojená vlastnost je koncept jazyka XAML (Extensible Application Markup Language). Připojené vlastnosti umožňují nastavení párů extra property/value u libovolného elementu XAML odvozeného z DependencyObject, i když prvek nedefinuje tyto dodatečné vlastnosti v 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í.

Požadavky

Článek 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 dětskému prvku určit jedinečnou hodnotu vlastnosti, která je definována v rodičovském prvku. 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. Například DockPanel.Dock je připojená vlastnost, protože je nastavena na podřízené prvky objektu DockPanel, nikoliv na samotný objekt DockPanel. Třída DockPanel definuje statické pole DependencyProperty s názvem DockPropertya pak 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 je například trigger v rámci stylů.

Připojené vlastnosti ve WPF

Připojené vlastnosti jsou koncept XAML, vlastnosti závislostí jsou koncept 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ý prvkům, které nastavují hodnoty pro připojenou vlastnost. Nadřazený typ iteruje své podřízené objekty pomocí interní logiky, která pracuje s strukturou stromu objektů, získá hodnoty a nějakým způsobem s nimi nakládá.
Typ, který definuje připojenou vlastnost, se používá jako podřízený prvek pro různé možné nadřazené prvky a modely obsahu.
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 vlastnosti, kterou definuje nadřazený objekt

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 DockPanel.Dock připojenou vlastnost. DockPanel má kód na úrovni třídy, konkrétně MeasureOverride a ArrangeOverride, který je součástí logiky 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, stanovené chování vnořené instance DockPanel je interakce pouze s okamžitou podřízenou sbírkou elementů. Pokud tedy nastavíte DockPanel.Dock u elementu, který nemá žádnou DockPanel nadřazenou položku, 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 v WPF nemají typické obaly metod CLR get a set, protože vlastnosti mohou být nastaveny z jiného oboru názvů, než je CLR. Aby procesor XAML nastavil tyto hodnoty při analýze XAML, třída, která definuje připojenou vlastnost, musí implementovat vyhrazené metody přistupující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 je myTextBox instancí třídy TextBox.

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 myTextBox nepřidáte jako podřízený prvek myDockPanel, volání SetDock nevyvolá výjimku nebo nebude mít žádný účinek. Vykreslování může ovlivnit pouze hodnota DockPanel.Dock nastavená u podřízeného prvku DockPanel a vykreslování bude stejné, zda hodnotu nastavíte před nebo po přidání podřízeného prvku do DockPanel.

Z pohledu kódu je připojená vlastnost jako podpůrné pole, které používá metodové přístupy místo vlastnostních přístupů, a lze ji nastavit u libovolného objektu, aniž by bylo nutné nejprve ji 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řetěžující třídy. Pokud připojená hodnota vlastnosti není jinak nastavena, je výchozí hodnota hlášena při dotazování vlastnosti pomocí Get<property name> přístupového 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 nepřipojených závislostních vlastností. Další informace naleznete v tématu Dědičnost hodnoty vlastnosti.

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 rozložení uživatelského rozhraní, například DockPanel.Dock, Panel.ZIndexa Canvas.Top jsou 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í.

Jak vytvořit připojenou vlastnost

Pokud vaše třída definuje připojenou vlastnost výhradně pro použití jinými typy, pak vaše třída nemusí odvozovat z DependencyObject. Jinak postupujte podle modelu WPF, aby připojená vlastnost byla zároveň vlastností závislosti, tím že odvodíte svou třídu z DependencyObject.

Definujte připojenou vlastnost jako závislost v definující třídě deklarováním pole public static readonly typu DependencyProperty. Potom přiřaďte návratové hodnoty metody RegisterAttached k poli, které se také označuje jako identifikátor vlastnosti závislostí. Postupujte podle konvence pojmenování vlastností WPF, které rozlišují pole od vlastností, které představují, pojmenováním pole identifikátoru <property name>Property. Také poskytněte statické Get<property name> a Set<property name> metody přístupového objektu, 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 metoda a jak definovat metody přístupového objektu. V příkladu je název připojené vlastnosti HasFish, takže pole identifikátoru má název HasFishPropertya přístupové metody se nazývají 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 přístupové metody get je public static object Get<property name>(DependencyObject target), kde:

target je DependencyObject, ze které se čte připojená vlastnost. Typ target může být konkrétnější než DependencyObject. Například metoda přístupu DockPanel.GetDock určuje target jako UIElement, protože připojená vlastnost je určena k nastavení na instance UIElement. UiElement nepřímo pochází z DependencyObject.
Návratový typ může být konkrétnější než object. Například GetDock metoda přiřadí vrácené hodnotě typ Dock, protože návratová hodnota by měla být výčtový typ Dock.

Poznámka

Pro podporu datových vazeb v nástrojích pro návrh, jako je Visual Studio nebo Blend pro Visual Studio, je vyžadován přístupový objekt get pro připojenou vlastnost.

Nastavení přístupového objektu

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

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

Atributy připojených vlastností

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í zobrazených vlastností 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ů pro vaše vlastní připojené vlastnosti. Účel a syntaxe atributů .NET je popsána na těchto referenčních stránkách:

Víc se uč

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ávislosti.
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 FrameworkElement.FlowDirection.

Viz také

DependencyProperty
Přehled vlastností závislostí
vlastní závislostní vlastnosti
XAML v WPF
Jak na to: Registrace připojené vlastnosti

Sdílet prostřednictvím