Bağlanabilir özellikler

Makale
02/13/2024

.NET Çok Platformlu Uygulama Kullanıcı Arabirimi (.NET MAUI) bağlanabilir özellikleri, bir özelliği alan yerine türüyle BindableProperty destekleyerek Ortak Dil Çalışma Zamanı (CLR) özellik işlevselliğini genişletir. Bağlanabilir özelliklerin amacı, üst-alt ilişkiler aracılığıyla ayarlanan veri bağlamayı, stilleri, şablonları ve değerleri destekleyen bir özellik sistemi sağlamaktır. Ayrıca, bağlanabilir özellikler varsayılan değerler, özellik değerlerinin doğrulanması ve özellik değişikliklerini izleyen geri çağırmalar sağlayabilir.

.NET MAUI uygulamalarında, özellikler aşağıdaki özelliklerden birini veya daha fazlasını desteklemek için bağlanabilir özellikler olarak uygulanmalıdır:

Veri bağlama için geçerli bir hedef özelliği olarak davranma. Hedef özellikler hakkında daha fazla bilgi için bkz . Temel bağlamalar.
Özelliği bir stil aracılığıyla ayarlama.
Özelliğin türü için varsayılandan farklı bir varsayılan özellik değeri sağlama.
özelliğinin değeri doğrulanıyor.
özellik değişikliklerini izleme.

.NET MAUI bağlanabilir özelliklerine örnek olarak Label.Text, Button.BorderRadiusve StackLayout.Orientationverilebilir. Her bağlanabilir özellik, aynı sınıfta kullanıma sunulan ve bağlanabilir özelliğin tanımlayıcısı olan karşılık gelen public static readonly türde BindableProperty bir alana sahiptir. Örneğin, özelliği için karşılık gelen bağlanabilir özellik tanımlayıcısı Label.Text şeklindedir Label.TextProperty.

Bağlanabilir özellik oluşturma

Bağlanabilir özellik oluşturma işlemi aşağıdaki gibidir:

Yöntem aşırı yüklemelerinden BindableProperty.Create biriyle bir BindableProperty örnek oluşturun.
Örnek için BindableProperty özellik erişimcilerini tanımlayın.

Tüm BindableProperty örneklerin kullanıcı arabirimi iş parçacığında oluşturulması gerekir. Bu, yalnızca ui iş parçacığında çalışan kodun bağlanabilir bir özelliğin değerini alabildiği veya ayarlayabildiği anlamına gelir. Ancak, BindableProperty kullanıcı arabirimi iş parçacığına sıralanarak örneklere diğer iş parçacıklarından erişilebilir. Daha fazla bilgi için bkz . Ui iş parçacığında kod çalıştırma.

Özellik oluşturma

Örnek BindableProperty oluşturmak için, içeren sınıfın sınıfından BindableObject türetilmesi gerekir. Ancak sınıf, BindableObject sınıf hiyerarşisinde yüksek olduğundan, kullanıcı arabirimi işlevselliği için kullanılan sınıfların çoğu bağlanabilir özellikleri destekler.

türündeki bir özellik bildirilerek bağlanabilir bir public static readonly özellik BindablePropertyoluşturulabilir. Bağlanabilir özellik, yöntem aşırı yüklemelerinden BindableProperty.Create birinin döndürülen değerine ayarlanmalıdır. Bildirimi, türetilmiş sınıfın gövdesi içinde BindableObject , ancak tüm üye tanımlarının dışında olmalıdır.

En azından, oluştururken aşağıdaki parametrelerle birlikte bir BindablePropertytanımlayıcı belirtilmelidir:

BindableProperty öğesinin adı.
Özelliğin türü.
Sahip olan nesnenin türü.
Özelliği için varsayılan değer. Bu, özelliğin ayarsız olduğunda her zaman belirli bir varsayılan değer döndürmesini sağlar ve özelliğin türü için varsayılan değerden farklı olabilir. Yöntemi bağlanabilir özelliğinde ClearValue çağrıldığında varsayılan değer geri yüklenir.

Önemli

Bağlanabilir özelliklerin adlandırma kuralı, bağlanabilir özellik tanımlayıcısının yönteminde Create belirtilen özellik adıyla eşleşmesi ve sonuna "Özellik" eklenmesi gerektiğidir.

Aşağıdaki kod, tanımlayıcı ve gerekli dört parametre için değerler içeren bağlanabilir özellik örneğini gösterir:

public static readonly BindableProperty IsExpandedProperty =
  BindableProperty.Create ("IsExpanded", typeof(bool), typeof(Expander), false);

Bu, türünde booladlı IsExpandedPropertybir BindableProperty örnek oluşturur. özelliği sınıfına Expander aittir ve varsayılan değerine falsesahiptir.

