Ekli özelliklere genel bakış

2025-05-07

Ekli özellik, Genişletilebilir Uygulama biçimlendirme dili (XAML) kavramıdır. Ekli özellikler, öğesi nesne modelinde bu ek özellikleri tanımlamasa bile, öğesinden DependencyObjecttüretilen herhangi bir XAML öğesinde ek özellik/değer çiftlerinin ayarlanmasını sağlar. Ek özelliklere genel olarak erişilebilir. Ekli özellikler genellikle geleneksel özellik sarmalayıcıya sahip olmayan özel bir bağımlılık özelliği biçimi olarak tanımlanır.

Önkoşullar

Bağımlılık özellikleri hakkında temel bilgilere sahip olduğunuz ve Bağımlılık Özelliklerine Genel Bakış'ı okuduğunuz varsayılmaktadır. Bu makaledeki örnekleri takip etmek için, XAML hakkında bilgi sahibi olmanız ve Windows Presentation Foundation (WPF) uygulamalarının nasıl yazabileceğinizi bilmeniz yardımcı olur.

Ekli özellikleri neden kullanmalısınız?

Ekli özellik, alt öğenin üst öğede tanımlanan bir özellik için benzersiz bir değer belirtmesini sağlar. Yaygın bir senaryo, kullanıcı arabiriminde ebeveyn öğesi tarafından nasıl görüntüleneceğini belirten bir alt öğedir. Örneğin, DockPanel.Dock bir ekli özelliktir çünkü DockPanel'nin kendisinde değil, DockPanel alt öğelerinde ayarlanmıştır. DockPanel sınıfı, DependencyProperty adlı statik DockProperty alan tanımlar ve ardından iliştirilen özellik için genel erişimciler olarak GetDock ve SetDock yöntemlerini sağlar.

XAML'de ekli özellikler

XAML'de, ekli özellik sağlayıcısının ekli özelliği tanımlayan sınıf olduğu söz dizimini <attached property provider type>.<property name>kullanarak ekli özellikleri ayarlarsınız. Aşağıdaki örnek, bir DockPanel alt öğesinin DockPanel.Dock özellik değerini nasıl ayarlayabildiğini gösterir.

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

Kullanım, ekli özelliğe (örneğin, DockPanel) sahip olan ve kaydeden türü değil, örnek adını referans aldığınız statik özelliğe benzer.

XAML özniteliğini kullanarak ekli bir özellik belirttiğinizde, yalnızca küme eylemi uygulanabilir. Stillerdeki tetikleyiciler gibi değerleri karşılaştırmaya yönelik bazı dolaylı mekanizmalar olsa da, XAML aracılığıyla bir özellik değerini doğrudan alamazsınız.

WPF'de ekli özellikler

Ekli özellikler bir XAML kavramıdır, bağımlılık özellikleri bir WPF kavramıdır. WPF'de, WPF türlerindeki kullanıcı arabirimiyle ilgili ekli özelliklerin çoğu bağımlılık özellikleri olarak uygulanır. Bağımlılık özellikleri olarak uygulanan WPF bağlı özellikler, bağımlılık özelliği kavramlarını destekler; bu kavramlara, meta veriler aracılığıyla sağlanan varsayılan değerler gibi özellik meta verileri de dahildir.

İliştirilmiş mülk kullanım modelleri

Herhangi bir nesne ekli bir özellik değeri ayarlayabilir, ancak bu değer ayarlamanın somut bir sonuç oluşturacağı veya değerin başka bir nesne tarafından kullanılacağı anlamına gelmez. Ekli özelliklerin temel amacı, çok çeşitli sınıf hiyerarşilerinden ve mantıksal ilişkilerden nesnelere, ortak bilgileri ekli özelliği tanımlayan türe raporlamak için bir yol sağlamaktır. Ekli özellik kullanımı genellikle şu modellerden birini izler:

Ekli özelliği tanımlayan tür, ekli özellik için değerleri ayarlayan öğelerin üst öğesidir. Ana tür, nesne ağacı yapısı üzerinde etkili olan iç mantık aracılığıyla alt nesnelerini yineleyerek, değerleri elde eder ve bu değerlere bir şekilde etki eder.
Ekli özelliği tanımlayan tür, çeşitli olası üst öğeler ve içerik modelleri için alt öğe olarak kullanılır.
Bağlı özelliği tanımlayan tür, bir hizmeti temsil eder. Diğer türler, ekli özellik için değerleri ayarlar. Ardından, özelliği ayarlayan öğe hizmet bağlamında değerlendirildiğinde, ekli özellik değerleri hizmet sınıfının iç mantığı aracılığıyla elde edilir.

Ebeveyn tarafından tanımlanan ekli özellik örneği

WPF'nin bağlı bir özelliği tanımladığı tipik senaryo, bir üst öğenin alt öğe koleksiyonunu desteklediği ve üst öğenin alt öğelerinin her biri tarafından sağlanan verilere dayanarak bir davranış sergilediği durumdur.

