Freigeben über

Xamarin.Forms Bindungsfähige Eigenschaften

  • Artikel

Bindbare Eigenschaften erweitern die CLR-Eigenschaftsfunktionalität, indem eine Eigenschaft mit einem BindableProperty Typ gesichert wird, anstatt eine Eigenschaft mit einem Feld zu sichern. Der Zweck von bindbaren Eigenschaften besteht darin, ein Eigenschaftensystem bereitzustellen, das Datenbindung, Formatvorlagen, Vorlagen und Werte unterstützt, die mithilfe über- und untergeordneter Beziehungen festgelegt werden. Darüber hinaus können bindbare Eigenschaften Standardwerte, Prüfung von Eigenschaftswerten und Rückrufe zur Überwachung von Eigenschaftsänderungen bereitstellen.

Eigenschaften sollten als bindungsfähige Eigenschaften implementiert werden, um mindestens eins der folgenden Features zu unterstützen:

  • Fungieren als gültige Ziel-Eigenschaft für die Datenbindung.
  • Festlegen der Eigenschaft über eine Formatvorlage.
  • Bereitstellen eines Standardeigenschaftswerts, der sich von der Standardeinstellung für den Typ der Eigenschaft unterscheidet.
  • Überprüfen des Wertes der Eigenschaft.
  • Überwachen von Eigenschaftsänderungen.

Beispiele für Xamarin.Forms bindungsfähige Eigenschaften sind , Label.TextButton.BorderRadiusund StackLayout.Orientation. Jede bindbare Eigenschaft verfügt über ein entsprechendes public static readonly-Feld vom Typ BindableProperty, das in derselben Klasse verfügbar gemacht wird und der Bezeichner der bindbaren Eigenschaft ist. Der entsprechende bindbare Eigenschaftsbezeichner für die Eigenschaft Label.Text lautet beispielsweise Label.TextProperty.

Erstellen einer bindbaren Eigenschaft

Der Prozess zum Erstellen einer bindbaren Eigenschaft lautet wie folgt:

  1. Erstellen einer BindableProperty-Instanz mit einer der BindableProperty.Create-Methodenüberladungen.
  2. Definieren der Eigenschaftszugriffsmethoden für die BindableProperty-Instanz.

Alle BindableProperty Instanzen müssen im UI-Thread erstellt werden. Dies bedeutet, dass nur Code, der im UI-Thread ausgeführt wird, den Wert einer bindbaren Eigenschaft abrufen oder festlegen kann. Auf Instanzen kann jedoch über andere Threads zugegriffen werden, BindableProperty indem sie mit der Device.BeginInvokeOnMainThread Methode an den UI-Thread marshallen.

Erstellen einer Eigenschaft

Zum Erstellen einer BindableProperty-Instanz muss die enthaltende Klasse von der BindableObject Klasse abgeleitet werden. Die BindableObject Klasse ist jedoch hoch in der Klassenhierarchie, daher unterstützen die meisten Klassen, die für die Benutzeroberflächenfunktionalität verwendet werden, bindungsfähige Eigenschaften.

Eine bindbare Eigenschaft kann durch Deklarieren einer public static readonly Eigenschaft vom Typ BindableProperty erstellt werden. Die bindbare Eigenschaft sollte auf den zurückgegebenen Wert einer der BindableProperty.Create-Methodenüberladungen festgelegt werden. Die Deklaration sollte sich im Textkörper der von BindableObject abgeleiteten Klasse, aber außerhalb von Memberdefinitionen befinden.

Bei der Erstellung einer BindableProperty muss mindestens ein Bezeichner angegeben werden, zusammen mit den folgenden Parametern:

  • Der Name von BindableProperty.
  • Den Typ der Eigenschaft.
  • Der Typ des besitzenden Objekts.
  • Der Standardwert für die Eigenschaft. Dadurch wird sichergestellt, dass die Eigenschaft immer einen bestimmten Standardwert zurückgibt, wenn sie nicht festgelegt ist, und sie kann vom Standardwert für den Typ der Eigenschaft abweichen. Der Standardwert wird wiederhergestellt, wenn die ClearValue-Methode für die bindbare Eigenschaft aufgerufen wird.

Wichtig

