Udostępnij za pośrednictwem

Xamarin.Forms Właściwości możliwe do powiązania

  • Artykuł

Właściwości możliwe do powiązania rozszerzają funkcjonalność właściwości CLR, tworząc kopię zapasową właściwości o typie BindableProperty zamiast tworzenia kopii zapasowej właściwości za pomocą pola. Właściwości możliwe do powiązania mają na celu zapewnienie systemu właściwości obsługującego powiązanie danych, style, szablony i wartości ustawione za pośrednictwem relacji nadrzędny-podrzędny. Ponadto powiązane właściwości mogą udostępniać wartości domyślne, walidację wartości właściwości i wywołania zwrotne monitorujące zmiany właściwości.

Właściwości należy zaimplementować jako właściwości możliwe do powiązania, aby obsługiwać co najmniej jedną z następujących funkcji:

  • Działanie jako prawidłowa właściwość docelowa powiązania danych.
  • Ustawianie właściwości za pomocą stylu.
  • Podanie domyślnej wartości właściwości innej niż domyślna dla typu właściwości.
  • Weryfikowanie wartości właściwości.
  • Monitorowanie zmian właściwości.

Przykłady powiązanych Xamarin.Forms właściwości to Label.Text, Button.BorderRadiusi StackLayout.Orientation. Każda właściwość powiązana ma odpowiednie public static readonly pole typu BindableProperty , które jest uwidocznione w tej samej klasie i jest identyfikatorem właściwości możliwej do powiązania. Na przykład odpowiedni identyfikator właściwości możliwej do powiązania dla Label.Text właściwości to Label.TextProperty.

Tworzenie właściwości możliwej do powiązania

Proces tworzenia właściwości możliwej do powiązania jest następujący:

  1. BindableProperty Utwórz wystąpienie z jednym BindableProperty.Create z przeciążeń metody.
  2. Zdefiniuj BindableProperty metody dostępu do właściwości dla wystąpienia.

Wszystkie BindableProperty wystąpienia muszą zostać utworzone w wątku interfejsu użytkownika. Oznacza to, że tylko kod uruchamiany w wątku interfejsu użytkownika może pobrać lub ustawić wartość właściwości możliwej do powiązania. Można BindableProperty jednak uzyskać dostęp do wystąpień z innych wątków, marshaling do wątku interfejsu użytkownika za Device.BeginInvokeOnMainThread pomocą metody .

Tworzenie właściwości

Aby utworzyć BindableProperty wystąpienie, klasa zawierająca musi pochodzić z BindableObject klasy . BindableObject Jednak klasa jest wysoka w hierarchii klas, więc większość klas używanych do obsługi funkcji interfejsu użytkownika obsługuje powiązane właściwości.

Właściwość, którą można powiązać, można utworzyć, deklarując public static readonly właściwość typu BindableProperty. Właściwość powiązana powinna być ustawiona na zwracaną wartość jednego z BindableProperty.Create przeciążeń metody. Deklaracja powinna znajdować się w treści klasy pochodnej BindableObject , ale poza definicjami składowymi.

W przypadku tworzenia BindablePropertyobiektu należy określić co najmniej identyfikator wraz z następującymi parametrami:

  • Nazwa elementu BindableProperty.
  • Typ właściwości.
  • Typ obiektu będącego właścicielem.
  • Wartość domyślna właściwości . Gwarantuje to, że właściwość zawsze zwraca określoną wartość domyślną, gdy jest ona niezastawiona i może być inna niż wartość domyślna typu właściwości. Wartość domyślna zostanie przywrócona, gdy ClearValue metoda zostanie wywołana we właściwości możliwej do powiązania.

Ważne

Konwencja nazewnictwa właściwości możliwych do powiązania polega na tym, że identyfikator właściwości możliwej do powiązania musi być zgodny z nazwą właściwości określoną w Create metodzie, z dołączonym do niego ciągiem "Property".

