Bindbare Eigenschaften

Die bindbaren Eigenschaften von .NET Multiplatform App UI (.NET MAUI) erweitern die Common Language Runtime (CLR)-Eigenschaftsfunktionalität, indem sie eine Eigenschaft mit einem BindableProperty-Typ statt mit einem Feld unterlegen. 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.

In .NET MAUI-Apps sollten Eigenschaften als bindbare Eigenschaften implementiert werden, um mindestens eine der folgenden Features zu unterstützen:

• Fungieren als gültige Ziel-Eigenschaft für die Datenbindung. Weitere Informationen zu Zieleigenschaften finden Sie unter Grundlegende Bindungen.
• 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 bindbare .NET MAUI-Eigenschaften sind Label.Text, Button.BorderRadius und 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 BindableProperty-Instanzen kann jedoch von anderen Threads aus zugegriffen werden, indem sie den UI-Thread marshallen. Weitere Informationen finden Sie unter Ausführen von Code im UI-Thread.

Erstellen einer Eigenschaft

Zum Erstellen einer BindableProperty-Instanz muss die enthaltende Klasse von der BindableObject Klasse abgeleitet werden. Die Klasse BindableObject ist jedoch in der Klassenhierarchie weit oben angesiedelt, so dass die meisten Klassen, die für UI-Funktionen verwendet werden, bindbare Eigenschaften unterstützen

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 IsExpandedProperty =
  BindableProperty.Create ("IsExpanded", typeof(bool), typeof(Expander), false);

Dies erzeugt eine BindableProperty-Instanz mit dem Namen IsExpandedProperty, vom Typ bool. Die Eigenschaft ist eine nicht eigenständige Eigenschaft der Klasse Expander und hat den Standardwert false.

Hinweis

Expander ist ein Steuerelement im .NET MAUI-Community-Toolkit. Weitere Informationen finden Sie unter Erweiterung.

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. Weitere Informationen finden Sie unter Grundlegende Bindungen.
• 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 IsExpanded:

public bool IsExpanded
{
    get => (bool)GetValue(IsExpandedProperty);
    set => SetValue(IsExpandedProperty, 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:DataBindingDemos" ...>
  ...
</ContentPage>

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

<Expander IsExpanded="true">
    ...
</Expander>

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

Expander expander = new Expander
{
    IsExpanded = true
};

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 bindbaren Eigenschaft geändert hat.

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

public static readonly BindableProperty IsExpandedProperty =
    BindableProperty.Create(nameof(IsExpanded), typeof(bool), typeof(Expander), false, propertyChanged: OnIsExpandedChanged);
...

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

static bool IsValidValue(BindableObject view, object value)
{
    double result;
    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 Validierungs-Rückruf false zurückgibt, was Sie behandeln sollten. 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 bindbaren Eigenschaft ändern soll, sodass Sie den neuen Wert anpassen können, bevor er angewendet wird.

Wichtig

Zusätzlich zur Auslösung durch die Engine für bindbare Eigenschaften können Sie aus dem Code heraus Coerce-Value-Rückrufe aufrufen. 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-Value-Rückrufe werden verwendet, um eine Neubewertung einer bindbaren Eigenschaft zu erzwingen, wenn sich der Wert der Eigenschaft ändern soll. 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(MainPage), 0.0, coerceValue: CoerceAngle);
public static readonly BindableProperty MaximumAngleProperty =
    BindableProperty.Create("MaximumAngle", typeof(double), typeof(MainPage), 360.0, propertyChanged: ForceCoerceValue);
...

static object CoerceAngle(BindableObject bindable, object value)
{
    MainPage page = bindable as MainPage;
    double input = (double)value;

    if (input > page.MaximumAngle)
    {
        input = page.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 bindbaren Eigenschaft zu initialisieren, wie im folgenden Beispiel veranschaulicht:

public static readonly BindableProperty DateProperty =
    BindableProperty.Create ("Date", typeof(DateTime), typeof(MyPage), default(DateTime), BindingMode.TwoWay, defaultValueCreator: bindable => DateTime.Today);

Der Parameter defaultValueCreator wird auf einen Func gesetzt, der einen DateTime zurückgibt, der das heutige Datum darstellt.