Xamarin.Forms Bindbare Eigenschaften

Artikel
07/13/2023

Bindbare Eigenschaften erweitern die CLR-Eigenschaftsfunktionalität, indem sie eine Eigenschaft mit einem BindableProperty Typ sichern, anstatt eine Eigenschaft mit einem Feld zu sichern. Der Zweck von bindbaren Eigenschaften besteht darin, ein Eigenschaftensystem bereitzustellen, das Datenbindungen, Stile, Vorlagen und Werte unterstützt, die über über-untergeordnete Beziehungen festgelegt werden. Darüber hinaus können bindbare Eigenschaften Standardwerte, Überprüfungen von Eigenschaftswerten und Rückrufe bereitstellen, die Eigenschaftsänderungen überwachen.

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

Dient als gültige Zieleigenschaft für die Datenbindung.
Festlegen der Eigenschaft über einen Stil.
Bereitstellen eines Standardeigenschaftswerts, der sich vom Standardwert für den Typ der Eigenschaft unterscheidet.
Überprüfen des Werts der Eigenschaft.
Überwachen von Eigenschaftenänderungen.

Xamarin.Forms Beispiele für bindbare Eigenschaften sind Label.Text, Button.BorderRadiusund StackLayout.Orientation. Jede bindbare Eigenschaft verfügt über ein entsprechendes public static readonly Feld vom Typ BindableProperty , das für dieselbe Klasse verfügbar gemacht wird, und das ist der Bezeichner der bindbaren Eigenschaft. Der entsprechende bindbare Eigenschaftsbezeichner für die Label.Text -Eigenschaft ist z. B Label.TextProperty. .

Erstellen einer bindbaren Eigenschaft

Der Prozess zum Erstellen einer bindbaren Eigenschaft sieht wie folgt aus:

Erstellen Sie eine BindableProperty instance mit einer der BindableProperty.Create Methodenüberladungen.
Definieren Sie Eigenschaftenaccessoren für die BindableProperty instance.

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 von anderen Threads aus zugegriffen werden, BindableProperty indem mit der -Methode in den Device.BeginInvokeOnMainThread UI-Thread gemarshallt wird.

Erstellen einer Eigenschaft

Um eine BindableProperty instance zu erstellen, muss die enthaltende Klasse von der BindableObject -Klasse abgeleitet werden. Die BindableObject Klasse ist jedoch in der Klassenhierarchie hoch, sodass die meisten Klassen, die für benutzeroberflächenfunktionen verwendet werden, bindbare Eigenschaften unterstützen.

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

Beim Erstellen eines BindablePropertymuss mindestens ein Bezeichner zusammen mit den folgenden Parametern angegeben werden:

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 dass sie sich vom Standardwert für den Typ der Eigenschaft unterscheiden kann. Der Standardwert wird wiederhergestellt, wenn die ClearValue Methode für die bindbare Eigenschaft aufgerufen wird.

Wichtig

Die Benennungskonvention für bindbare Eigenschaften besteht darin, dass der bindbare Eigenschaftsbezeichner mit dem in der Create -Methode angegebenen Eigenschaftennamen übereinstimmen muss, wobei "Property" angefügt ist.

Der folgende Code zeigt ein Beispiel für eine bindbare 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);

Dadurch wird eine BindableProperty instance namens erstelltEventNameProperty, die vom Typ stringist. Die -Eigenschaft gehört der EventToCommandBehavior -Klasse und hat den Standardwert null.

Optional können beim Erstellen eines BindableProperty instance die folgenden Parameter angegeben werden:

Der Bindungsmodus. Dies wird verwendet, um die Richtung anzugeben, in der Eigenschaftswertänderungen weitergegeben werden. Im Standardbindungsmodus werden Änderungen von der Quelle an das Ziel weitergegeben.
Ein Validierungsdelegat, der aufgerufen wird, wenn der Eigenschaftswert festgelegt wird. Weitere Informationen finden Sie unter Überprüfung von Rückrufen.
Ein Geänderter Delegat der Eigenschaft, der aufgerufen wird, wenn sich der Eigenschaftswert geändert hat. Weitere Informationen finden Sie unter Erkennen von Eigenschaftenänderungen.
Ein Eigenschaftsänderungsdelegat, der aufgerufen wird, wenn sich der Eigenschaftswert ändert. Dieser Delegat verfügt über die gleiche Signatur wie der Geänderte Delegat der Eigenschaft.
Ein Coerce-Wertdelegat, der aufgerufen wird, wenn sich der Eigenschaftswert geändert hat. Weitere Informationen finden Sie unter Coerce-Wertrückrufe.
Ein Func , der verwendet wird, um einen Standardeigenschaftswert zu initialisieren. Weitere Informationen finden Sie unter Erstellen eines Standardwerts mit einem Func.

Erstellen von Accessoren

