Bagikan melalui

Xamarin.Forms Properti yang Dapat Diikat

  • Artikel

Properti yang dapat diikat memperluas fungsionalitas properti CLR dengan mendukung properti dengan BindableProperty jenis, alih-alih mencadangkan properti 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.

Properti harus diimplementasikan sebagai properti yang dapat diikat untuk mendukung satu atau beberapa fitur berikut:

  • Bertindak sebagai properti target yang valid untuk pengikatan data.
  • Mengatur properti melalui gaya.
  • Menyediakan nilai properti default yang berbeda dari default untuk jenis properti.
  • Memvalidasi nilai properti.
  • Memantau perubahan properti.

Xamarin.Forms Contoh properti 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:

  1. Buat BindableProperty instans dengan salah BindableProperty.Create satu metode kelebihan beban.
  2. 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 dengan Device.BeginInvokeOnMainThread metode .

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 antarmuka pengguna 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 EventNameProperty =
  BindableProperty.Create ("EventName", typeof(string), typeof(EventToCommandBehavior), null);

Ini membuat instans BindableProperty bernama EventNameProperty, dari jenis string. Properti dimiliki oleh EventToCommandBehavior kelas , dan memiliki nilai default .null

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.
  • 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 EventName :

public string EventName
{
  get { return (string)GetValue (EventNameProperty); }
  set { SetValue (EventNameProperty, 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:EventToCommandBehavior" ...>
  ...
</ContentPage>

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

<ListView ...>
  <ListView.Behaviors>
    <local:EventToCommandBehavior EventName="ItemSelected" ... />
  </ListView.Behaviors>
</ListView>

Kode C# yang setara ditampilkan dalam contoh kode berikut:

var listView = new ListView ();
listView.Behaviors.Add (new EventToCommandBehavior
{
  EventName = "ItemSelected",
  ...
});

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 berubah.

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

public static readonly BindableProperty EventNameProperty =
  BindableProperty.Create (
    "EventName", typeof(string), typeof(EventToCommandBehavior), null, propertyChanged: OnEventNameChanged);
...

static void OnEventNameChanged (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(HomePage), 0.0, validateValue: IsValidValue);
...

static bool IsValidValue (BindableObject view, object value)
{
  double result;
  bool isDouble = 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 dinaikkan jika panggilan balik validasi mengembalikan false, yang harus ditangani oleh pengembang. 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 berubah.

Penting

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 saat nilai properti 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(HomePage), 0.0, coerceValue: CoerceAngle);
public static readonly BindableProperty MaximumAngleProperty = BindableProperty.Create (
  "MaximumAngle", typeof(double), typeof(HomePage), 360.0, propertyChanged: ForceCoerceValue);
...

static object CoerceAngle (BindableObject bindable, object value)
{
  var homePage = bindable as HomePage;
  double input = (double)value;

  if (input > homePage.MaximumAngle)
  {
    input = homePage.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 kode berikut:

public static readonly BindableProperty SizeProperty =
  BindableProperty.Create ("Size", typeof(double), typeof(HomePage), 0.0,
  defaultValueCreator: bindable => Device.GetNamedSize (NamedSize.Large, (Label)bindable));

Parameter defaultValueCreator diatur ke Func yang memanggil Device.GetNamedSize metode untuk mengembalikan double yang mewakili ukuran bernama untuk font yang digunakan pada Label platform asli.