Ekli özelliklere genel bakış (WPF .NET)

Makale
10/18/2023

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.

Önemli

.NET 7 ve .NET 6 için Masaüstü Kılavuzu belgeleri yapım aşamasındadır.

Ön koşullar

Makalede bağımlılık özellikleri hakkında temel bilgiler edindiğiniz ve Bağımlılık özelliklerine genel bakış makalesini okuduğunuz varsayılı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 üst öğesi tarafından nasıl işleneceğini belirten bir alt öğedir. Örneğin, DockPanel.Dock iliştirilmiş bir özelliktir çünkü kendisi değilDockPanel, alt DockPanelöğelerinde ayarlanmıştır. DockPanel sınıfı adlı DockPropertybir statik DependencyProperty alan tanımlar ve ardından ekli özellik için ortak erişimciler olarak ve SetDock yöntemleri sağlarGetDock.

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 örnekte bir alt öğesinin DockPanel özellik değerini nasıl ayarlayabildiği gösterilmektedir DockPanel.Dock .

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

Kullanım, örnek adına değil, ekli özelliğe (örneğin, DockPanel) sahip olan ve kaydeden türe başvurduğunuz 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 ekli özellikleri, meta verilerden varsayılan değerler içeren özellik meta verileri gibi bağımlılık özelliği kavramlarını destekler.

İliştirilmiş özellik 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. Üst tür, nesne ağacı yapısı üzerinde hareket eden, değerleri alan ve bu değerler üzerinde bir şekilde davranan iç mantık aracılığıyla alt nesnelerini yineler.
Ekli özelliği tanımlayan tür, çeşitli olası üst öğeler ve con çadır modu ls için alt öğe olarak kullanılır.
Ekli ö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.

Üst tanımlı ekli özellik örneği

WPF'nin ekli bir özelliği tanımladığı tipik senaryo, bir üst öğenin bir alt öğe koleksiyonunu desteklediği ve üst öğenin alt öğelerinin her biri tarafından bildirilen verileri temel alan bir davranış uygulamasıdır.

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ığına girişler haline gelir. Ekli özelliklerin öğeleri hemen üst öğenin ötesinde etkilemesi teorik olarak mümkün olsa da, iç içe DockPanel bir örneğin tanımlı davranışı yalnızca anlık alt öğe koleksiyonuyla etkileşime geçmektir. Bu nedenle, üst öğesi olmayan DockPanel bir öğede ayarlarsanız DockPanel.Dock hiçbir hata veya özel durum oluşturulmaz ve herhangi DockPanelbir 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 ve Set<property name>biçiminde Get<property name> ayrılmış erişimci yöntemleri 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 myDockPanelolarak eklemezsenizmyTextBox, ç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 özelliğinin özelliklerini belirtmek için özelliğinin işlemeyi veya ölçümü etkileyip etkilemediği gibi kullanın FrameworkPropertyMetadata . 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.

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

Özel ekli özellikler

Ekli özellik ne zaman oluşturulur?

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üzenleyebilme gibi Visual Studio WPF Tasarım Aracı desteği istiyorsunuz. Daha fazla bilgi için bkz . Denetim yazmaya genel bakış.
Özellik değeri devralmayı kullanmak istiyorsunuz.

Ekli özellik oluşturma

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 öğesinden DependencyObjecttüretmesi gerekmez. Aksi takdirde, sınıfınızı öğesinden DependencyObjecttüreterek ekli bir özelliğe sahip olan WPF modelini de bağımlılık özelliği olarak izleyin.

türünde DependencyPropertybir alan bildirerek ekli özelliğinizi tanımlama sınıfında bağımlılık public static readonly 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 ekli özelliğinize erişmesini sağlayan statik Get<property name> ve Set<property name> erişimci yöntemleri sağlayın.

Aşağıdaki örnekte yöntemini kullanarak RegisterAttached bağımlılık özelliğini kaydetme ve erişimci yöntemlerini tanımlama işlemleri gösterilmektedir. Örnekte, ekli özelliğin adı şeklindedirHasFish, bu nedenle tanımlayıcı alanı olarak adlandırılır HasFishPropertyve erişimci yöntemleri ve SetHasFisholarak adlandırılırGetHasFish.

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şimcisi

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

targetDependencyObject ekli özelliğin okunduğu yerdir. Türü target değerinden DependencyObjectdaha belirgin olabilir. Örneğin, ekli özelliğin örneklerde ayarlanması amaçlandığından erişimci DockPanel.GetDock yöntemi olarak yazın targetUIElement.UIElement UiElement dolaylı olarak dosyasından DependencyObjecttüretilir.
Dönüş türü değerinden objectdaha belirgin olabilir. Örneğin, dönüş değeri bir Dock numaralandırma olması gerektiğinden, GetDock yöntem döndürülen değeri olarak Dock yazın.

Dekont

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

Set erişimcisi

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

targetDependencyObject, ekli özelliğin yazıldığı yerdir. Türü target değerinden DependencyObjectdaha belirgin olabilir. Örneğin, SetDock ekli özelliğin örneklerde UIElement ayarlanması amaçlandığından yöntemi olarak yazın targetUIElement. UiElement dolaylı olarak dosyasından DependencyObjecttüretilir.
Türü value değerinden objectdaha 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ım Aracı, tüm ekli özelliklerin genel listesi olan kullanıcıların aşırı yüklenmesini önlemek için özellikler penceresinde gösterilen özellikleri sınırlamak için WPF tanımlı .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 geleneksel özellik sarmalayıcıları 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. Örnek için bkz. FrameworkElement.FlowDirection