:::no-loc(Xamarin.Forms)::: Propriétés pouvant être liées:::no-loc(Xamarin.Forms)::: Bindable Properties

Télécharger l’exemple Télécharger l’exempleDownload Sample Download the sample

Les propriétés pouvant être liées étendent la fonctionnalité de propriété CLR en sauvegardant une propriété avec un BindableProperty type, au lieu de sauvegarder une propriété avec un champ.Bindable properties extend CLR property functionality by backing a property with a BindableProperty type, instead of backing a property with a field. L’objectif 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.The purpose of bindable properties is to provide a property system that supports data binding, styles, templates, and values set through parent-child relationships. En outre, les propriétés pouvant être liées peuvent fournir des valeurs par défaut, la validation des valeurs de propriété et les rappels qui surveillent les modifications de propriété.In addition, bindable properties can provide default values, validation of property values, and callbacks that monitor property changes.

Les propriétés doivent être implémentées en tant que propriétés pouvant être liées afin de prendre en charge une ou plusieurs des fonctionnalités suivantes :Properties should be implemented as bindable properties to support one or more of the following features:

  • Agissant comme une propriété cible valide pour la liaison de données.Acting as a valid target property for data binding.
  • Définition de la propriété à l’aide d’un style.Setting the property through a style.
  • En fournissant une valeur de propriété par défaut qui est différente de la valeur par défaut pour le type de la propriété.Providing a default property value that's different from the default for the type of the property.
  • Validation de la valeur de la propriété.Validating the value of the property.
  • Analyse des modifications des propriétés.Monitoring property changes.

Les exemples de :::no-loc(Xamarin.Forms)::: propriétés pouvant être liées sont notamment Label.Text , Button.BorderRadius et StackLayout.Orientation .Examples of :::no-loc(Xamarin.Forms)::: bindable properties include Label.Text, Button.BorderRadius, and StackLayout.Orientation. Chaque propriété pouvant être liée possède un public static readonly champ de type correspondant BindableProperty qui est exposé sur la même classe et qui est l’identificateur de la propriété pouvant être liée.Each bindable property has a corresponding public static readonly field of type BindableProperty that is exposed on the same class and that is the identifier of the bindable property. Par exemple, l’identificateur de propriété pouvant être lié correspondant à la Label.Text propriété est Label.TextProperty .For example, the corresponding bindable property identifier for the Label.Text property is Label.TextProperty.

Créer une propriété pouvant être liéeCreate a bindable property

Le processus de création d’une propriété pouvant être liée est le suivant :The process for creating a bindable property is as follows:

  1. Créez une BindableProperty instance de avec l’une des BindableProperty.Create surcharges de méthode.Create a BindableProperty instance with one of the BindableProperty.Create method overloads.
  2. Définissez les accesseurs de propriété pour l' BindableProperty instance.Define property accessors for the BindableProperty instance.

Toutes les BindableProperty instances doivent être créées sur le thread d’interface utilisateur.All BindableProperty instances must be created on the UI thread. 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.This means that only code that runs on the UI thread can get or set the value of a bindable property. Toutefois, BindableProperty les instances sont accessibles à partir d’autres threads en marshalant vers le thread d’interface utilisateur avec la Device.BeginInvokeOnMainThread méthode.However, BindableProperty instances can be accessed from other threads by marshaling to the UI thread with the Device.BeginInvokeOnMainThread method.

Créer une propriétéCreate a property

Pour créer une BindableProperty instance, la classe conteneur doit dériver de la BindableObject classe.To create a BindableProperty instance, the containing class must derive from the BindableObject class. Toutefois, la BindableObject classe est élevée dans la hiérarchie de classes, donc la majorité des classes utilisées pour les fonctionnalités de l’interface utilisateur prennent en charge les propriétés pouvant être liées.However, the BindableObject class is high in the class hierarchy, so the majority of classes used for user interface functionality support bindable properties.