Die Namenskonvention für bindbare Eigenschaften besteht darin, dass der Bezeichner der bindbaren Eigenschaft mit dem in der Create-Methode angegebenen Eigenschaftsnamen übereinstimmen muss, wobei „Property“ angehängt wird.

Der folgende Code zeigt ein Beispiel für eine bindbaren Eigenschaft mit einem Bezeichner und Werten für die vier erforderlichen Parameter:

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

Dies erzeugt eine BindableProperty-Instanz mit dem Namen EventNameProperty, vom Typ string. Die Eigenschaft ist eine nicht eigenständige Eigenschaft der Klasse EventToCommandBehavior und hat den Standardwert null.

Optional können beim Erstellen einer BindableProperty-Instanz die folgenden Parameter angegeben werden:

  • Der Bindungsmodus. Dieser dient zur Angabe der Richtung, in der sich Eigenschaftswertänderungen verteilen. Im Standardbindungsmodus werden Änderungen von der Quelle an das Ziel verteilt.
  • Ein Prüfungsdelegat, der aufgerufen wird, wenn der Eigenschaftswert festgelegt wird. Weitere Informationen finden Sie unter Überprüfung von Rückrufen.
  • Ein Eigenschaftsdelegat, der aufgerufen wird, wenn sich der Eigenschaftswert geändert hat. Weitere Informationen finden Sie unter Erkennen von Eigenschaftsänderungen.
  • Ein Eigenschaftsänderungsdelegat, der aufgerufen wird, wenn sich der Eigenschaftswert ändert. Dieser Delegat hat die gleiche Signatur wie der Eigenschaftsänderungsdelegat.
  • Ein Coerce Value-Delegat, der aufgerufen wird, wenn sich der Eigenschaftswert geändert hat. Weitere Informationen finden Sie unter Coerce Value-Rückrufe.
  • Ein Func, das zur Initialisierung eines Standardeigenschaftswerts verwendet wird. Weitere Informationen finden Sie unter Erstellen eines Standardwerts mit einem Func.

Erstellen von Zugriffsmethoden

Eigenschaftenaccessoren sind erforderlich, um mithilfe der Eigenschaftssyntax auf eine bindbare Eigenschaft zuzugreifen. Der Get-Accessor sollte den Wert zurückgeben, der in der entsprechenden bindbaren Eigenschaft enthalten ist. Dies kann erreicht werden, indem man die Methode GetValue aufruft, den Bezeichner der bindbaren Eigenschaft übergibt, für die der Wert abgerufen werden soll, und dann das Ergebnis auf den erforderlichen Typ umsetzt. Der Set-Accessor sollte den Wert der entsprechenden bindbaren Eigenschaft festlegen. Dies kann erreicht werden, indem die SetValue Methode aufgerufen und der Bezeichner für bindungsfähige Eigenschaften, für den der Wert abgerufen werden soll, und der abzurufende Wert übergeben werden.

Das folgende Codebeispiel zeigt Accessors für die bindbare Eigenschaft EventName:

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

Verwenden einer bindbaren Eigenschaft

Sobald eine bindbare Eigenschaft erstellt wurde, kann sie aus XAML oder Code konsumiert werden. In XAML wird dies durch die Deklaration eines Namespace mit einem Präfix erreicht, wobei die Namespace-Deklaration den CLR-Namespace-Namen und optional einen Assembly-Namen angibt. Weitere Informationen finden Sie unter XAML Namespaces.

Das folgende Codebeispiel veranschaulicht einen XAML-Namespace für einen benutzerdefinierten Typ, der eine bindbare Eigenschaft enthält, die in derselben Assembly definiert ist wie der Anwendungscode, der auf den benutzerdefinierten Typ verweist:

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

Die Namespace-Deklaration wird beim Festlegen der bindbaren Eigenschaft EventName verwendet, wie im folgenden XAML-Codebeispiel gezeigt:

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

Der äquivalente C#-Code ist im folgenden Codebeispiel zu sehen:

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

Erweiterte Szenarios

Bei der Erstellung einer BindableProperty-Instanz gibt es eine Reihe von optionalen Parametern, die gesetzt werden können, um erweiterte Szenarien bindbarer Eigenschaften zu ermöglichen. In diesem Abschnitt werden diese Szenarien erläutert.

Erkennen von Eigenschaftsänderungen

