Propiedades enlazablesBindable Properties

Descargar ejemplo descargar el ejemploDownload Sample Download the sample

En Xamarin.Forms, la funcionalidad de las propiedades de common language runtime (CLR) se extiende por las propiedades enlazables. Una propiedad enlazable es un tipo especial de propiedad, donde el valor de propiedad se realiza el seguimiento por el sistema de propiedades de Xamarin.Forms. Este artículo proporciona una introducción a las propiedades enlazables y muestra cómo crear y consumirlos.In Xamarin.Forms, the functionality of common language runtime (CLR) properties is extended by bindable properties. A bindable property is a special type of property, where the property's value is tracked by the Xamarin.Forms property system. This article provides an introduction to bindable properties, and demonstrates how to create and consume them.

Información generalOverview

Propiedades enlazables amplían la funcionalidad de propiedad CLR de seguridad de una propiedad con un BindableProperty tipo, en lugar de una propiedad con un campo de respaldo.Bindable properties extend CLR property functionality by backing a property with a BindableProperty type, instead of backing a property with a field. El propósito de las propiedades enlazables es proporcionar un sistema de propiedades que admite el enlace de datos, estilos, plantillas y valores se establecen a través de relaciones de elementos primarios y secundarios.The purpose of bindable properties is to provide a property system that supports data binding, styles, templates, and values set through parent-child relationships. Además, las propiedades enlazables pueden proporcionar valores predeterminados, validación de los valores de propiedad y las devoluciones de llamada que supervisen los cambios de propiedad.In addition, bindable properties can provide default values, validation of property values, and callbacks that monitor property changes.

Las propiedades deben implementarse como propiedades enlazables para admitir una o varias de las siguientes características:Properties should be implemented as bindable properties to support one or more of the following features:

  • Que actúa como válido destino propiedad para el enlace de datos.Acting as a valid target property for data binding.
  • Establecer la propiedad a través de un estilo.Setting the property through a style.
  • Proporcionar un valor de propiedad predeterminado que es diferente del valor predeterminado para el tipo de la propiedad.Providing a default property value that's different from the default for the type of the property.
  • Validar el valor de la propiedad.Validating the value of the property.
  • Supervisión de los cambios de propiedad.Monitoring property changes.

Ejemplos de Xamarin.Forms que las propiedades enlazables Label.Text , Button.BorderRadius , y StackLayout.Orientation .Examples of Xamarin.Forms bindable properties include Label.Text, Button.BorderRadius, and StackLayout.Orientation. Cada propiedad enlazable le corresponde una public static readonly propiedad de tipo BindableProperty que se expone en la misma clase y que es el identificador de la propiedad enlazable.Each bindable property has a corresponding public static readonly property of type BindableProperty that is exposed on the same class and that is the identifier of the bindable property. Por ejemplo, el identificador de propiedad enlazable correspondiente para el Label.Text propiedad es Label.TextProperty .For example, the corresponding bindable property identifier for the Label.Text property is Label.TextProperty.

Creación y consumo de una propiedad enlazableCreating and Consuming a Bindable Property

El proceso de creación de una propiedad enlazable es como sigue:The process for creating a bindable property is as follows:

  1. Crear un BindableProperty instancia con uno de los BindableProperty.Create sobrecargas del método.Create a BindableProperty instance with one of the BindableProperty.Create method overloads.
  2. Definir descriptores de acceso de propiedad para el BindableProperty instancia.Define property accessors for the BindableProperty instance.

Tenga en cuenta que todos los BindableProperty instancias deben crearse en el subproceso de interfaz de usuario.Note that all BindableProperty instances must be created on the UI thread. Esto significa que sólo el código que se ejecuta en el subproceso de interfaz de usuario puede obtener o establecer el valor de una propiedad enlazable.This means that only code that runs on the UI thread can get or set the value of a bindable property. Sin embargo, BindableProperty instancias pueden tener acceso desde otros subprocesos por el cálculo de referencias para el subproceso de interfaz de usuario con el Device.BeginInvokeOnMainThread método.However, BindableProperty instances can be accessed from other threads by marshaling to the UI thread with the Device.BeginInvokeOnMainThread method.

Creación de una propiedadCreating a Property

Para crear un BindableProperty instancia, debe derivar la clase contenedora de la BindableObject clase.To create a BindableProperty instance, the containing class must derive from the BindableObject class. Sin embargo, la BindableObject clase es alta en la jerarquía de clases, por lo que la mayoría de las clases que se usa para las propiedades enlazables para compatibilidad con la funcionalidad de interfaz de usuario.However, the BindableObject class is high in the class hierarchy, so the majority of classes used for user interface functionality support bindable properties.

Se puede crear una propiedad enlazable declarando un public static readonly propiedad de tipo BindableProperty .A bindable property can be created by declaring a public static readonly property of type BindableProperty. La propiedad enlazable debe establecerse en el valor devuelto de uno de los BindableProperty.Create sobrecargas del método.The bindable property should be set to the returned value of one of the BindableProperty.Create method overloads. La declaración debe estar dentro del cuerpo de BindableObject clase derivada, pero fuera de las definiciones de miembros.The declaration should be within the body of BindableObject derived class, but outside of any member definitions.