İsteğe bağlı olarak, örnek BindableProperty oluştururken aşağıdaki parametreler belirtilebilir:

Bağlama modu. Bu, özellik değeri değişikliklerinin yayılacağı yönü belirtmek için kullanılır. Varsayılan bağlama modunda, değişiklikler kaynaktan hedefe yayılır. Daha fazla bilgi için bkz . Temel bağlamalar.
Özellik değeri ayarlandığında çağrılacak bir doğrulama temsilcisi. Daha fazla bilgi için bkz . Doğrulama geri çağırmaları.
Özellik değeri değiştiğinde çağrılacak bir özellik değiştirme temsilcisi. Daha fazla bilgi için bkz . Özellik değişikliklerini algılama.
Özellik değeri değiştirildiğinde çağrılacak temsilciyi değiştiren özellik. Bu temsilci, değiştirilen özellik temsilcisiyle aynı imzaya sahip.
Özellik değeri değiştiğinde çağrılacak bir zorlama değeri temsilcisi. Daha fazla bilgi için bkz . Coerce değeri geri çağırmaları.
Func Varsayılan özellik değerini başlatmak için kullanılan bir. Daha fazla bilgi için bkz . Func ile varsayılan değer oluşturma.

Erişimci oluşturma

Özellik erişimcileri, bağlanabilir bir özelliğe erişmek için özellik söz dizimini kullanmak için gereklidir. Erişimci, Get karşılık gelen bağlanabilir özelliğinde bulunan değeri döndürmelidir. Bu, yöntemini çağırarak GetValue , değerin alınacağı bağlanabilir özellik tanımlayıcısını geçirerek ve ardından sonucu gerekli türe geçirerek elde edilebilir. Erişimci, Set karşılık gelen bağlanabilir özelliğin değerini ayarlamalıdır. Bu, yöntemi çağrılarak SetValue , değerin ayarlanacağı bağlanabilir özellik tanımlayıcısı ve ayarlanacak değer geçirilerek gerçekleştirilebilir.

Aşağıdaki kod örneği, bağlanabilir özelliğin IsExpanded erişimcilerini gösterir:

public bool IsExpanded
{
    get => (bool)GetValue(IsExpandedProperty);
    set => SetValue(IsExpandedProperty, value);
}

Bağlanabilir özellik kullanma

Bağlanabilir bir özellik oluşturulduktan sonra XAML veya koddan kullanılabilir. XAML'de bu, clr ad alanı adını belirten ad alanı bildirimi ve isteğe bağlı olarak bir derleme adı ile bir ön ek ile bir ad alanı bildirilerek elde edilir. Daha fazla bilgi için bkz . XAML Ad Alanları.

Aşağıdaki kod örneği, özel türe başvuran uygulama koduyla aynı derleme içinde tanımlanan bağlanabilir özellik içeren özel bir tür için XAML ad alanını gösterir:

<ContentPage ... xmlns:local="clr-namespace:DataBindingDemos" ...>
  ...
</ContentPage>

Ad alanı bildirimi, aşağıdaki XAML kod örneğinde gösterildiği gibi bağlanabilir özellik ayarlanırken IsExpanded kullanılır:

<Expander IsExpanded="true">
    ...
</Expander>

Eşdeğer C# kodu aşağıdaki kod örneğinde gösterilmiştir:

Expander expander = new Expander
{
    IsExpanded = true
};

Gelişmiş senaryolar

Örnek oluştururken BindableProperty , gelişmiş bağlanabilir özellik senaryolarını etkinleştirmek için ayarlanabilen bir dizi isteğe bağlı parametre vardır. Bu bölümde bu senaryolar incelanmıştır.

Özellik değişikliklerini algılama

static Özellik tarafından değiştirilen geri çağırma yöntemi, yöntemin BindableProperty.Create parametresi belirtilerek propertyChanged bağlanabilir bir özelliğe kaydedilebilir. Belirtilen geri çağırma yöntemi, bağlanabilir özelliğin değeri değiştiğinde çağrılır.

Aşağıdaki kod örneğinde, bindable özelliğinin IsExpanded yöntemi özellik değiştirmeli geri çağırma yöntemi olarak nasıl kaydeddiği OnIsExpandedChanged gösterilmektedir:

public static readonly BindableProperty IsExpandedProperty =
    BindableProperty.Create(nameof(IsExpanded), typeof(bool), typeof(Expander), false, propertyChanged: OnIsExpandedChanged);
...

static void OnIsExpandedChanged (BindableObject bindable, object oldValue, object newValue)
{
  // Property changed implementation goes here
}

