Csatolt tulajdonságok áttekintése

2025-05-07

A csatolt tulajdonság egy XAML(Extensible Application Markup Language, XAML) fogalom. A csatolt tulajdonságok lehetővé teszik a további tulajdonság-/érték párok beállítását minden olyan XAML-elemen, amely DependencyObjectszármazik, annak ellenére, hogy az elem nem definiálja ezeket az extra tulajdonságokat az objektummodellben. A további tulajdonságok globálisan elérhetők. A csatolt tulajdonságok általában olyan függőségi tulajdonság speciális formájaként vannak definiálva, amely nem rendelkezik hagyományos tulajdonságburkolóval.

Előfeltételek

A cikk feltételezi a függőségi tulajdonságok alapszintű ismeretét, és hogy elolvasta függőségi tulajdonságok áttekintését. A cikkben szereplő példák követéséhez segít, ha ismeri az XAML-t, és ismeri a Windows Presentation Foundation (WPF) alkalmazások írásának módját.

Miért érdemes csatolt tulajdonságokat használni?

A csatolt tulajdonság lehetővé teszi, hogy a gyermekelem egyedi értéket adjon meg egy szülőelemben definiált tulajdonsághoz. Gyakori forgatókönyv, hogy egy szülőelem határozza meg, hogyan jelenjen meg a gyermekelem a felhasználói felületen. A DockPanel.Dock például egy csatolt tulajdonság, mert egy DockPanelgyermekelemeire van beállítva, nem pedig magára a DockPanel. A DockPanel osztály egy DependencyPropertynevű statikus DockProperty mezőt határoz meg, majd GetDock és SetDock metódusokat biztosít a csatolt tulajdonság nyilvános tartozékaként.

Csatolt tulajdonságok az XAML-ben

Az XAML-ben a csatolt tulajdonságokat a <attached property provider type>.<property name>szintaxissal állíthatja be, ahol a csatolt tulajdonságszolgáltató a csatolt tulajdonságot meghatározó osztály. Az alábbi példa bemutatja, hogy a DockPanel gyermekeleme hogyan állíthatja be a DockPanel.Dock tulajdonság értékét.

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

A használat hasonlít egy statikus tulajdonságra abban, hogy a csatolt tulajdonságot birtokló és regisztráló típusra (például DockPanel) hivatkozik, nem pedig a példány nevére.

Ha egy csatolt tulajdonságot XAML-attribútummal ad meg, csak a beállított művelet alkalmazható. A tulajdonságértékeket nem lehet közvetlenül az XAML-ben lekérni, bár vannak közvetett mechanizmusok az értékek összehasonlítására, például stílusok eseményindítói.

Csatolt tulajdonságok a WPF-ben

A csatolt tulajdonságok egy XAML-fogalom, a függőségi tulajdonságok WPF-koncepciók. A WPF-ben a WPF-típusok legtöbb felhasználói felülettel kapcsolatos csatolt tulajdonsága függőségi tulajdonságként van implementálva. A függőségi tulajdonságokként implementált WPF-csatolt tulajdonságok támogatják a függőségi tulajdonság fogalmait, például a tulajdonság metaadatait, beleértve a metaadatok alapértelmezett értékeit.

Csatolt tulajdonsághasználati modellek

Bár bármely objektum beállíthat csatolt tulajdonságértéket, ez nem jelenti azt, hogy az érték beállítása kézzelfogható eredményt eredményez, vagy egy másik objektum fogja használni az értéket. A csatolt tulajdonságok fő célja, hogy módot biztosítson a különböző osztályhierarchiákból és logikai kapcsolatokból származó objektumok számára, hogy a közös információkat a csatolt tulajdonságot meghatározó típusnak jelentse. A csatolt tulajdonsághasználat általában az alábbi modellek egyikét követi:

A csatolt tulajdonságot meghatározó típus a csatolt tulajdonság értékeit beadó elemek szülője. A szülőtípus a gyermekobjektumokat belső logikával iterálja, amely az objektumfa szerkezetére hat, beolvasja az értékeket, és valamilyen módon hat ezekre az értékekre.
A csatolt tulajdonságot meghatározó típus gyermekelemként használható a különböző lehetséges szülőelemekhez és tartalommodellekhez.
A csatolt tulajdonságot meghatározó típus egy szolgáltatást jelöl. Más típusok a csatolt tulajdonság értékeit állítják be. Ezután, amikor a tulajdonságot meghatározó elem kiértékelése a szolgáltatás kontextusában történik, a csatolt tulajdonságértékek a szolgáltatásosztály belső logikájában lesznek lekérve.

Példa egy szülő által definiált csatolt tulajdonságra

Az a tipikus forgatókönyv, amikor a WPF egy csatolt tulajdonságot határoz meg, amikor egy szülőelem támogatja a gyermekelem-gyűjteményt, a szülőelem pedig az egyes gyermekelemek által jelentett adatokon alapuló viselkedést valósít meg.