Como mínimo, debe especificarse un identificador al crear un BindableProperty , junto con los parámetros siguientes:At a minimum, an identifier must be specified when creating a BindableProperty, along with the following parameters:

  • El nombre de la BindableProperty .The name of the BindableProperty.
  • Tipo de la propiedad.The type of the property.
  • El tipo del objeto propietario.The type of the owning object.
  • Valor predeterminado de la propiedad.The default value for the property. Esto garantiza que la propiedad siempre devuelve un valor determinado de forma predeterminada cuando no está establecido, y puede ser diferente del valor predeterminado para el tipo de la propiedad.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. El valor predeterminado será cuando restaura la ClearValue se llama al método en la propiedad enlazable.The default value will be restored when the ClearValue method is called on the bindable property.

El código siguiente muestra un ejemplo de una propiedad enlazable, con un identificador y los valores de los cuatro campos obligatorios: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);

Esto crea un BindableProperty instancia denominada EventName, del tipo string.This creates a BindableProperty instance named EventName, of type string. La propiedad pertenece a la EventToCommandBehavior clase y tiene un valor predeterminado de null.The property is owned by the EventToCommandBehavior class, and has a default value of null. La convención de nomenclatura para las propiedades enlazables es que el identificador de propiedad enlazable debe coincidir con el nombre de propiedad especificado en el Create método con "Property" anexado a él.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. Por lo tanto, en el ejemplo anterior, el identificador de propiedad enlazable es EventNameProperty.Therefore, in the example above, the bindable property identifier is EventNameProperty.

Si lo desea, al crear un BindableProperty de instancia, los siguientes parámetros se pueden especificar:Optionally, when creating a BindableProperty instance, the following parameters can be specified:

  • Modo de enlace.The binding mode. Esto se utiliza para especificar la dirección en la que se propaguen los cambios de valor de propiedad.This is used to specify the direction in which property value changes will propagate. En el modo de enlace predeterminada, los cambios se propaguen desde el origen a la destino.In the default binding mode, changes will propagate from the source to the target.
  • Un delegado de validación que se invocará cuando se establece el valor de propiedad.A validation delegate that will be invoked when the property value is set. Para obtener más información, consulte las devoluciones de llamada de validación.For more information, see Validation Callbacks.
  • Un delegado de cambio de propiedad que se invoca cuando ha cambiado el valor de propiedad.A property changed delegate that will be invoked when the property value has changed. Para obtener más información, consulte detectar los cambios de propiedad.For more information, see Detecting Property Changes.
  • Una propiedad de cambio de delegado que se invoca cuando cambia el valor de propiedad.A property changing delegate that will be invoked when the property value will change. Este delegado tiene la misma firma que el delegado de la propiedad ha cambiado.This delegate has the same signature as the property changed delegate.
  • Un delegado del valor de coerción que se invoca cuando ha cambiado el valor de propiedad.A coerce value delegate that will be invoked when the property value has changed. Para obtener más información, consulte devoluciones de llamada de valor de coerción.For more information, see Coerce Value Callbacks.
  • Un Func que se usa para inicializar un valor de propiedad predeterminado.A Func that's used to initialize a default property value. Para obtener más información, consulte creación de un valor predeterminado con un elemento Func.For more information, see Creating a Default Value with a Func.

Creación de los descriptores de accesoCreating Accessors

Los descriptores de acceso de propiedad deben usar la sintaxis de la propiedad para tener acceso a una propiedad enlazable.Property accessors are required to use property syntax to access a bindable property. El Get descriptor de acceso debe devolver el valor que se encuentra en la propiedad enlazable correspondiente.The Get accessor should return the value that's contained in the corresponding bindable property. Esto puede lograrse mediante una llamada a la GetValue método, pasando el identificador de propiedad enlazable en la que se va a obtener el valor y, a continuación, convertir el resultado al tipo requerido.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. El Set descriptor de acceso debe establecer el valor de la propiedad enlazable correspondiente.The Set accessor should set the value of the corresponding bindable property. Esto puede lograrse mediante una llamada a la SetValue método, pasando el identificador de propiedad enlazable en la que se va a establecer el valor y el valor que se va a establecer.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.

El ejemplo de código siguiente muestra los descriptores de acceso para el EventName propiedad enlazable:The following code example shows accessors for the EventName bindable property:

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

Consumo de una propiedad enlazableConsuming a Bindable Property

Una vez creada una propiedad enlazable, se puede consumir desde XAML o código.Once a bindable property has been created, it can be consumed from XAML or code. En XAML, esto se logra mediante la declaración de un espacio de nombres con un prefijo, con la declaración de espacio de nombres que indica el nombre del espacio de nombres CLR y, opcionalmente, un nombre de ensamblado.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. Para obtener más información, consulte los espacios de nombres XAML.For more information, see XAML Namespaces.

En el ejemplo de código siguiente se muestra un espacio de nombres XAML para un tipo personalizado que contiene una propiedad enlazable, que se define dentro del mismo ensamblado que el código de aplicación que se hace referencia al tipo personalizado: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 declaración de espacio de nombres se utiliza al establecer el EventName propiedad enlazable, como se muestra en el ejemplo de código XAML siguiente: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>