Une propriété pouvant être liée peut être créée en déclarant une public static readonly propriété de type BindableProperty .A bindable property can be created by declaring a public static readonly property of type BindableProperty. La propriété pouvant être liée doit être définie sur la valeur retournée de l’un des [ BindableProperty.Create ] (XREF : :::no-loc(Xamarin.Forms)::: . BindableProperty. Create (System. String, System. type, System. type, System. Object, :::no-loc(Xamarin.Forms)::: . BindingMode, :::no-loc(Xamarin.Forms)::: . BindableProperty. ValidateValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangedDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangingDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CoerceValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CreateDefaultValueDelegate)) surcharges de la méthode.The bindable property should be set to the returned value of one of the BindableProperty.Create method overloads. La déclaration doit se trouver dans le corps de la BindableObject classe dérivée, mais en dehors de toutes les définitions de membre.The declaration should be within the body of BindableObject derived class, but outside of any member definitions.

Au minimum, un identificateur doit être spécifié lors de la création d’un BindableProperty , avec les paramètres suivants :At a minimum, an identifier must be specified when creating a BindableProperty, along with the following parameters:

  • Nom du BindableProperty .The name of the BindableProperty.
  • Type de la propriété.The type of the property.
  • Type de l’objet propriétaire.The type of the owning object.
  • Valeur par défaut de la propriété.The default value for the property. Cela garantit que la propriété retourne toujours une valeur par défaut particulière lorsqu’elle est non définie et qu’elle peut être différente de la valeur par défaut pour le type de la propriété.This ensures that the property always returns a particular default value when it is unset, and it can be different from the default value for the type of the property. La valeur par défaut est restaurée quand [ ClearValue ] (XREF : :::no-loc(Xamarin.Forms)::: . BindableObject. ClearValue ( :::no-loc(Xamarin.Forms)::: . BindableProperty)) est appelé sur la propriété pouvant être liée.The default value will be restored when the ClearValue method is called on the bindable property.

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 propriété spécifié dans la Create méthode, avec « propriété » ajoutée.The naming convention for bindable properties is that the bindable property identifier must match the property name specified in the Create method, with "Property" appended to it.

Le code suivant illustre un exemple de propriété pouvant être liée, avec un identificateur et des valeurs pour les quatre paramètres requis :The following code shows an example of a bindable property, with an identifier and values for the four required parameters:

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 .This creates a BindableProperty instance named EventNameProperty, of type string. La propriété appartient à la EventToCommandBehavior classe et a une valeur par défaut de null .The property is owned by the EventToCommandBehavior class, and has a default value of null.

Si vous le souhaitez, lors de la création d’une BindableProperty instance, vous pouvez spécifier les paramètres suivants :Optionally, when creating a BindableProperty instance, the following parameters can be specified:

  • Mode de liaison.The binding mode. Utilisé pour spécifier la direction dans laquelle les modifications de valeur de propriété sont propagées.This is used to specify the direction in which property value changes will propagate. Dans le mode de liaison par défaut, les modifications sont propagées de la source à la cible.In the default binding mode, changes will propagate from the source to the target.
  • Délégué de validation qui sera appelé lorsque la valeur de propriété est définie.A validation delegate that will be invoked when the property value is set. Pour plus d’informations, consultez rappels de validation.For more information, see Validation callbacks.
  • Délégué de propriété modifié qui sera appelé lorsque la valeur de propriété a été modifiée.A property changed delegate that will be invoked when the property value has changed. Pour plus d’informations, consultez détecter les modifications de propriété.For more information, see Detect property changes.
  • Délégué de modification de propriété qui sera appelé lorsque la valeur de propriété sera modifiée.A property changing delegate that will be invoked when the property value will change. Ce délégué a la même signature que le délégué property changed.This delegate has the same signature as the property changed delegate.
  • Délégué de valeur forcée qui sera appelé lorsque la valeur de propriété a été modifiée.A coerce value delegate that will be invoked when the property value has changed. Pour plus d’informations, consultez forçage des rappels de valeur.For more information, see Coerce value callbacks.
  • FuncUtilisé pour initialiser une valeur de propriété par défaut.A Func that's used to initialize a default property value. Pour plus d’informations, consultez créer une valeur par défaut avec un Func.For more information, see Create a default value with a Func.

Créer des accesseursCreate accessors