DockPanel a csatolt DockPanel.Dock tulajdonságot határozza meg. DockPanel osztályszintű kóddal rendelkezik, különösen MeasureOverride és ArrangeOverride, ez a renderelési logika része. Egy DockPanel-példány ellenőrzi, hogy a közvetlen gyermekelem beállított-e bármilyen értéket a DockPanel.Dock-hez. Ha igen, ezek az értékek bemenetek lesznek az egyes gyermekelemekre alkalmazott renderelési logikához. Bár elméletileg lehetséges, hogy a csatolt tulajdonságok az elemeket a közvetlen szülőn túl is befolyásolják, a beágyazott DockPanel példányok meghatározott viselkedése az, hogy csak a közvetlen gyermekelemekkel lépnek kapcsolatba. Ha tehát DockPanel.Dock olyan elemre állít be, amely nem rendelkezik DockPanel szülővel, a rendszer nem fog hibát vagy kivételt eredményezni, és olyan globális tulajdonságértéket hoz létre, amelyet egyetlen DockPanelsem fog felhasználni.

Csatolt tulajdonságok a kódban

A WPF csatolt tulajdonságai nem rendelkeznek a clr-get és set burkoló metódusokkal, mert a tulajdonságok a CLR-névtéren kívülről állíthatók be. Annak érdekében, hogy egy XAML-processzor beállíthassa ezeket az értékeket az XAML elemzésekor, a csatolt tulajdonságot meghatározó osztálynak dedikált kiegészítő módszereket kell implementálnia Get<property name> és Set<property name>formájában.

A dedikált kiegészítő módszerek használatával is lekérhet és beállíthat egy csatolt tulajdonságot a kódban, ahogyan az az alábbi példában is látható. A példában a myTextBox a TextBox osztály egy példánya.

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)

Ha nem ad hozzá myTextBox a myDockPanelgyermekelemeként, a SetDock hívása nem okoz kivételt vagy semmilyen hatást. Csak egy DockPanel.Dock gyermekelemén beállított DockPanel érték befolyásolhatja a renderelést, és a renderelés ugyanaz lesz, ha a gyermekelem DockPanelhozzáadása előtt vagy után állítja be az értéket.

A kód szempontjából a csatolt tulajdonság olyan, mint egy háttérmező, amely metódus-tartozékokkal rendelkezik a tulajdonság tartozékai helyett, és bármely objektumon beállítható anélkül, hogy először definiálni kellene őket ezeken az objektumokon.

Csatolt tulajdonság metaadatai

A csatolt tulajdonságok metaadatai általában nem különböznek a függőségi tulajdonságtól. Csatolt tulajdonság regisztrálásakor a FrameworkPropertyMetadata használatával adja meg a tulajdonság jellemzőit, például azt, hogy a tulajdonság befolyásolja-e a renderelést vagy a mérést. Ha egy alapértelmezett értéket a csatolt tulajdonság metaadatainak felülírásával ad meg, az az érték lesz az implicit csatolt tulajdonság alapértelmezett értéke a felülíró osztály példányai esetében. Ha a csatolt tulajdonság értéke nincs másként beállítva, az alapértelmezett érték jelenik meg, amikor a tulajdonságot a Get<property name> hozzáférővel kérdezi le annak az osztálynak egy példányával, ahol megadta a metaadatokat.

A tulajdonság értéköröklésének engedélyezéséhez használjon csatolt tulajdonságokat a nem csatolt függőségi tulajdonságok helyett. További információ: Tulajdonságérték öröklése.

Egyéni csatolt tulajdonságok

Mikor érdemes csatolt tulajdonságot létrehozni?

Csatolt tulajdonság létrehozása akkor hasznos, ha:

A definiáló osztálytól eltérő osztályok számára elérhető tulajdonságbeállítási mechanizmusra van szükség. Gyakori forgatókönyv a felhasználói felület elrendezése, például a DockPanel.Dock, a Panel.ZIndexés a Canvas.Top mind a meglévő elrendezéstulajdonságok példái. Az elrendezési forgatókönyvben az elrendezés-vezérlő elemek gyermekelemei ki tudják fejezni az elrendezési követelményeket az elrendezés szülője számára, és beállíthatják a szülő által meghatározott csatolt tulajdonság értékét.
Az egyik osztály egy szolgáltatást jelöl, és azt szeretné, hogy más osztályok transzparensebben integrálják a szolgáltatást.
A Visual Studio WPF Designer támogatását szeretné, például egy tulajdonság szerkesztését a Tulajdonságok ablakban. További információ: A szerzői műveletek szabályozása – áttekintés
Tulajdonságérték-öröklést szeretne használni.

Csatolt tulajdonság létrehozása

