Properti yang dapat diikat

Artikel
05/14/2024

Properti yang dapat diikat .NET Multi-platform App UI (.NET MAUI) memperluas fungsionalitas properti Common Language Runtime (CLR) dengan mendukung properti dengan BindableProperty jenis, bukan dengan bidang. Tujuan properti yang dapat diikat adalah untuk menyediakan sistem properti yang mendukung pengikatan data, gaya, templat, dan nilai yang diatur melalui hubungan induk-anak. Selain itu, properti yang dapat diikat dapat memberikan nilai default, validasi nilai properti, dan panggilan balik yang memantau perubahan properti.

Di aplikasi .NET MAUI, properti harus diimplementasikan sebagai properti yang dapat diikat untuk mendukung satu atau beberapa fitur berikut:

Bertindak sebagai properti target yang valid untuk pengikatan data. Untuk informasi selengkapnya tentang properti target, lihat Pengikatan dasar.
Mengatur properti melalui gaya.
Menyediakan nilai properti default yang berbeda dari default untuk jenis properti.
Memvalidasi nilai properti.
Memantau perubahan properti.

Contoh properti .NET MAUI yang dapat diikat termasuk Label.Text, , Button.BorderRadiusdan StackLayout.Orientation. Setiap properti yang dapat diikat memiliki bidang jenis BindableProperty yang sesuai public static readonly yang diekspos pada kelas yang sama dan itu adalah pengidentifikasi properti yang dapat diikat. Misalnya, pengidentifikasi properti yang dapat diikat yang sesuai untuk Label.Text properti adalah Label.TextProperty.

Membuat properti yang dapat diikat

Proses untuk membuat properti yang dapat diikat adalah sebagai berikut:

Buat BindableProperty instans dengan salah BindableProperty.Create satu metode kelebihan beban.
Tentukan aksesor properti untuk BindableProperty instans.

Semua BindableProperty instans harus dibuat pada utas UI. Ini berarti bahwa hanya kode yang berjalan pada utas UI yang bisa mendapatkan atau mengatur nilai properti yang dapat diikat. Namun, BindableProperty instans dapat diakses dari utas lain dengan melakukan marshal ke utas UI. Untuk informasi selengkapnya, lihat Menjalankan kode pada utas UI.

Membuat properti

Untuk membuat BindableProperty instans, kelas yang berisi harus berasal dari BindableObject kelas . Namun, BindableObject kelas ini tinggi dalam hierarki kelas, sehingga sebagian besar kelas yang digunakan untuk fungsionalitas UI mendukung properti yang dapat diikat.

Properti yang dapat diikat dapat dibuat dengan mendeklarasikan public static readonly properti jenis BindableProperty. Properti yang dapat diikat harus diatur ke nilai yang dikembalikan dari salah BindableProperty.Create satu metode kelebihan beban. Deklarasi harus berada dalam isi kelas turunan BindableObject , tetapi di luar definisi anggota apa pun.

Minimal, pengidentifikasi harus ditentukan saat membuat BindableProperty, bersama dengan parameter berikut:

Nama BindableProperty.
Jenis properti.
Jenis objek pemilik.
Nilai default untuk properti . Ini memastikan bahwa properti selalu mengembalikan nilai default tertentu saat tidak diatur, dan dapat berbeda dari nilai default untuk jenis properti. Nilai default akan dipulihkan ketika ClearValue metode dipanggil pada properti yang dapat diikat.

Penting

Konvensi penamaan untuk properti yang dapat diikat adalah bahwa pengidentifikasi properti yang dapat diikat harus cocok dengan nama properti yang ditentukan dalam Create metode , dengan "Properti" ditambahkan ke dalamnya.

Kode berikut menunjukkan contoh properti yang dapat diikat, dengan pengidentifikasi dan nilai untuk empat parameter yang diperlukan:

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

Ini membuat instans BindableProperty bernama IsExpandedProperty, dari jenis bool. Properti dimiliki oleh Expander kelas , dan memiliki nilai default .false

Catatan

Expander adalah kontrol di Toolkit Komunitas .NET MAUI. Untuk informasi selengkapnya, lihat Expander.

Secara opsional, saat membuat BindableProperty instans, parameter berikut dapat ditentukan:

Mode pengikatan. Ini digunakan untuk menentukan arah di mana perubahan nilai properti akan disebarluaskan. Dalam mode pengikatan default, perubahan akan disebarluaskan dari sumber ke target. Untuk informasi selengkapnya, lihat Pengikatan dasar.
Delegasi validasi yang akan dipanggil saat nilai properti diatur. Untuk informasi selengkapnya, lihat Panggilan balik validasi.
Properti mengubah delegasi yang akan dipanggil ketika nilai properti telah berubah. Untuk informasi selengkapnya, lihat Mendeteksi perubahan properti.
Properti yang mengubah delegasi yang akan dipanggil saat nilai properti akan berubah. Delegasi ini memiliki tanda tangan yang sama dengan delegasi yang diubah properti.
Delegasi nilai paksa yang akan dipanggil ketika nilai properti telah berubah. Untuk informasi selengkapnya, lihat Panggilan balik nilai koerce.
Func Yang digunakan untuk menginisialisasi nilai properti default. Untuk informasi selengkapnya, lihat Membuat nilai default dengan Func.

Membuat aksesor