El código de C# equivalente se muestra en el ejemplo de código siguiente:The equivalent C# code is shown in the following code example:

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

Escenarios avanzadosAdvanced Scenarios

Al crear un BindableProperty de la instancia, hay una serie de parámetros opcionales que se pueden establecer para habilitar escenarios avanzados de propiedad enlazable.When creating a BindableProperty instance, there are a number of optional parameters that can be set to enable advanced bindable property scenarios. Esta sección explora estos escenarios.This section explores these scenarios.

Detección de cambios de propiedadDetecting Property Changes

Un static método de devolución de llamada de cambio de propiedad se puede registrar con una propiedad enlazable especificando el propertyChanged parámetro para el BindableProperty.Create método.A static property-changed callback method can be registered with a bindable property by specifying the propertyChanged parameter for the BindableProperty.Create method. El método de devolución de llamada especificada se invoca cuando cambia el valor de la propiedad enlazable.The specified callback method will be invoked when the value of the bindable property changes.

El siguiente ejemplo de código muestra cómo el EventName propiedad enlazable registra el OnEventNameChanged método como un método de devolución de llamada de cambio de propiedad: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
}

En el método de devolución de llamada de cambio de propiedad, el BindableObject parámetro se usa para indicar qué instancia de la clase propietaria informó de un cambio y los valores de los dos object parámetros representan los valores antiguos y nuevos de la propiedad enlazable.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.

Devoluciones de llamada de validaciónValidation Callbacks

Un static método de devolución de llamada de validación se puede registrar con una propiedad enlazable especificando el validateValue parámetro para el BindableProperty.Create método.A static validation callback method can be registered with a bindable property by specifying the validateValue parameter for the BindableProperty.Create method. Se invocará el método de devolución de llamada especificada cuando se establece el valor de la propiedad enlazable.The specified callback method will be invoked when the value of the bindable property is set.

El siguiente ejemplo de código muestra cómo el Angle propiedad enlazable registra el IsValidValue método como método de devolución de llamada de validación: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);
}

Las devoluciones de llamada de validación se proporcionan con un valor y debe devolver true si el valor es válido para la propiedad, de lo contrario false.Validation callbacks are provided with a value, and should return true if the value is valid for the property, otherwise false. Se producirá una excepción si una devolución de llamada de validación devuelve false, que debe controlarse por el desarrollador.An exception will be raised if a validation callback returns false, which should be handled by the developer. Un uso típico de un método de devolución de llamada de validación es restringir los valores de números enteros o dobles cuando se establece la propiedad enlazable.A typical use of a validation callback method is constraining the values of integers or doubles when the bindable property is set. Por ejemplo, el IsValidValue método comprueba que el valor de propiedad es un double dentro del intervalo de 0 a 360.For example, the IsValidValue method checks that the property value is a double within the range 0 to 360.

CoerceValue CallbacksCoerce Value Callbacks

Un static convertir el valor del método de devolución de llamada se puede registrar con una propiedad enlazable especificando el coerceValue parámetro para el BindableProperty.Create método.A static coerce value callback method can be registered with a bindable property by specifying the coerceValue parameter for the BindableProperty.Create method. El método de devolución de llamada especificada se invoca cuando cambia el valor de la propiedad enlazable.The specified callback method will be invoked when the value of the bindable property changes.

Las devoluciones de llamada se usan para forzar una reevaluación de una propiedad enlazable cuando cambia el valor de la propiedad de valor de coerción.Coerce value callbacks are used to force a reevaluation of a bindable property when the value of the property changes. Por ejemplo, puede utilizarse una devolución de llamada de valor de coerción para asegurarse de que el valor de una propiedad enlazable no es mayor que el valor de otra propiedad enlazable.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.

El siguiente ejemplo de código muestra cómo el Angle propiedad enlazable registra el CoerceAngle método como un método de devolución de llamada de valor de coerción: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);
...

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

El CoerceAngle método comprueba el valor de la MaximumAngle propiedad y si el Angle es mayor el valor de propiedad, convierte el valor en el MaximumAngle valor de propiedad.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.

Creación de un valor predeterminado con un elemento FuncCreating a Default Value with a Func

Un Func puede usarse para inicializar el valor predeterminado de una propiedad enlazable, como se muestra en el ejemplo de código siguiente: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));

El defaultValueCreator parámetro se establece en un Func que invoca la Device.GetNamedSize método devuelva un double que representa el nombre de tamaño para la fuente que se usa en un Label en la plataforma nativa.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.

ResumenSummary

En este artículo proporciona una introducción a las propiedades enlazables y se muestra cómo crear y consumirlos.This article provided an introduction to bindable properties, and demonstrated how to create and consume them. Una propiedad enlazable es un tipo especial de propiedad, donde el valor de propiedad se realiza el seguimiento por el sistema de propiedades de Xamarin.Forms.A bindable property is a special type of property, where the property's value is tracked by the Xamarin.Forms property system.