Propriétés liables

Les propriétés pouvant être liées .NET MAUI (.NET Multi-Platform App UI) étendent la fonctionnalité des propriétés CLR (Common Language Runtime) en prenant en charge une propriété avec un type BindableProperty à la place d’un champ. Le but des propriétés pouvant être liées est de fournir un système de propriétés qui prend en charge la liaison de données, les styles, les modèles et les valeurs définis par le biais de relations parent-enfant. En outre, les propriétés pouvant être liées peuvent fournir des valeurs par défaut, la validation de valeurs de propriété et des rappels qui surveillent les modifications de propriété.

Dans les applications .NET MAUI, vous devez implémenter des propriétés en tant que propriétés pouvant être liées pour prendre en charge une ou plusieurs des fonctionnalités suivantes :

• Agir en tant que propriété cible valide pour la liaison de données. Pour plus d’informations sur les propriétés cibles, consultez Liaisons de base.
• Définir la propriété par le biais d’un style.
• Fournir une valeur de propriété par défaut différente de la valeur par défaut pour le type de la propriété.
• Valider la valeur de la propriété.
• Surveiller les modifications de propriété.

Label.Text, Button.BorderRadius et StackLayout.Orientation sont des exemples de propriétés pouvant être liées .NET MAUI. Chaque propriété pouvant être liée possède un champ public static readonly correspondant de type BindableProperty qui est exposé sur la même classe et qui est l’identificateur de la propriété pouvant être liée. Par exemple, l’identificateur de propriété pouvant être liée correspondant pour la propriété Label.Text est Label.TextProperty.

Créer une propriété pouvant être liée

Le processus de création d’une propriété pouvant être liée est le suivant :

1. Créez une instance BindableProperty avec l’une des surcharges de méthode BindableProperty.Create.
2. Définissez les accesseurs de propriété pour l’instance BindableProperty.

Toutes les instances BindableProperty doivent être créées sur le thread d’interface utilisateur. Cela signifie que seul le code qui s’exécute sur le thread d’interface utilisateur peut obtenir ou définir la valeur d’une propriété pouvant être liée. Toutefois, les instances BindableProperty sont accessibles à partir d’autres threads via un marshaling vers le thread d’interface utilisateur. Pour plus d’informations, consultez Exécuter du code sur le thread d’interface utilisateur.

Créer une propriété

Pour créer une instance BindableProperty, la classe contenante doit dériver de la classe BindableObject. Toutefois, la classe BindableObject se trouvant dans la partie supérieure de la hiérarchie des classes, la majorité des classes utilisées pour les fonctionnalités d’interface utilisateur prennent en charge les propriétés pouvant être liées.

Vous pouvez créer une propriété pouvant être liée en déclarant une propriété public static readonly de type BindableProperty. La propriété pouvant être liée doit être définie sur la valeur renvoyée de l’une des surcharges de méthode BindableProperty.Create. La déclaration doit se trouver dans le corps de la classe dérivée BindableObject, mais en dehors de toute définition de membre.

Au minimum, vous devez spécifier un identificateur lors de la création de BindableProperty, ainsi que les paramètres suivants :

• Nom de l'objet BindableProperty.
• Type de la propriété.
• Type de l’objet propriétaire.
• Valeur par défaut de la propriété. Cela garantit que la propriété retourne toujours une valeur par défaut particulière si elle n’est pas définie et qu’elle peut être différente de la valeur par défaut pour le type de la propriété. La valeur par défaut est restaurée lorsque la méthode ClearValue est appelée sur la propriété pouvant être liée.

Le code suivant montre un exemple de propriété pouvant être liée, avec un identificateur et des valeurs pour les quatre paramètres requis :

public static readonly BindableProperty IsExpandedProperty =
  BindableProperty.Create ("IsExpanded", typeof(bool), typeof(Expander), false);

Une instance BindableProperty nommée IsExpandedProperty de type bool est créée. La propriété appartient à la classe Expander et a pour valeur par défaut false.

Lors de la création d’une instance BindableProperty, vous pouvez éventuellement spécifier les paramètres suivants :

• Mode de liaison. Il est utilisé pour spécifier la direction dans laquelle les modifications de valeur de propriété se propagent. Dans le mode de liaison par défaut, les modifications se propagent de la source à la cible. Pour plus d’informations, consultez Liaisons de base.
• Un délégué de validation qui est appelé lorsque la valeur de propriété est définie. Pour plus d’informations, consultez Rappels de validation.
• Un délégué de propriété modifiée qui est appelé lorsque la valeur de propriété a été modifiée. Pour plus d’informations, consultez Détecter les modifications de propriété.
• Un délégué de modification de propriété qui est appelé lorsque la valeur de propriété va être modifiée. Ce délégué a la même signature que le délégué de propriété modifiée.
• Un délégué de forçage de valeur qui est appelé lorsque la valeur de propriété a été modifiée. Pour plus d’informations, consultez Rappels de forçage de valeur.
• Un Func utilisé pour initialiser une valeur de propriété par défaut. Pour plus d’informations, consultez Créer une valeur par défaut avec Func.

Créer des accesseurs

