آموزش Bindable Properties در زامارین فرم

موارد استفاده Bindable Properties به شرح زیر است 

1. اعتبار سنجی data binding
2. تنظیم ویژگی از طریق استایل ها
3. تنظیم مقدار پیش فرض property که متفاوت از مقدار پیش فرض اصلی باشد
4. اعتبار سنجی مقدار property
5. نظارت بر تغییرات property

در کنترل های زامارین فرم از این خصوصیت استفاده شده است .Label.Text و Button.BorderRadius و StackLayout.Orientation از جمله خصوصیت هایی هستند که با استفاده از Bindable Properties قابل مقدار دهی می باشند . هر bindable property دارای یک فیلد public static readonly مربوط به نوع BindableProperty عمومی است که در همان کلاس قرار می گیرد .

ایجاد bindable property

برای ایجاد یک نمونه BindableProperty ، کلاس مورد نظر باید از کلاس BindableObject مشتق شود. کلاس BindableObject در سلسله مراتب بالا قرار دارد ، بنابراین اکثر کلاس هایی که برای عملکرد رابط کاربر استفاده می شوند از bindable properties پشتیبانی می کنند. با اعلام یک public static readonly از نوع BindableProperty می توان یک bindable properties ایجاد کرد.

پارامتر های BindableProperty

حداقل پارامتر برای ایجاد یک BindableProperty به شرح زیر است 

1. نام BindableProperty
2. نوع property
3. نوع owning object
4. مقدار پیش فرض property : این اطمینان می دهد که property همیشه هنگام تنظیم نشدن  ، مقدار پیش فرض خاصی را برمی گرداند ، و می تواند متفاوت از مقدار پیش فرض اصلی  باشد. با فراخوانی روش ClearValue بر روی property ، مقدار پیش فرض بازیابی می شود.

قرارداد نامگذاری برای bindable properties به این صورت است که بعد نام BindableProperty کلمه property  قرار می گیرد

کد زیر مثالی از ویژگی BindableProperty را با یک شناسه و مقادیر برای چهار پارامتر مورد نیاز نشان می دهد:

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

در کد بالا یک نمونه BindableProperty به نام EventNameProperty ، از نوع رشته ایجاد شده است و متعلق به کلاس EventToCommandBehavior و مقدار پیش فرض آن null است. به صورت اختیاری ، هنگام ایجاد یک نمونه BindableProperty ، پارامترهای زیر را می توان تعیین کرد

binding mode

 برای تعیین جهتی که در آن تغییرات مقدار خاصیت تغییر می یابد، استفاده می شود. در حالت پیش فرض ، تغییرات از مبدا به هدف منتقل می شوند.

validation delegate

زمانی فراخوانی خواهد شد که property مقدار دهی شود

property changed

زمانی فراخوانی خواهد شد که مقدار property تغییر کرده باشد

property changing

زمانی فراخوانی خواهد شد که مقدار property در حال تغییر باشد

Func

تابعی برای مقدار دهی اولیه به property 

مقادر اجباری coerce value 

زمانی فراخوانی خواهد شد که مقدار property تغییر کرده باشد

ایجاد accessors

برای دسترسی به bindable property  نیاز به تعریف Property accessors داریم . Get accessor باید مقداری را که در BindableProperty مربوطه وجود دارد ، برگرداند. این امر می تواند با فراخوانی روش GetValue صورت گیرد . Set accessor باید مقدار BindableProperty مربوطه را تنظیم کند. این امر می تواند با فراخوانی روش SetValue  صورت گیرد .

در کد زیر نحوه get  و set اورده شده است

public string EventName
{
  get { return (string)GetValue (EventNameProperty); }
  set { SetValue (EventNameProperty, value); }
}

نحوه استفاده از bindable property

پس از ایجاد bindable property ، می توان آن را از XAML یا کد استفاده کرد. در XAML ، این امر با اعلام یک فضای نام با پیشوند ، یک فضای نام CLR ، و در صورت تمایل ، یک اسمبلی حاصل می شود. 

<ContentPage ... xmlns:local="clr-namespace:EventToCommandBehavior" ...>
  <ListView ...>
  <ListView.Behaviors>
    <local:EventToCommandBehavior EventName="ItemSelected" ... />
  </ListView.Behaviors>
</ListView>
</ContentPage>

کد C # معادل در مثال  زیر نشان داده شده است

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

سناریوهای پیشرفته

هنگام ایجاد یک نمونه BindableProperty ، تعدادی پارامتر اختیاری وجود دارد که می توانند برای فعال کردن سناریوهای پیشرفته ، تنظیم شوند. در این بخش این سناریوها را بررسی می کنیم .

تشخیص تغییرات در مقدار property

وقتی مقدار property  تغییر می کند متدی که در پارامتر propertyChanged تعریف شده است فراخوانی شده و اجرا می شود 

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
}

برای propertyChanged هم به شکل مشابه کد بالا عمل می کند 

Validation callbacks

وقتی مقدار property  ست شد متدی که در پارامتر IsValidValue تعریف شده است فراخوانی شده و اجرا می شود 

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

در مثال بالا مقداری که وارد شده اگر بین 0 تا 360 باشد مقدار true  برگشت داده می شود و توسعه دهنده می تواند به ان دسترسی داشته باشد.

Func

همانطور که در مثال کد زیر نشان داده شده است ، می توان از Func برای مقداردهی پیش فرض یک خاصیت استفاده کرد

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

پارامتر defaultValueCreator در زمان فراخوانی خاصیت به عنوان مقدار پیش فرض سایز قلم دستگاه تنظیم شده است .

مقادیر اجباری Coerce value

زمانی فراخوانی خواهد شد که bindable property تغییر کند 

نوع BindableObject دارای یک متد CoerceValue است که می توان با فراخوانی مقادیر  اجباری ، ارزیابی مجدد از مقدار  BindableProperty خود را بررسی کند.

به طور کلی برای چک کردن مقادیر به کار می رود به عنوان مثال در کد زیر چک می کند مقدار درجه وارد شده ورودی بیشتر از 360 درجه نباشد و در صورتی که بیشتر بود ان را 360 در نظر می گیرد.

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

دانلود نمونه کد و مثال