Aksesor properti diperlukan untuk menggunakan sintaks properti untuk mengakses properti yang dapat diikat. Aksesor Get harus mengembalikan nilai yang terkandung dalam properti yang dapat diikat yang sesuai. Ini dapat dicapai dengan memanggil GetValue metode , meneruskan pengidentifikasi properti yang dapat diikat untuk mendapatkan nilai, lalu mentransmisikan hasilnya ke jenis yang diperlukan. Aksesor Set harus mengatur nilai properti yang dapat diikat yang sesuai. Ini dapat dicapai dengan memanggil SetValue metode , meneruskan pengidentifikasi properti yang dapat diikat untuk mengatur nilai, dan nilai yang akan diatur.

Contoh kode berikut menunjukkan aksesor untuk properti yang dapat diikat IsExpanded :

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

Mengonsumsi properti yang dapat diikat

Setelah properti yang dapat diikat dibuat, properti dapat dikonsumsi dari XAML atau kode. Di XAML, ini dicapai dengan mendeklarasikan namespace dengan awalan, dengan deklarasi namespace yang menunjukkan nama namespace CLR, dan secara opsional, nama rakitan. Untuk informasi selengkapnya, lihat Namespace XAML.

Contoh kode berikut menunjukkan namespace XAML untuk jenis kustom yang berisi properti yang dapat diikat, yang didefinisikan dalam rakitan yang sama dengan kode aplikasi yang mereferensikan jenis kustom:

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

Deklarasi namespace digunakan saat mengatur IsExpanded properti yang dapat diikat, seperti yang ditunjukkan dalam contoh kode XAML berikut:

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

Kode C# yang setara ditampilkan dalam contoh kode berikut:

Expander expander = new Expander
{
    IsExpanded = true
};

Skenario tingkat lanjut

Saat membuat BindableProperty instans, ada sejumlah parameter opsional yang dapat diatur untuk mengaktifkan skenario properti yang dapat diikat tingkat lanjut. Bagian ini menjelajahi skenario ini.

Mendeteksi perubahan properti

Metode static panggilan balik yang diubah properti dapat didaftarkan dengan properti yang dapat diikat dengan menentukan propertyChanged parameter untuk metode .BindableProperty.Create Metode panggilan balik yang ditentukan akan dipanggil ketika nilai properti yang dapat diikat telah berubah.

Contoh kode berikut menunjukkan bagaimana IsExpanded properti yang dapat diikat mendaftarkan OnIsExpandedChanged metode sebagai metode panggilan balik yang diubah properti:

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
}

Dalam metode panggilan balik yang diubah properti, BindableObject parameter digunakan untuk menunjukkan instans kelas pemilik mana yang telah melaporkan perubahan, dan nilai dua object parameter mewakili nilai lama dan baru dari properti yang dapat diikat.

Panggilan balik validasi

Metode static panggilan balik validasi dapat didaftarkan dengan properti yang dapat diikat dengan menentukan validateValue parameter untuk metode .BindableProperty.Create Metode panggilan balik yang ditentukan akan dipanggil ketika nilai properti yang dapat diikat diatur.

Contoh kode berikut menunjukkan bagaimana Angle properti yang dapat diikat mendaftarkan IsValidValue metode sebagai metode panggilan balik validasi:

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);
}

Panggilan balik validasi disediakan dengan nilai, dan harus mengembalikan true jika nilainya valid untuk properti, jika tidak false. Pengecualian akan dimunculkan jika panggilan balik validasi mengembalikan false, yang harus Anda tangani. Penggunaan umum metode panggilan balik validasi membatasi nilai bilangan bulat atau ganda saat properti yang dapat diikat diatur. Misalnya, IsValidValue metode memeriksa bahwa nilai properti berada double dalam rentang 0 hingga 360.

Panggilan balik nilai koerce

Metode static panggilan balik nilai koersi dapat didaftarkan dengan properti yang dapat diikat dengan menentukan coerceValue parameter untuk metode .BindableProperty.Create Metode panggilan balik yang ditentukan akan dipanggil ketika nilai properti yang dapat diikat akan berubah, sehingga Anda dapat menyesuaikan nilai baru sebelum diterapkan.

Penting

Selain dipicu oleh mesin properti yang dapat diikat, Anda dapat memanggil panggilan balik coerce-value dari kode. Jenis BindableObject memiliki CoerceValue metode yang dapat dipanggil untuk memaksa evaluasi ulang nilai argumennya BindableProperty , dengan memanggil panggilan balik nilai pemaksaannya.

Panggilan balik nilai koerce digunakan untuk memaksa evaluasi ulang properti yang dapat diikat ketika nilai properti akan berubah. Misalnya, panggilan balik nilai koersi dapat digunakan untuk memastikan bahwa nilai satu properti yang dapat diikat tidak lebih besar dari nilai properti lain yang dapat diikat.

Contoh kode berikut menunjukkan bagaimana Angle properti yang dapat diikat mendaftarkan CoerceAngle metode sebagai metode panggilan balik nilai koersi:

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);
}

Metode CoerceAngle ini memeriksa nilai MaximumAngle properti, dan jika Angle nilai properti lebih besar darinya, metode ini memaksa nilai ke MaximumAngle nilai properti. Selain itu, ketika MaximumAngle properti mengubah panggilan balik nilai koerce dipanggil pada Angle properti dengan memanggil CoerceValue metode .

Membuat nilai default dengan Func

Func Dapat digunakan untuk menginisialisasi nilai default properti yang dapat diikat, seperti yang ditunjukkan dalam contoh berikut:

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

Parameter defaultValueCreator diatur ke Func yang mengembalikan DateTime yang mewakili tanggal hari ini.

Bagikan melalui