Les accesseurs de propriété doivent utiliser la syntaxe de propriété pour accéder à une propriété pouvant être liée. L’accesseur Get doit retourner la valeur contenue dans la propriété pouvant être liée correspondante. Pour ce faire, appelez la méthode GetValue, passez l’identificateur de la propriété pouvant être liée dont vous souhaitez obtenir la valeur, puis castez le résultat vers le type requis. L’accesseur Set doit définir la valeur de la propriété pouvant être liée correspondante. Pour ce faire, appelez la méthode SetValue, puis passez l’identificateur de la propriété pouvant être liée dont vous souhaitez définir la valeur et la valeur à définir.

L’exemple de code suivant montre les accesseurs pour la propriété pouvant être liée IsExpanded :

public bool IsExpanded
{
    get => (bool)GetValue(IsExpandedProperty);
    set => SetValue(IsExpandedProperty, value);
}

Consommer une propriété pouvant être liée

Une fois qu’une propriété pouvant être liée a été créée, vous pouvez la consommer en XAML ou dans du code. En XAML, déclarez un espace de noms avec un préfixe en indiquant le nom de l’espace de noms CLR dans la déclaration d’espace de noms et en spécifiant éventuellement un nom d’assembly. Pour plus d’informations, consultez Espaces de noms XAML.

L’exemple de code suivant illustre un espace de noms XAML pour un type personnalisé qui contient une propriété pouvant être liée, définie dans le même assembly que le code d’application qui référence le type personnalisé :

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

La déclaration d’espace de noms est utilisée lors de la définition de la propriété pouvant être liée IsExpanded, comme illustré dans l’exemple de code XAML suivant :

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

Le code C# équivalent est affiché dans l’exemple de code suivant :

Expander expander = new Expander
{
    IsExpanded = true
};

Scénarios avancés

Lors de la création d’une instance BindableProperty, vous pouvez définir un certain nombre de paramètres facultatifs pour prendre en charge des scénarios avancés avec des propriétés pouvant être liées. Cette section explore ces scénarios.

Détecter les modifications de propriété

Vous pouvez inscrire une méthode de rappel de propriété modifiée static auprès d’une propriété pouvant être liée en spécifiant le paramètre propertyChanged pour la méthode BindableProperty.Create. La méthode de rappel spécifiée est appelée lorsque la valeur de la propriété pouvant être liée est modifiée.

L’exemple de code suivant montre comment la propriété pouvant être liée IsExpanded inscrit la méthode OnIsExpandedChanged en tant que méthode de rappel de propriété modifiée :

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
}

Dans la méthode de rappel de propriété modifiée, le paramètre BindableObject est utilisé pour indiquer l’instance de la classe propriétaire qui a signalé une modification, et les valeurs des deux paramètres object représentent l’ancienne valeur et la nouvelle valeur de la propriété pouvant être liée.

Rappels de validation

Vous pouvez inscrire une méthode de rappel de validation static auprès d’une propriété pouvant être liée en spécifiant le paramètre validateValue pour la méthode BindableProperty.Create. La méthode de rappel spécifiée est appelée lorsque la valeur de la propriété pouvant être liée est définie.

L’exemple de code suivant montre comment la propriété pouvant être liée Angle inscrit la méthode IsValidValue en tant que méthode de rappel de validation :

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

Les rappels de validation sont fournis avec une valeur et doivent retourner true si la valeur est valide pour la propriété (sinon, false). Une exception est levée si un rappel de validation retourne false. Vous devez gérer cette exception. Une méthode de rappel de validation est généralement utilisée pour limiter les valeurs d’entiers ou de doubles lorsque la propriété pouvant être liée est définie. Par exemple, la méthode IsValidValue vérifie que la valeur de propriété est un double compris entre 0 et 360.

Rappels de forçage de valeur

Vous pouvez inscrire une méthode de rappel de forçage de valeur static auprès d’une propriété pouvant être liée en spécifiant le paramètre coerceValue pour la méthode BindableProperty.Create. La méthode de rappel spécifiée est appelée lorsque la valeur de la propriété pouvant être liée est sur le point d’être modifiée, ce qui vous permet d’ajuster la nouvelle valeur avant son application.

Les rappels de forçage de valeur sont utilisés pour forcer une réévaluation d’une propriété pouvant être liée lorsque la valeur de la propriété est sur le point d’être modifiée. Par exemple, un rappel de forçage de valeur peut être utilisé pour s’assurer que la valeur d’une propriété pouvant être liée n’est pas supérieure à la valeur d’une autre propriété pouvant être liée.

L’exemple de code suivant montre comment la propriété pouvant être liée Angle inscrit la méthode CoerceAngle en tant que méthode de rappel de forçage de valeur :

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

La méthode CoerceAngle vérifie la valeur de la propriété MaximumAngle et, si la valeur de la propriété Angle est supérieure, force la valeur à être égale à la valeur de la propriété MaximumAngle. De plus, lorsque la propriété MaximumAngle est modifiée, le rappel de forçage de valeur est appelé sur la propriété Angle en appelant la méthode CoerceValue.

Créer une valeur par défaut avec Func

Vous pouvez utiliser un Func pour initialiser la valeur par défaut d’une propriété pouvant être liée, comme illustré dans l’exemple suivant :

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

Le paramètre defaultValueCreator est défini sur un Func qui retourne un DateTime représentant la date du jour.