DockPanel DockPanel.Dock ekli özelliği tanımlar. DockPanel özellikle MeasureOverride ve ArrangeOverridesınıf düzeyinde koda sahiptir. Bu, işleme mantığının bir parçasıdır. Örnek, DockPanel anlık alt öğelerinden herhangi birinin için DockPanel.Dockbir değer ayarlayıp ayarlamadığını denetler. Öyleyse, bu değerler her alt öğeye uygulanan işleme mantığının girdileri haline gelir. Ekli özelliklerin, doğrudan üst öğenin ötesindeki öğeleri etkilemesi teorik olarak mümkün olsa da, iç içe DockPanel örneğinin tanımlı davranışı sadece doğrudan alt öğe koleksiyonuyla etkileşim halinde olmaktır. Bu nedenle, eğer bir üst öğeye sahip olmayan bir element üzerinde DockPanel.Dock ayarlarsanız, hiçbir hata veya özel durum oluşmaz ve DockPanel tarafından tüketilmeyecek bir genel özellik değeri oluşturmuş olursunuz.

Koda eklenen özellikler

ÖZELLIKLER CLR get ad alanının dışından ayarlanabileceği için WPF'deki ekli özellikler tipik CLR ve set sarmalayıcı yöntemlerine sahip değildir. Bir XAML işlemcisinin XAML ayrıştırırken bu değerleri ayarlamasına izin vermek için, ekli özelliği tanımlayan sınıfın Get<property name> ve Set<property name> biçiminde özel erişimci yöntemler uygulaması gerekir.

Aşağıdaki örnekte gösterildiği gibi kodda ekli bir özellik almak ve ayarlamak için ayrılmış erişimci yöntemlerini de kullanabilirsiniz. Örnekte, myTextBox sınıfının bir örneğidir 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)

öğesinin alt öğesi myTextBoxolarak eklemezsenizmyDockPanel, çağrısı SetDock özel durum oluşturmaz veya herhangi bir etkisi olmaz. Yalnızca bir alt öğesinde ayarlanan bir DockPanel.Dock değer işlemeyi DockPanel etkileyebilir ve alt öğeyi öğesine eklemeden önce veya ekledikten sonra değeri ayarlamanız fark etmeksizin işleme aynı DockPanelolacaktır.

Kod açısından bakıldığında, ekli özellik, özellik erişimcileri yerine yöntem erişimcilerine sahip olan ve önce bu nesneler üzerinde tanımlanması gerekmeden herhangi bir nesne üzerinde ayarlanabilen bir yedekleme alanı gibidir.

Eklenen özellik meta verileri

Ekli bir özelliğin meta verileri genellikle bağımlılık özelliğinden farklı değildir. Ekli bir özelliği kaydederken, işlemenin veya ölçümün etkileyip etkilemediği gibi özelliklerini belirtmek için FrameworkPropertyMetadata kullanın. Ekli özellik meta verilerini geçersiz kılarak varsayılan bir değer belirttiğinizde, bu değer geçersiz kılma sınıfının örneklerinde örtük ekli özellik için varsayılan değer olur. Ekli özellik değeri aksi takdirde ayarlanmamışsa, meta verileri belirttiğiniz sınıfın bir örneğiyle erişimci kullanılarak Get<property name> özellik sorgulandığında varsayılan değer bildirilir.

Özellik değeri devralmayı etkinleştirmek için, ekli olmayan bağımlılık özellikleri yerine ek özellikleri kullanın. Daha fazla bilgi için bkz. Özellik değeri kalıtımı.

Ekli özel özellikler

Ekli özelliği ne zaman oluşturmalı?

Ekli özellik oluşturmak aşağıdaki durumlarda kullanışlıdır:

Tanımlama sınıfı dışındaki sınıfların kullanabileceği bir özellik ayarı mekanizmasına ihtiyacınız vardır. Yaygın bir senaryo, kullanıcı arabirimi düzenine yöneliktir; örneğin DockPanel.Dock, Panel.ZIndexve Canvas.Top tüm örnekler, var olan düzen özelliklerine örnektir. Düzen senaryosunda, düzen denetimi öğesinin alt öğeleri düzen gereksinimlerini düzen üst öğelerine ifade eder ve üst öğe tarafından tanımlanan ekli özellik için bir değer ayarlayabilir.
Sınıflarınızdan biri bir hizmeti temsil eder ve diğer sınıfların hizmeti daha şeffaf bir şekilde tümleştirmesini istiyorsunuz.
Özellikler penceresi aracılığıyla bir özelliği düzenleme özelliği gibi Visual Studio WPF Tasarımcısı desteği istiyorsunuz. Daha fazla bilgi için bkz. Denetim yazmaya genel bakış
Özellik değeri devralmayı kullanmak istiyorsunuz.