Özellik tarafından değiştirilen geri çağırma yönteminde BindableObject , sahip olan sınıfın hangi örneğinin değişiklik bildirdiğini belirtmek için parametresi kullanılır ve iki object parametrenin değerleri bindable özelliğinin eski ve yeni değerlerini temsil eder.

Doğrulama geri çağırmaları

Doğrulama static geri çağırma yöntemi, yöntemin BindableProperty.Create parametresi belirtilerek validateValue bağlanabilir bir özelliğe kaydedilebilir. Bindable özelliğinin değeri ayarlandığında belirtilen geri çağırma yöntemi çağrılır.

Aşağıdaki kod örneğinde bindable özelliğinin Angle yöntemi doğrulama geri çağırma yöntemi olarak nasıl kaydeddiği IsValidValue gösterilmektedir:

public static readonly BindableProperty AngleProperty =
    BindableProperty.Create("Angle", typeof(double), typeof(MainPage), 0.0, validateValue: IsValidValue);
...

static bool IsValidValue(BindableObject view, object value)
{
    double result;
    double.TryParse(value.ToString(), out result);
    return (result >= 0 && result <= 360);
}

Doğrulama geri çağırmaları bir değerle sağlanır ve değer özelliği için geçerliyse döndürülmelidir true , aksi takdirde false. Bir doğrulama geri çağırması döndürürse false, işlemeniz gereken bir özel durum oluşturulur. Doğrulama geri çağırma yönteminin tipik bir kullanımı, bağlanabilir özellik ayarlandığında tamsayıların veya çiftlerin değerlerini kısıtlamaktır. Örneğin, IsValidValue yöntemi özellik değerinin 0 ile 360 arasında bir double olup olmadığını denetler.

Zorlama değeri geri çağırmaları

Bir static zorlama değeri geri çağırma yöntemi, yöntemin BindableProperty.Create parametresi belirtilerek coerceValue bağlanabilir bir özelliğe kaydedilebilir. Belirtilen geri çağırma yöntemi, bağlanabilir özelliğin değeri değişmek üzereyken çağrılır, böylece yeni değeri uygulanmadan önce ayarlayabilirsiniz.

Önemli

Bağlanabilir özellik altyapısı tarafından tetiklenmenin yanı sıra koddan zorlama-değer geri çağırmaları da çağırabilirsiniz. türü, BindableObject zorlayıcı değeri geri çağırma yoluyla bağımsız değişkeninin değerinin BindableProperty yeniden değerlendirilmesini zorlamak için çağrılabilen bir CoerceValue yönteme sahiptir.

Zorlayıcı değer geri çağırmaları, özelliğin değeri değişmek üzereyken bağlanabilir bir özelliğin yeniden değerlendirilmesini zorlamak için kullanılır. Örneğin, bir zorlayıcı değer geri çağırma, bir bağlanabilir özelliğin değerinin başka bir bağlanabilir özelliğin değerinden büyük olmadığından emin olmak için kullanılabilir.

Aşağıdaki kod örneğinde, bindable özelliğinin Angle yöntemi bir zorlama değeri geri çağırma yöntemi olarak nasıl kaydettirdiği CoerceAngle gösterilmektedir:

public static readonly BindableProperty AngleProperty =
    BindableProperty.Create("Angle", typeof(double), typeof(MainPage), 0.0, coerceValue: CoerceAngle);
public static readonly BindableProperty MaximumAngleProperty =
    BindableProperty.Create("MaximumAngle", typeof(double), typeof(MainPage), 360.0, propertyChanged: ForceCoerceValue);
...

static object CoerceAngle(BindableObject bindable, object value)
{
    MainPage page = bindable as MainPage;
    double input = (double)value;

    if (input > page.MaximumAngle)
    {
        input = page.MaximumAngle;
    }

    return input;
}

static void ForceCoerceValue(BindableObject bindable, object oldValue, object newValue)
{
    bindable.CoerceValue(AngleProperty);
}

CoerceAngle yöntemi özelliğin MaximumAngle değerini denetler ve özellik değeri ondan büyükseAngle, değeri özellik değerine zorlamalıMaximumAngle. Ayrıca, özelliği değiştirdiğinde MaximumAngle , yöntemi çağrılarak özelliğinde Angle zorlama değeri geri çağırması çağrılır CoerceValue .

Func ile varsayılan değer oluşturma

aşağıdaki Func örnekte gösterildiği gibi, bağlanabilir bir özelliğin varsayılan değerini başlatmak için kullanılabilir:

public static readonly BindableProperty DateProperty =
    BindableProperty.Create ("Date", typeof(DateTime), typeof(MyPage), default(DateTime), BindingMode.TwoWay, defaultValueCreator: bindable => DateTime.Today);

defaultValueCreator parametresi, bugünün tarihini temsil eden bir döndüren değerine DateTime ayarlanırFunc.