Poniższy kod przedstawia przykład właściwości możliwej do powiązania z identyfikatorem i wartościami dla czterech wymaganych parametrów:

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

Spowoduje to utworzenie BindableProperty wystąpienia o nazwie EventNameProperty, typu string. Właściwość jest własnością EventToCommandBehavior klasy i ma wartość nulldomyślną .

Opcjonalnie podczas tworzenia BindableProperty wystąpienia można określić następujące parametry:

  • Tryb powiązania. Służy do określania kierunku, w którym zmiany wartości właściwości będą propagowane. W domyślnym trybie powiązania zmiany będą propagowane ze źródła do miejsca docelowego.
  • Delegat weryfikacji, który zostanie wywołany po ustawieniu wartości właściwości. Aby uzyskać więcej informacji, zobacz Sprawdzanie poprawności wywołań zwrotnych.
  • Delegat zmiany właściwości, który zostanie wywołany po zmianie wartości właściwości. Aby uzyskać więcej informacji, zobacz Wykrywanie zmian właściwości.
  • Delegat zmiany właściwości, który zostanie wywołany, gdy wartość właściwości zostanie zmieniona. Ten delegat ma ten sam podpis, co właściwość zmieniona delegata.
  • Delegat wartości coerce, który zostanie wywołany po zmianie wartości właściwości. Aby uzyskać więcej informacji, zobacz Coerce value callbacks (Wywołania zwrotne wartości coerce).
  • Element Func używany do inicjowania wartości właściwości domyślnej. Aby uzyskać więcej informacji, zobacz Create a default value with a Func (Tworzenie wartości domyślnej za pomocą narzędzia Func).

Tworzenie metod dostępu

Metody dostępu do właściwości są wymagane do używania składni właściwości w celu uzyskania dostępu do właściwości możliwej do powiązania. Akcesorium Get powinno zwrócić wartość zawartą w odpowiedniej właściwości możliwej do powiązania. Można to osiągnąć, wywołując metodę GetValue , przekazując identyfikator właściwości możliwej do powiązania, dla której ma zostać pobrana wartość, a następnie rzutując wynik na wymagany typ. Metodę Set dostępu należy ustawić wartość odpowiedniej właściwości możliwej do powiązania. Można to osiągnąć, wywołując metodę SetValue , przekazując identyfikator właściwości możliwej do powiązania, dla której należy ustawić wartość, oraz wartość do ustawienia.

Poniższy przykład kodu przedstawia metody dostępu dla właściwości możliwej EventName do powiązania:

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

Korzystanie z właściwości możliwej do powiązania

Po utworzeniu właściwości możliwej do powiązania można jej użyć z kodu lub kodu XAML. W języku XAML jest to osiągane przez zadeklarowanie przestrzeni nazw z prefiksem z deklaracją przestrzeni nazw wskazującą nazwę przestrzeni nazw CLR i opcjonalnie nazwę zestawu. Aby uzyskać więcej informacji, zobacz Przestrzenie nazw XAML.

W poniższym przykładzie kodu pokazano przestrzeń nazw XAML dla typu niestandardowego zawierającego właściwość powiązaną, która jest zdefiniowana w tym samym zestawie co kod aplikacji odwołujący się do typu niestandardowego:

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

Deklaracja przestrzeni nazw jest używana podczas ustawiania właściwości możliwej EventName do powiązania, jak pokazano w poniższym przykładzie kodu XAML:

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

Równoważny kod języka C# jest pokazany w poniższym przykładzie kodu:

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

Zaawansowane scenariusze

Podczas tworzenia BindableProperty wystąpienia istnieje wiele opcjonalnych parametrów, które można ustawić w celu włączenia zaawansowanych scenariuszy właściwości możliwych do powiązania. W tej sekcji omówiono te scenariusze.

Wykrywanie zmian właściwości