Les accesseurs de propriété sont requis pour utiliser la syntaxe de propriété pour accéder à une propriété pouvant être liée.Property accessors are required to use property syntax to access a bindable property. L' Get accesseur doit retourner la valeur contenue dans la propriété pouvant être liée correspondante.The Get accessor should return the value that's contained in the corresponding bindable property. Pour ce faire, vous pouvez appeler la [ GetValue ] (XREF : :::no-loc(Xamarin.Forms)::: . BindableObject. GetValue ( :::no-loc(Xamarin.Forms)::: . BindableProperty)), en passant l’identificateur de propriété pouvant être lié sur lequel obtenir la valeur, puis en effectuant un cast du résultat vers le type requis.This can be achieved by calling the GetValue method, passing in the bindable property identifier on which to get the value, and then casting the result to the required type. L' Set accesseur doit définir la valeur de la propriété pouvant être liée correspondante.The Set accessor should set the value of the corresponding bindable property. Pour ce faire, vous pouvez appeler la [ SetValue ] (XREF : :::no-loc(Xamarin.Forms)::: . BindableObject. SetValue ( :::no-loc(Xamarin.Forms)::: . BindableProperty, System. Object)), en passant l’identificateur de propriété pouvant être lié sur lequel définir la valeur, et la valeur à définir.This can be achieved by calling the SetValue method, passing in the bindable property identifier on which to set the value, and the value to set.

L’exemple de code suivant montre des accesseurs pour la EventName propriété pouvant être liée :The following code example shows accessors for the EventName bindable property:

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

Utiliser une propriété pouvant être liéeConsume a bindable property

Une fois qu’une propriété pouvant être liée a été créée, elle peut être consommée à partir du code XAML ou.Once a bindable property has been created, it can be consumed from XAML or 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 qui indique le nom de l’espace de noms CLR et, éventuellement, un nom d’assembly.In XAML, this is achieved by declaring a namespace with a prefix, with the namespace declaration indicating the CLR namespace name, and optionally, an assembly name. Pour plus d’informations, consultez espaces de noms XAML.For more information, see XAML Namespaces.

L’exemple de code suivant montre 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é :The following code example demonstrates a XAML namespace for a custom type that contains a bindable property, which is defined within the same assembly as the application code that's referencing the custom type:

<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 :The namespace declaration is used when setting the EventName bindable property, as demonstrated in the following XAML code example:

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

Le code C# équivalent est affiché dans l’exemple de code suivant :The equivalent C# code is shown in the following code example:

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

Scénarios avancésAdvanced scenarios

Lors de la création d’une BindableProperty instance, il existe un certain nombre de paramètres facultatifs qui peuvent être définis pour activer les scénarios de propriété avancés pouvant être liés.When creating a BindableProperty instance, there are a number of optional parameters that can be set to enable advanced bindable property scenarios. Cette section explore ces scénarios.This section explores these scenarios.

Détecter les modifications de propriétéDetect property changes

Une static méthode de rappel de propriété modifiée peut être inscrite avec une propriété pouvant être liée en spécifiant le propertyChanged paramètre pour [ BindableProperty.Create ] (XREF : :::no-loc(Xamarin.Forms)::: . BindableProperty. Create (System. String, System. type, System. type, System. Object, :::no-loc(Xamarin.Forms)::: . BindingMode, :::no-loc(Xamarin.Forms)::: . BindableProperty. ValidateValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangedDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangingDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CoerceValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CreateDefaultValueDelegate)).A static property-changed callback method can be registered with a bindable property by specifying the propertyChanged parameter for the BindableProperty.Create method. La méthode de rappel spécifiée sera appelée lorsque la valeur de la propriété pouvant être liée sera modifiée.The specified callback method will be invoked when the value of the bindable property changes.

L’exemple de code suivant montre comment la EventName propriété pouvant être liée enregistre la OnEventNameChanged méthode en tant que méthode de rappel de modification de propriété :The following code example shows how the EventName bindable property registers the OnEventNameChanged method as a property-changed callback method:

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 modification de propriété, le BindableObject paramètre est utilisé pour désigner l’instance de la classe propriétaire qui 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.In the property-changed callback method, the BindableObject parameter is used to denote which instance of the owning class has reported a change, and the values of the two object parameters represent the old and new values of the bindable property.

Rappels de validationValidation callbacks

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 pour [ BindableProperty.Create ] (XREF : :::no-loc(Xamarin.Forms)::: . BindableProperty. Create (System. String, System. type, System. type, System. Object, :::no-loc(Xamarin.Forms)::: . BindingMode, :::no-loc(Xamarin.Forms)::: . BindableProperty. ValidateValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangedDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangingDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CoerceValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CreateDefaultValueDelegate)).A static validation callback method can be registered with a bindable property by specifying the validateValue parameter for the BindableProperty.Create method. La méthode de rappel spécifiée sera appelée lorsque la valeur de la propriété pouvant être liée est définie.The specified callback method will be invoked when the value of the bindable property is set.