Ekli özellik oluşturma

Eğer sınıfınız, ekli bir özelliği yalnızca diğer türler tarafından kullanılmak üzere tanımlıyorsa, sınıfınızın DependencyObject ile türetilmesi gerekmez. Aksi takdirde, sınıfınızı DependencyObject'dan türeterek, ekli bir özelliği aynı zamanda bir bağımlılık özelliği olarak kullanma modelini izleyen WPF modelini takip edin.

türünde public static readonlybir alan bildirerek ekli özelliğinizi tanımlama sınıfında bağımlılık DependencyProperty olarak tanımlayın. Ardından, yönteminin RegisterAttached dönüş değerini bağımlılık özelliği tanımlayıcısı olarak da bilinen alana atayın. Tanımlayıcı alanını <property name>Propertyadlandırarak alanları temsil ettikleri özelliklerden ayıran WPF özellik adlandırma kuralını izleyin. Ayrıca, özellik sisteminin bağlı özelliğinize erişmesini sağlayan statik Get<property name> ve Set<property name> erişim yöntemlerini sağlayın.

Aşağıdaki örnekte, RegisterAttached yöntemini kullanarak bir bağımlılık özelliğinin nasıl kaydedileceği ve erişimci yöntemlerinin nasıl tanımlanacağı gösterilmektedir. Örnekte, ekli özelliğin adı HasFish olduğu için tanımlayıcı alan HasFishProperty olarak, erişimci yöntemler ise GetHasFish ve SetHasFish olarak adlandırılır.

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

Get erişim metodu

Erişimci get yöntemi imzası şu şekildedir public static object Get<property name>(DependencyObject target):

target DependencyObject ekli özelliğin okunduğu yerdir. Tip targetDependencyObject tipinden daha belirgin olabilir. Erişimci DockPanel.GetDock yöntemi, ekli özelliğin target örneklerinde ayarlanması amaçlandığından, UIElement'i UIElement olarak türlendirir. UiElement, DependencyObject’den dolaylı olarak türetilir.
Dönüş türü, object değerinden daha özel olabilir. Örneğin, dönüş değeri bir GetDock numaralandırma olmalıdır çünkü Dock yöntemi döndürülen değeri Dock olarak yazıyor.

Uyarı

get Ekli bir özelliğin erişimcisi, Visual Studio veya Visual Studio için Blend gibi tasarım araçlarında veri bağlama desteği sağlamak için gereklidir.

Set erişimcisi

Erişimci set yöntemi imzası şu şekildedir public static void Set<property name>(DependencyObject target, object value):

target DependencyObject, ekli özelliğin yazıldığı yerdir. Tip targetDependencyObject tipinden daha belirgin olabilir. Örneğin, SetDock yöntemi, ekli özelliğin target örneklerinde ayarlanması amaçlandığından, UIElement öğesini UIElement olarak sınıflandırır. UiElement, DependencyObject’den dolaylı olarak türetilir.
Tip valueobject tipinden daha belirgin olabilir. Örneğin, SetDock yöntemi bir Dock değer gerektirir. XAML yükleyicisinin value , ekli özellik değerini temsil eden işaretleme dizesinden türü oluşturabilmesi gerekir. Bu nedenle, kullandığınız tür için tür dönüştürme, değer serileştiricisi veya işaretleme uzantısı desteği olmalıdır.

İliştirilmiş özellik öznitelikleri

WPF, yansıma işlemlerine ve ayrıca tasarımcılar gibi yansıma ve özellik bilgilerinin tüketicilerine eklenen özellikler hakkında bilgi sağlayan çeşitli .NET özniteliklerini tanımlar. Tasarımcılar, kullanıcıları tüm ekli özelliklerin genel bir listesi ile aşırı yükleyip zorlamamak için özellikler penceresinde gösterilen özellikleri sınırlamak amacıyla WPF tarafından tanımlanan .NET özniteliklerini kullanır. Bu öznitelikleri kendi özel ekli özelliklerinize uygulamayı düşünebilirsiniz. .NET özniteliklerinin amacı ve söz dizimi şu başvuru sayfalarında açıklanmıştır:

Daha fazla bilgi edinin

Ekli özellik oluşturma hakkında daha fazla bilgi için bkz . Ekli özelliği kaydetme.
Bağımlılık özellikleri ve ekli özellikler için daha gelişmiş kullanım senaryoları için bkz. Özel bağımlılık özellikleri.
Bir özelliği hem ekli özellik hem de bağımlılık özelliği olarak kaydedebilir ve özellik sarmalayıcılarını geleneksel şekilde ekleyebilirsiniz. Bu şekilde, özellik, özellik sarmalayıcıları kullanılarak bir öğede ve ayrıca XAML ekli özellik söz dizimi kullanılarak diğer herhangi bir öğede ayarlanabilir. Bir örnek için bkz. FrameworkElement.FlowDirection.