Ha az osztály egy csatolt tulajdonságot határoz meg kizárólag más típusok általi használatra, akkor az osztálynak nem kell leszármaztatnia a DependencyObject-ből. Ellenkező esetben kövesse a WPF-modellt, amely szerint egy csatolt tulajdonság függőségi tulajdonságként is funkcionál, azáltal hogy az osztályt a DependencyObject-ből származtatja.

A csatolt tulajdonságot függőségként definiálhatja a definiáló osztályban egy public static readonly típusú mező DependencyPropertydeklarálásával. Ezután rendelje hozzá a RegisterAttached metódus visszatérési értékét a mezőhöz, amelyet függőségi tulajdonság azonosítójának is nevezünk,. Kövesse a WPF tulajdonságelnevezési konvenciót, amely megkülönbözteti a mezőket az általuk képviselt tulajdonságoktól az azonosító mező <property name>Propertyelnevezésével. Emellett statikus Get<property name> és Set<property name> kiegészítő módszereket is biztosít, amelyekkel a tulajdonságrendszer hozzáférhet a csatolt tulajdonsághoz.

Az alábbi példa bemutatja, hogyan regisztrálhat függőségi tulajdonságot a RegisterAttached metódussal, és hogyan határozhatja meg a kiegészítő metódusokat. A példában a csatolt tulajdonság neve HasFish, így az azonosító mező neve HasFishProperty, a kiegészítő metódusok neve pedig GetHasFish és 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

A Tartozék lekérése

A get kiegészítő metódus aláírása public static object Get<property name>(DependencyObject target), ahol:

target az a DependencyObject, amelyből a csatolt tulajdonság beolvasható. A target típus pontosabb lehet, mint DependencyObject. A DockPanel.GetDock kiegészítő metódus például a target-et UIElement típusra állítja be, mert a csatolt tulajdonságot UIElement példányokon kell alkalmazni. UiElement közvetetten a DependencyObjectszármazik.
A visszatérési típus pontosabb lehet, mint object. A GetDock metódus például Dock adja meg a visszaadott értéket, mert a visszatérési értéknek Dock enumerálásnak kell lennie.

Megjegyzés:

A csatolt tulajdonság get tartozéka szükséges az adatkötés támogatásához a tervezőeszközökben, például a Visual Studióban vagy a Blend for Visual Studióban.

A Tartozék beállítása

A set kiegészítő metódus aláírása public static void Set<property name>(DependencyObject target, object value), ahol:

target az a felület, amelyre a csatolt tulajdonság DependencyObject íródik. A target típus pontosabb lehet, mint DependencyObject. Például a SetDock metódus a target-t a UIElement-ként típusolja, mert a csatolt tulajdonságot UIElement példányokon kell beállítani. UiElement közvetetten a DependencyObjectszármazik.
A value típus pontosabb lehet, mint object. A SetDock metódushoz például Dock érték szükséges. Az XAML-betöltőnek képesnek kell lennie arra, hogy a csatolt tulajdonságértéket képviselő jelölő sztringből hozza létre a value típust. Ezért a használt típushoz típuskonverziónak, értékszerializálónak vagy korrektúrakiterjesztésnek kell lennie.

Csatolt tulajdonságattribútumok

A WPF számos .NET-attribútumot határoz meg, amelyek információt nyújtanak a tükröződési folyamatokhoz csatolt tulajdonságokról, valamint a tükröződés és a tulajdonságinformációk felhasználóinak, például a tervezőknek. A tervezők a WPF által definiált .NET-attribútumokkal korlátozzák a tulajdonságok ablakában látható tulajdonságokat, hogy ne terheljék túl a felhasználókat az összes csatolt tulajdonság globális listájával. Érdemes lehet ezeket az attribútumokat a saját egyéni csatolt tulajdonságaira alkalmazni. A .NET-attribútumok célját és szintaxisát az alábbi referenciaoldalak ismertetik:

Tudj meg többet

További információ a csatolt tulajdonság létrehozásáról: Csatolt tulajdonság regisztrálása.
A függőségi tulajdonságok és a csatolt tulajdonságok speciálisabb használati forgatókönyveit Egyéni függőségi tulajdonságokcímű témakörben talál.
Ön egy tulajdonságot regisztrálhat mind csatolt tulajdonságként, mind függőségi tulajdonságként, és hagyományos tulajdonságburkolókat is tartalmazhat. Ily módon egy tulajdonság beállítható tulajdonságburkolók alkalmazásával, és ugyanígy bármely más elemen az XAML csatolt tulajdonságok szintaxisának alkalmazásával. Példaként tekintse meg a FrameworkElement.FlowDirection-t.

Lásd még

DependencyProperty
Függőség tulajdonságainak áttekintése
egyéni függőségi tulajdonságok
XAML WPF-
Útmutató: Csatolt tulajdonság regisztrálása