L’exemple de code suivant montre comment la Angle propriété pouvant être liée enregistre la IsValidValue méthode comme une méthode de rappel de validation :The following code example shows how the Angle bindable property registers the IsValidValue method as a validation callback method:

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 .Validation callbacks are provided with a value, and should return true if the value is valid for the property, otherwise false. Une exception est levée si un rappel de validation est retourné false , ce qui doit être géré par le développeur.An exception will be raised if a validation callback returns false, which should be handled by the developer. Une utilisation classique d’une méthode de rappel de validation consiste à contraindre les valeurs des entiers ou des valeurs de type double lorsque la propriété pouvant être liée est définie.A typical use of a validation callback method is constraining the values of integers or doubles when the bindable property is set. Par exemple, la IsValidValue méthode vérifie que la valeur de la propriété est double comprise entre 0 et 360.For example, the IsValidValue method checks that the property value is a double within the range 0 to 360.

Forcer les rappels de valeurCoerce value callbacks

Une static méthode de rappel de valeur forcée peut être inscrite avec une propriété pouvant être liée en spécifiant le coerceValue paramètre pour [ BindableProperty.Create ] (XREF : :::no-loc(Xamarin.Forms)::: . BindableProperty. Create (System. String, System. type, System. type, System. Object, :::no-loc(Xamarin.Forms)::: . BindingMode, :::no-loc(Xamarin.Forms)::: . BindableProperty. ValidateValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangedDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. BindingPropertyChangingDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CoerceValueDelegate, :::no-loc(Xamarin.Forms)::: . BindableProperty. CreateDefaultValueDelegate)).A static coerce value callback method can be registered with a bindable property by specifying the coerceValue parameter for the BindableProperty.Create method. La méthode de rappel spécifiée sera appelée lorsque la valeur de la propriété pouvant être liée sera modifiée.The specified callback method will be invoked when the value of the bindable property changes.

Important

Le BindableObject type a une CoerceValue méthode qui peut être appelée pour forcer une réévaluation de la valeur de son BindableProperty argument, en appelant son rappel de valeur forcée.The BindableObject type has a CoerceValue method that can be called to force a reevaluation of the value of its BindableProperty argument, by invoking its coerce value callback.

Les rappels de valeur forcée sont utilisés pour forcer une réévaluation d’une propriété pouvant être liée lorsque la valeur de la propriété change.Coerce value callbacks are used to force a reevaluation of a bindable property when the value of the property changes. Par exemple, un rappel de valeur forcée 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.For example, a coerce value callback can be used to ensure that the value of one bindable property is not greater than the value of another bindable property.

L’exemple de code suivant montre comment la Angle propriété pouvant être liée inscrit la CoerceAngle méthode en tant que méthode de rappel de valeur forcée :The following code example shows how the Angle bindable property registers the CoerceAngle method as a coerce value callback method:

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 propriété est supérieure à, elle convertit la valeur en MaximumAngle valeur de propriété.The CoerceAngle method checks the value of the MaximumAngle property, and if the Angle property value is greater than it, it coerces the value to the MaximumAngle property value. En outre, lorsque la MaximumAngle propriété change, le rappel de la valeur forcée est appelé sur la Angle propriété en appelant la CoerceValue méthode.In addition, when the MaximumAngle property changes the coerce value callback is invoked on the Angle property by calling the CoerceValue method.

Créer une valeur par défaut avec un FuncCreate a default value with a Func

Un 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 :A Func can be used to initialize the default value of a bindable property, as demonstrated in the following code example:

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 [ Device.GetNamedSize ] (XREF : :::no-loc(Xamarin.Forms)::: . Device. GetNamedSize ( :::no-loc(Xamarin.Forms)::: . NamedSize, System. type)) pour retourner un double qui représente la taille nommée de la police utilisée sur Label sur la plateforme native.The defaultValueCreator parameter is set to a Func that invokes the Device.GetNamedSize method to return a double that represents the named size for the font that is used on a Label on the native platform.