static Metodę wywołania zwrotnego zmiany właściwości można zarejestrować za pomocą właściwości możliwej do powiązania, określając propertyChanged parametr metody BindableProperty.Create . Określona metoda wywołania zwrotnego zostanie wywołana po zmianie wartości właściwości możliwej do powiązania.

W poniższym przykładzie kodu pokazano, jak EventName właściwość z możliwością powiązania rejestruje OnEventNameChanged metodę jako metodę wywołania zwrotnego zmiany właściwości:

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
}

W metodzie wywołania zwrotnego zmienionej właściwości parametr służy do oznaczania, BindableObject które wystąpienie klasy będącej właścicielem zgłosiło zmianę, a wartości dwóch object parametrów reprezentują stare i nowe wartości właściwości możliwe do powiązania.

Wywołania zwrotne weryfikacji

static Metodę wywołania zwrotnego weryfikacji można zarejestrować za pomocą właściwości możliwej do powiązania, określając validateValue parametr metody BindableProperty.Create . Określona metoda wywołania zwrotnego zostanie wywołana po ustawieniu wartości właściwości możliwej do powiązania.

W poniższym przykładzie kodu pokazano, jak Angle właściwość z możliwością powiązania rejestruje IsValidValue metodę jako metodę wywołania zwrotnego weryfikacji:

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

Wywołania zwrotne weryfikacji są dostarczane z wartością i powinny zwracać true , jeśli wartość jest prawidłowa dla właściwości, w przeciwnym razie false. Wyjątek zostanie zgłoszony, jeśli wywołanie zwrotne weryfikacji zwróci falsewartość , która powinna być obsługiwana przez dewelopera. Typowym zastosowaniem metody wywołania zwrotnego walidacji jest ograniczenie wartości liczb całkowitych lub podwaja się po ustawieniu właściwości możliwej do powiązania. Na przykład metoda sprawdza, IsValidValue czy wartość właściwości mieści się double w zakresie od 0 do 360.

Wywołania zwrotne wartości coerce

Metodę static wywołania zwrotnego wartości coerce można zarejestrować za pomocą właściwości możliwej do powiązania, określając coerceValue parametr dla BindableProperty.Create metody . Określona metoda wywołania zwrotnego zostanie wywołana po zmianie wartości właściwości możliwej do powiązania.

Ważne

Typ BindableObject ma metodę CoerceValue , którą można wywołać w celu wymuszenia ponownej oceny wartości argumentu BindableProperty , wywołując wywołanie zwrotne wartości coerce.

Wywołania zwrotne wartości coerce są używane do wymuszenia ponownej oceny właściwości możliwej do powiązania, gdy wartość właściwości ulegnie zmianie. Na przykład wywołanie zwrotne wartości coerce może służyć do zapewnienia, że wartość jednej właściwości możliwej do powiązania nie jest większa niż wartość innej właściwości możliwej do powiązania.

W poniższym przykładzie kodu pokazano, jak Angle właściwość z możliwością powiązania rejestruje CoerceAngle metodę jako metodę wywołania zwrotnego wartości coerce:

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

Metoda CoerceAngle sprawdza wartość MaximumAngle właściwości, a jeśli Angle wartość właściwości jest większa niż, przekształca wartość na MaximumAngle wartość właściwości. Ponadto, gdy MaximumAngle właściwość zmienia wywołanie zwrotne wartości coerce jest wywoływane we Angle właściwości przez wywołanie CoerceValue metody .

Tworzenie wartości domyślnej za pomocą narzędzia Func

Element może Func służyć do inicjowania wartości domyślnej właściwości możliwej do powiązania, jak pokazano w poniższym przykładzie kodu:

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

Parametr defaultValueCreator jest ustawiony na Func wartość , która wywołuje Device.GetNamedSize metodę w celu zwrócenia elementu double reprezentującego nazwany rozmiar czcionki używanej na Label platformie natywnej.