Xamarin.Forms Propriétés pouvant être liées

Article
01/16/2020

Les propriétés pouvant être liées étendent la fonctionnalité de propriété CLR en appuyant une propriété avec un BindableProperty type, au lieu de sauvegarder une propriété avec 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é.

Les propriétés doivent être implémentées 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.
Définition de la propriété à l’aide 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é.

Exemples de Xamarin.Forms propriétés pouvant être liées : Label.Text, Button.BorderRadiuset StackLayout.Orientation. 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 :

Créez une instance BindableProperty avec l’une des surcharges de méthode BindableProperty.Create.
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, BindableProperty les instances sont accessibles à partir d’autres threads en marshalant vers le thread d’interface utilisateur avec la Device.BeginInvokeOnMainThread méthode.

Créer une propriété

Pour créer une instance BindableProperty, la classe contenante doit dériver de la classe BindableObject. Toutefois, la BindableObject classe est élevée dans la hiérarchie de classes, de sorte que la majorité des classes utilisées pour la fonctionnalité 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.

Important

Selon la convention d’affectation de noms pour les propriétés pouvant être liées, l’identificateur de propriété pouvant être lié doit correspondre au nom de propriété spécifié dans la méthode Create et être suivi de « Property ».

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 EventNameProperty =
  BindableProperty.Create ("EventName", typeof(string), typeof(EventToCommandBehavior), null);

Une instance BindableProperty nommée EventNameProperty de type string est créée. La propriété appartient à la classe EventToCommandBehavior et a pour valeur par défaut null.

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.
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 EventName :

public string EventName
{
  get { return (string)GetValue (EventNameProperty); }
  set { SetValue (EventNameProperty, 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:EventToCommandBehavior" ...>
  ...
</ContentPage>

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

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

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

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

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 change.

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

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
}

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

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, qui doit être géré par le développeur. 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 change.

Important

Le type BindableObject possède une méthode CoerceValue qui peut être appelée pour forcer une réévaluation de la valeur de son argument BindableProperty, en appelant son rappel de forçage de valeur.

Les rappels de valeurs coerce sont utilisés pour forcer une réévaluation d’une propriété pouvant être liée lorsque la valeur de la propriété change. 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(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);
}

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 Func pouvez l’utiliser pour initialiser la valeur par défaut d’une propriété pouvant être liée, comme illustré dans l’exemple de code suivant :

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

Le defaultValueCreator paramètre est défini sur un Func qui appelle la Device.GetNamedSize méthode pour retourner une double valeur qui représente la taille nommée de la police utilisée sur une Label plateforme native.