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

Download Sample Télécharger l’exemple

Les propriétés pouvant être liées étendent la fonctionnalité de propriété CLR en sauvegardeant une propriété avec un BindableProperty type, au lieu de sauvegarder une propriété avec un champ. L’objectif des propriétés pouvant être liées consiste à 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, une validation des 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 :

  • Agissant comme une propriété cible valide pour la liaison de données.
  • Définition de 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é.
  • Validation de la valeur de la propriété.
  • Surveillance des modifications de propriété.

Les exemples de Xamarin.Forms propriétés pouvant être liées incluent Label.Text, Button.BorderRadiuset StackLayout.Orientation. Chaque propriété pouvant être liée a un champ de type BindableProperty correspondant public static readonly 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é correspondant pour la Label.Text propriété 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 BindableProperty instance avec l’une des surcharges de BindableProperty.Create méthode.
  2. Définissez les accesseurs de propriétés pour l’instance BindableProperty .

Toutes les BindableProperty instances 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 BindableProperty 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 BindableProperty instance, la classe contenante doit dériver de la BindableObject classe. Toutefois, la BindableObject classe est élevée dans la hiérarchie de classes, de sorte que la majorité des classes utilisées pour les fonctionnalités d’interface utilisateur prennent en charge les propriétés pouvant être liées.

Une propriété pouvant être liée peut être créée en déclarant une public static readonly propriété de type BindableProperty. La propriété pouvant être liée doit être définie sur la valeur retournée de l’une BindableProperty.Create des surcharges de méthode. La déclaration doit se trouver dans le corps de BindableObject la classe dérivée, mais en dehors de toutes les définitions de membre.

Au minimum, un identificateur doit être spécifié lors de la création d’un BindableProperty, ainsi que des 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 lorsqu’elle n’est pas définie et qu’elle peut être différente de la valeur par défaut du type de la propriété. La valeur par défaut est restaurée lorsque la ClearValue méthode est appelée sur la propriété pouvant être liée.

Important

La convention d’affectation de noms pour les propriétés pouvant être liées est que l’identificateur de propriété pouvant être lié doit correspondre au nom de la propriété spécifié dans la Create méthode, avec « Property » ajouté à celui-ci.

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

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

Si vous le souhaitez, lors de la création d’une BindableProperty instance, les paramètres suivants peuvent être spécifiés :

  • Mode de liaison. Il est utilisé pour spécifier la direction dans laquelle la valeur de propriété change se propage. En mode de liaison par défaut, les modifications se propagent de la source à la cible.
  • Délégué de validation qui sera appelé lorsque la valeur de propriété est définie. Pour plus d’informations, consultez Rappels de validation.
  • Délégué modifié de propriété qui sera appelé lorsque la valeur de la propriété a changé. Pour plus d’informations, consultez Détecter les modifications de propriété.
  • Délégué de modification de propriété qui sera appelé lorsque la valeur de la propriété change. Ce délégué a la même signature que le délégué modifié par la propriété.
  • Délégué de valeur coerce qui sera appelé lorsque la valeur de propriété a changé. Pour plus d’informations, consultez rappels de valeur de coerce.
  • Utilisé Func pour initialiser une valeur de propriété par défaut. Pour plus d’informations, consultez Créer une valeur par défaut avec un Func.

Créer des accesseurs

Les accesseurs de propriété sont requis pour 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. Cela peut être obtenu en appelant la GetValue méthode, en passant l’identificateur de propriété pouvant être lié sur lequel obtenir la valeur, puis en faisant passer le résultat au type requis. L’accesseur Set doit définir la valeur de la propriété pouvant être liée correspondante. Cela peut être obtenu en appelant la SetValue méthode, en passant l’identificateur de propriété pouvant être lié sur lequel définir la valeur et la valeur à définir.

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

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, elle peut être consommée à partir de XAML ou de code. En XAML, cela est obtenu en déclarant un espace de noms avec un préfixe, avec la déclaration d’espace de noms indiquant le nom de l’espace de noms CLR, et é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, qui est 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 EventName propriété pouvant être liée, 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 BindableProperty instance, plusieurs paramètres facultatifs peuvent être définis pour activer des scénarios de propriété pouvant être liés avancés. Cette section explore ces scénarios.

Détecter les modifications de propriété

Une static méthode de rappel modifiée par propriété peut être inscrite avec une propriété pouvant être liée en spécifiant le propertyChanged paramètre de la BindableProperty.Create méthode. 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 EventName propriété pouvant être liée inscrit la OnEventNameChanged méthode en tant que méthode de rappel modifiée par propriété :

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 modifiée par la propriété, le BindableObject paramètre est utilisé pour indiquer quelle instance de la classe propriétaire a signalé une modification et les valeurs des deux object paramètres représentent les anciennes et nouvelles valeurs de la propriété pouvant être liée.

Rappels de validation

Une static méthode de rappel de validation peut être inscrite avec une propriété pouvant être liée en spécifiant le validateValue paramètre de la BindableProperty.Create méthode. 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 Angle propriété pouvant être liée inscrit la IsValidValue méthode comme 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 déclenchée si un rappel de validation retourne false, qui doit être géré par le développeur. Une utilisation classique d’une méthode de rappel de validation limite les valeurs d’entiers ou de doubles lorsque la propriété pouvant être liée est définie. Par exemple, la IsValidValue méthode vérifie que la valeur de la propriété est comprise double entre 0 et 360.

Rappels de valeur de coerce

Une static méthode de rappel de valeur coerce peut être inscrite avec une propriété pouvant être liée en spécifiant le coerceValue paramètre de la BindableProperty.Create méthode. 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 BindableObject type a une CoerceValue méthode qui peut être appelée pour forcer une reévaluation de la valeur de son BindableProperty argument, en appelant son rappel de valeur coerce.

Les rappels de valeur 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 valeur coerce peut être utilisé pour vous 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 Angle propriété pouvant être liée inscrit la CoerceAngle méthode comme méthode de rappel de valeur coerce :

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 CoerceAngle méthode vérifie la valeur de la MaximumAngle propriété et si la Angle valeur de la propriété est supérieure à celle-ci, elle coédise la valeur à la MaximumAngle valeur de la propriété. En outre, lorsque la MaximumAngle propriété modifie le rappel de valeur de coerce est appelé sur la Angle propriété en appelant la CoerceValue méthode.

Créer une valeur par défaut avec un Func

Il Func peut être utilisé 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 renvoyer une double valeur qui représente la taille nommée de la police utilisée sur une Label plateforme native.