Eine eigenschaftsgeänderte static Rückrufmethode kann sich mit einer bindbaren Eigenschaft registrieren, indem der propertyChanged-Parameter für die BindableProperty.Create-Methode angegeben wird. Die angegebene Rückrufmethode wird aufgerufen, wenn sich der Wert der bindungsfähigen Eigenschaft ändert.

Das folgende Codebeispiel zeigt, wie die bindbare Eigenschaft EventName die OnEventNameChanged-Methode als Rückrufmethode für geänderte Eigenschaften registriert:

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
}

In der Rückrufmethode für geänderte Eigenschaften wird der BindableObject-Parameter verwendet, um anzugeben, welche Instanz der besitzenden Klasse eine Änderung gemeldet hat. Die Werte der beiden object-Parameter stellen die alten und neuen Werte der bindbaren Eigenschaft dar.

Validierungs-Rückrufe

Eine static-Validierungs-Rückrufmethode kann sich mit einer bindbaren Eigenschaft registrieren, indem der validateValue-Parameter für die BindableProperty.Create-Methode angegeben wird. Die angegebene Rückrufmethode wird aufgerufen, wenn der Wert der bindbaren Eigenschaft gesetzt wird.

Das folgende Codebeispiel zeigt, wie sich die Angle bindbare Eigenschaft die IsValidValue-Methode als Rückrufmethode für die Validierung registriert:

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

Validierungs-Rückrufe werden mit einem Wert versehen und sollten true zurückgeben, wenn der Wert für die Eigenschaft gültig ist, ansonsten false. Eine Ausnahme wird ausgelöst, wenn ein Überprüfungsrückruf zurückgegeben falsewird, der vom Entwickler behandelt werden soll. Eine typische Verwendung einer Validierungs-Rückrufmethode ist die Beschränkung der Werte von Ganzzahlen oder Doubles, wenn die bindbare Eigenschaft gesetzt ist. Die IsValidValue-Methode prüft zum Beispiel, ob der Eigenschaftswert ein double im Bereich von 0 bis 360 ist.

Coerce Value-Rückrufe

Eine static Coerce-Value-Rückrufmethode kann mit einer bindbaren Eigenschaft registriert werden, indem der coerceValue-Parameter für die BindableProperty.Create-Methode angegeben wird. Die angegebene Rückrufmethode wird aufgerufen, wenn sich der Wert der bindungsfähigen Eigenschaft ändert.

Wichtig

Der BindableObject-Typ hat eine CoerceValue-Methode, die aufgerufen werden kann, um eine Neubewertung des Werts seines BindableProperty-Arguments zu erzwingen, indem sein Coerce-Value-Rückruf aufgerufen wird.

Coerce-Wertrückrufe werden verwendet, um eine erneute Auswertung einer bindungsfähigen Eigenschaft zu erzwingen, wenn sich der Wert der Eigenschaft ändert. Ein Coerce-Value-Rückruf kann zum Beispiel verwendet werden, um sicherzustellen, dass der Wert einer bindbaren Eigenschaft nicht größer ist als der Wert einer anderen bindbaren Eigenschaft.

Das folgende Codebeispiel zeigt, wie die bindbare Angle-Eigenschaft die CoerceAngle-Methode als Coerce-Value-Rückrufmethode registriert:

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

Die CoerceAngle-Methode prüft den Wert der MaximumAngle-Eigenschaft, und wenn der Wert der Angle-Eigenschaft größer ist als dieser, zwingt sie den Wert auf den Wert der MaximumAngle-Eigenschaft. Wenn sich die MaximumAngle-Eigenschaft ändert, wird außerdem der Coerce-Value-Rückruf für die Angle-Eigenschaft durch Aufruf der CoerceValue-Methode aufgerufen.

Erstellen eines Standardwerts mit einem Func

Eine Func kann verwendet werden, um den Standardwert einer bindungsfähigen Eigenschaft zu initialisieren, wie im folgenden Codebeispiel veranschaulicht:

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

Der defaultValueCreator Parameter wird auf eine Func Methode festgelegt, die die Device.GetNamedSize Methode aufruft, um eine double zurückzugeben, die den benannten Schriftgrad für die Schriftart darstellt, die auf einer Label systemeigenen Plattform verwendet wird.