Eigenschaftenaccessoren müssen eigenschaftensyntax verwenden, um 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 Sie die GetValue -Methode aufrufen, den bindbaren Eigenschaftsbezeichner übergeben, für den der Wert abgerufen werden soll, und dann das Ergebnis in den erforderlichen Typ umwandeln. Der Set Accessor sollte den Wert der entsprechenden bindbaren Eigenschaft festlegen. Dies kann durch Aufrufen der SetValue -Methode erreicht werden, wobei der bindbare Eigenschaftsbezeichner, für den der Wert festgelegt werden soll, und der festzulegende Wert übergeben wird.

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

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

Verwenden einer bindbaren Eigenschaft

Nachdem eine bindbare Eigenschaft erstellt wurde, kann sie von XAML oder Code verwendet werden. In XAML wird dies erreicht, indem ein Namespace mit einem Präfix deklariert wird, wobei die Namespacedeklaration den CLR-Namespacenamen und optional einen Assemblynamen angibt. Weitere Informationen finden Sie unter XAML-Namespaces.

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

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

Die Namespacedeklaration wird beim Festlegen der EventName bindbaren Eigenschaft verwendet, wie im folgenden XAML-Codebeispiel veranschaulicht:

<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

Beim Erstellen eines BindableProperty instance gibt es eine Reihe optionaler Parameter, die festgelegt werden können, um erweiterte Szenarien für bindbare Eigenschaften zu ermöglichen. In diesem Abschnitt werden diese Szenarien erläutert.

Erkennen von Eigenschaftenänderungen

Eine static durch die Eigenschaft geänderte Rückrufmethode kann bei einer bindbaren Eigenschaft registriert werden, indem der propertyChanged Parameter für die BindableProperty.Create -Methode angegeben wird. Die angegebene Rückrufmethode wird aufgerufen, wenn sich der Wert der bindbaren Eigenschaft ändert.

Das folgende Codebeispiel zeigt, wie die EventName bindbare Eigenschaft die OnEventNameChanged -Methode als durch die Eigenschaft geänderte Rückrufmethode 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 von der Eigenschaft geänderten Rückrufmethode wird der BindableObject Parameter verwendet, um anzugeben, welche instance der besitzenden Klasse eine Änderung gemeldet hat, und die Werte der beiden object Parameter stellen die alten und neuen Werte der bindbaren Eigenschaft dar.

Überprüfungsrückrufe

Eine static Validierungsrückrufmethode kann mit einer bindbaren Eigenschaft registriert werden, indem der validateValue Parameter für die BindableProperty.Create -Methode angegeben wird. Die angegebene Rückrufmethode wird aufgerufen, wenn der Wert der bindbaren Eigenschaft festgelegt wird.

Das folgende Codebeispiel zeigt, wie die Angle bindbare Eigenschaft die IsValidValue -Methode als Validierungsrückrufmethode 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);
}

Validierungsrückrufe werden mit einem -Wert bereitgestellt und sollten zurückgeben true , wenn der Wert für die -Eigenschaft gültig ist, andernfalls false. Eine Ausnahme wird ausgelöst, wenn ein Überprüfungsrückruf zurückgibt false, der vom Entwickler behandelt werden soll. Eine typische Verwendung einer Überprüfungsrückrufmethode besteht darin, die Werte von ganzen Zahlen oder Doubles einzuschränken, wenn die bindbare Eigenschaft festgelegt ist. Die -Methode überprüft beispielsweise, IsValidValue ob der Eigenschaftswert im double Bereich von 0 bis 360 liegt.

Coerce-Wertrückrufe

Eine static Coerce-Wert-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 bindbaren Eigenschaft ändert.

Wichtig

Der BindableObject -Typ verfügt über eine CoerceValue -Methode, die aufgerufen werden kann, um eine Neubewertung des Werts seines BindableProperty Arguments zu erzwingen, indem der Coerce-Wertrückruf aufgerufen wird.

Coerce-Wertrückrufe werden verwendet, um eine Neubewertung einer bindbaren Eigenschaft zu erzwingen, wenn sich der Wert der Eigenschaft ändert. Beispielsweise kann ein Coerce-Wertrückruf verwendet werden, um sicherzustellen, dass der Wert einer bindbaren Eigenschaft nicht größer als der Wert einer anderen bindbaren Eigenschaft ist.

Das folgende Codebeispiel zeigt, wie die Angle bindbare Eigenschaft die CoerceAngle -Methode als Coerce-Wert-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 überprüft den Wert der MaximumAngle -Eigenschaft, und wenn der Angle Eigenschaftswert größer als er ist, wird der Wert in den MaximumAngle Eigenschaftswert umgestaltet. Wenn die -Eigenschaft ändertMaximumAngle, wird außerdem der Coerce-Wertrückruf für die -Eigenschaft durch Aufrufen der CoerceValueAngle -Methode aufgerufen.

Erstellen eines Standardwerts mit einem Func

Ein Func kann verwendet werden, um den Standardwert einer bindbaren 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 festgelegt, die die Device.GetNamedSize -Methode aufruft, um eine double zurückzugeben, die die benannte Größe für die Schriftart darstellt, die auf der Label nativen Plattform verwendet wird.