Proprietà associabiliBindable Properties

Scaricare l'esempio scaricare l'esempioDownload Sample Download the sample

In xamarin. Forms, la funzionalità delle proprietà di common language runtime (CLR) viene estesa dalla proprietà associabili. Una proprietà associabile è un tipo speciale di proprietà, in cui il valore della proprietà viene rilevato dal sistema di proprietà di xamarin. Forms. Questo articolo viene fornita un'introduzione alle proprietà associabile e viene illustrato come creare e il loro uso.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.

PanoramicaOverview

Proprietà associabili estendere la funzionalità delle proprietà CLR eseguendo il backup di una proprietà con un BindableProperty tipo, invece di eseguire il backup di una proprietà con un campo.Bindable properties extend CLR property functionality by backing a property with a BindableProperty type, instead of backing a property with a field. Lo scopo di proprietà associabili consiste nel fornire un sistema di proprietà che supporta l'associazione dati, stili, modelli e i valori impostati tramite relazioni padre-figlio.The purpose of bindable properties is to provide a property system that supports data binding, styles, templates, and values set through parent-child relationships. Inoltre, le proprietà associabili possono fornire valori predefiniti, convalida dei valori delle proprietà e i callback che consentono di monitorare le modifiche alle proprietà.In addition, bindable properties can provide default values, validation of property values, and callbacks that monitor property changes.

Le proprietà devono essere implementate come proprietà associabile per supportare uno o più delle seguenti funzionalità:Properties should be implemented as bindable properties to support one or more of the following features:

  • Funge da un oggetto valido destinazione proprietà per il data binding.Acting as a valid target property for data binding.
  • Impostazione della proprietà tramite un stile.Setting the property through a style.
  • Fornire un valore di proprietà predefinite che è diverso da quello predefinito per il tipo della proprietà.Providing a default property value that's different from the default for the type of the property.
  • La convalida del valore della proprietà.Validating the value of the property.
  • Monitoraggio delle modifiche di proprietà.Monitoring property changes.

Esempi di xamarin. Forms proprietà associabili Label.Text , Button.BorderRadius , e StackLayout.Orientation .Examples of Xamarin.Forms bindable properties include Label.Text, Button.BorderRadius, and StackLayout.Orientation. Ogni proprietà associabili ha un corrispondente public static readonly vlastnosti typu BindableProperty esposto nella stessa classe e che è l'identificatore della proprietà associabile.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. Ad esempio, l'identificatore della proprietà associabile corrispondente per il Label.Text proprietà viene Label.TextProperty .For example, the corresponding bindable property identifier for the Label.Text property is Label.TextProperty.

Creazione e l'utilizzo di una proprietà associabileCreating and Consuming a Bindable Property

Il processo per la creazione di una proprietà associabile è come segue:The process for creating a bindable property is as follows:

  1. Creare un BindableProperty istanza con uno del BindableProperty.Create overload del metodo.Create a BindableProperty instance with one of the BindableProperty.Create method overloads.
  2. Definire le funzioni di accesso di proprietà per il BindableProperty istanza.Define property accessors for the BindableProperty instance.

Si noti che tutti i BindableProperty istanze devono essere create nel thread UI.Note that all BindableProperty instances must be created on the UI thread. Ciò significa che solo il codice viene eseguito sul thread dell'interfaccia utente può ottenere o impostare il valore di una proprietà associabile.This means that only code that runs on the UI thread can get or set the value of a bindable property. Tuttavia BindableProperty istanze sono accessibili da altri thread effettuando il marshalling al thread UI con la Device.BeginInvokeOnMainThread (metodo).However, BindableProperty instances can be accessed from other threads by marshaling to the UI thread with the Device.BeginInvokeOnMainThread method.

Creazione di una proprietàCreating a Property

Per creare un BindableProperty istanza, la classe contenitore deve derivare dal BindableObject classe.To create a BindableProperty instance, the containing class must derive from the BindableObject class. Tuttavia, il BindableObject classe è elevata nella gerarchia delle classi, in modo che la maggior parte delle classi usato per la proprietà associabile supporto funzionalità dell'interfaccia utente.However, the BindableObject class is high in the class hierarchy, so the majority of classes used for user interface functionality support bindable properties.

Può creare una proprietà associabile dichiarando una public static readonly vlastnosti typu BindableProperty .A bindable property can be created by declaring a public static readonly property of type BindableProperty. Le proprietà associabili deve essere impostata sul valore restituito di una delle BindableProperty.Create overload del metodo.The bindable property should be set to the returned value of one of the BindableProperty.Create method overloads. La dichiarazione deve essere all'interno del corpo della BindableObject derivato (classe), ma di fuori di qualsiasi definizione del membro.The declaration should be within the body of BindableObject derived class, but outside of any member definitions.

Come minimo, un identificatore deve essere specificato durante la creazione di un BindableProperty , insieme ai parametri seguenti:At a minimum, an identifier must be specified when creating a BindableProperty, along with the following parameters:

  • Il nome del BindableProperty .The name of the BindableProperty.
  • Tipo della proprietà.The type of the property.
  • Il tipo dell'oggetto.The type of the owning object.
  • Il valore predefinito per la proprietà.The default value for the property. Ciò garantisce che la proprietà restituisce sempre un valore predefinito specifico quando è impostato e può essere diverso da quello predefinito per il tipo della proprietà.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. Il valore predefinito sarà ripristinato quando la ClearValue viene chiamato sulla proprietà associabili.The default value will be restored when the ClearValue method is called on the bindable property.

Il codice seguente viene illustrato un esempio di una proprietà associabile, con un identificatore e i valori per i quattro parametri obbligatori: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);

Ciò consente di creare un BindableProperty istanza denominata EventName, di tipo string.This creates a BindableProperty instance named EventName, of type string. La proprietà è di proprietà di EventToCommandBehavior classi e ha un valore predefinito di null.The property is owned by the EventToCommandBehavior class, and has a default value of null. La convenzione di denominazione per le proprietà associabili è che l'identificatore di proprietà associabili deve corrispondere al nome di proprietà specificato nella Create con "Property" aggiunto a tale metodo.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. Pertanto, nell'esempio precedente, è l'identificatore della proprietà associabile EventNameProperty.Therefore, in the example above, the bindable property identifier is EventNameProperty.

Facoltativamente, durante la creazione di un BindableProperty dell'istanza, di seguito è possibile specificare parametri:Optionally, when creating a BindableProperty instance, the following parameters can be specified:

  • La modalità di associazione.The binding mode. Ciò consente di specificare la direzione in cui verranno propagato modifiche dei valori di proprietà.This is used to specify the direction in which property value changes will propagate. Nella modalità di associazione predefinita, le modifiche si propaghino dal origine per il destinazione.In the default binding mode, changes will propagate from the source to the target.
  • Un delegato di convalida che verrà richiamato quando il valore della proprietà è impostato.A validation delegate that will be invoked when the property value is set. Per altre informazioni, vedere i callback di convalida.For more information, see Validation Callbacks.
  • Delegato che verrà richiamato quando è stato modificato il valore della proprietà modificata una proprietà.A property changed delegate that will be invoked when the property value has changed. Per altre informazioni, vedere rilevamento di modifiche alle proprietà.For more information, see Detecting Property Changes.
  • Una proprietà modifica delegato che verrà richiamato quando il valore della proprietà verrà modificato.A property changing delegate that will be invoked when the property value will change. Questo delegato ha la stessa firma del delegato di proprietà modificata.This delegate has the same signature as the property changed delegate.
  • Un delegato di valore soggetti a coercizione che verrà richiamato quando è stato modificato il valore della proprietà.A coerce value delegate that will be invoked when the property value has changed. Per altre informazioni, vedere i callback di valori soggetti a coercizione.For more information, see Coerce Value Callbacks.
  • Oggetto Func che viene usato per inizializzare un valore di proprietà predefinito.A Func that's used to initialize a default property value. Per altre informazioni, vedere creazione di un valore predefinito con un Func.For more information, see Creating a Default Value with a Func.

Creazione di funzioni di accessoCreating Accessors

Le funzioni di accesso di proprietà sono necessarie per usare la sintassi di proprietà per accedere a una proprietà associabile.Property accessors are required to use property syntax to access a bindable property. Il Get della funzione di accesso deve restituire il valore contenuto nella proprietà associabili corrispondente.The Get accessor should return the value that's contained in the corresponding bindable property. Ciò può essere ottenuto chiamando il GetValue (metodo), passando l'identificatore di proprietà associabili su cui ottenere il valore e quindi esegue il cast del risultato per il tipo richiesto.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. Il Set della funzione di accesso deve impostare il valore della proprietà associabile corrispondente.The Set accessor should set the value of the corresponding bindable property. Ciò può essere ottenuto chiamando il SetValue metodo, passando l'identificatore della proprietà associabile per cui impostare il valore e il valore da impostare.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.

Esempio di codice seguente mostra le funzioni di accesso per il EventName proprietà associabili:The following code example shows accessors for the EventName bindable property:

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

Utilizzo di una proprietà associabileConsuming a Bindable Property

Dopo aver creata una proprietà associabile, può essere utilizzato dal codice o XAML.Once a bindable property has been created, it can be consumed from XAML or code. In XAML, ciò si ottiene con la dichiarazione di uno spazio dei nomi con un prefisso con la dichiarazione dello spazio dei nomi che indica il nome dello spazio dei nomi CLR e, facoltativamente, un nome di 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. Per altre informazioni, vedere spazi dei nomi XAML.For more information, see XAML Namespaces.

L'esempio di codice seguente illustra uno spazio dei nomi XAML per un tipo personalizzato che contiene una proprietà associabile, che viene definita nello stesso assembly del codice dell'applicazione che fa riferimento al tipo personalizzato: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 dichiarazione dello spazio dei nomi viene usata quando si impostano le EventName proprietà associabile, come illustrato nell'esempio di codice XAML seguente: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>

Il codice C# equivalente è visualizzato nell'esempio seguente:The equivalent C# code is shown in the following code example:

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

Scenari avanzatiAdvanced Scenarios

Quando si crea una BindableProperty dell'istanza, esistono una serie di parametri facoltativi che è possibile impostare per abilitare scenari avanzati di proprietà associabili.When creating a BindableProperty instance, there are a number of optional parameters that can be set to enable advanced bindable property scenarios. Questa sezione vengono illustrati questi scenari.This section explores these scenarios.

Rilevamento delle modifiche di proprietàDetecting Property Changes

Oggetto static metodo di callback di modifica della proprietà può essere registrata con una proprietà associabile, specificando le propertyChanged parametro per il BindableProperty.Create (metodo).A static property-changed callback method can be registered with a bindable property by specifying the propertyChanged parameter for the BindableProperty.Create method. Verrà richiamato il metodo di callback specificato quando cambia il valore della proprietà associabile.The specified callback method will be invoked when the value of the bindable property changes.

Nell'esempio di codice riportato di seguito viene illustrato come la EventName registri di proprietà associabili il OnEventNameChanged metodo come metodo di callback di modifica delle proprietà: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
}

Nel metodo di callback di modifica delle proprietà, il BindableObject parametro viene usato per indicare quale istanza della classe di appartenenza ha segnalato una modifica e i valori dei due object parametri rappresentano i valori vecchi e nuovi di la proprietà associabile.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.

Callback di convalidaValidation Callbacks

Oggetto static metodo di callback di convalida può essere registrata con una proprietà associabile, specificando le validateValue parametro per il BindableProperty.Create (metodo).A static validation callback method can be registered with a bindable property by specifying the validateValue parameter for the BindableProperty.Create method. Verrà richiamato il metodo di callback specificato quando è impostato il valore della proprietà associabile.The specified callback method will be invoked when the value of the bindable property is set.

Nell'esempio di codice riportato di seguito viene illustrato come la Angle registri di proprietà associabili il IsValidValue metodo come metodo di callback di convalida: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);
}

I callback di convalida vengono forniti con un valore e deve restituire true se il valore è valido per la proprietà, in caso contrario false.Validation callbacks are provided with a value, and should return true if the value is valid for the property, otherwise false. Verrà generata un'eccezione se un callback di convalida restituisce false, che deve essere gestita dallo sviluppatore.An exception will be raised if a validation callback returns false, which should be handled by the developer. Un tipico utilizzo di un metodo di callback di convalida è vincolare i valori di integer o Double quando è impostata la proprietà associabile.A typical use of a validation callback method is constraining the values of integers or doubles when the bindable property is set. Ad esempio, il IsValidValue metodo controlla che il valore della proprietà è un double all'interno dell'intervallo da 0 a 360.For example, the IsValidValue method checks that the property value is a double within the range 0 to 360.

I callback di valori soggetti a coercizioneCoerce Value Callbacks

Oggetto static valori soggetti a coercizione metodo di callback può essere registrata con una proprietà associabile, specificando le coerceValue parametro per il BindableProperty.Create (metodo).A static coerce value callback method can be registered with a bindable property by specifying the coerceValue parameter for the BindableProperty.Create method. Verrà richiamato il metodo di callback specificato quando cambia il valore della proprietà associabile.The specified callback method will be invoked when the value of the bindable property changes.

Valore di callback vengono usati per forzare una rivalutazione di una proprietà associabile quando cambia il valore della proprietà vengono assegnati forzatamente.Coerce value callbacks are used to force a reevaluation of a bindable property when the value of the property changes. Ad esempio, un callback di soggetti a coercizione del valore è utilizzabile per assicurarsi che il valore di una proprietà associabile non sia maggiore del valore di un'altra proprietà associabile.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.

Nell'esempio di codice riportato di seguito viene illustrato come la Angle registra la proprietà associabile il CoerceAngle metodo come metodo di callback soggetti a coercizione valore: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;
}

Il CoerceAngle metodo controlla il valore della MaximumAngle proprietà e, se il Angle è maggiore rispetto al valore della proprietà, assegna il valore per il MaximumAngle valore della proprietà.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.

Creazione di un valore predefinito con una funzioneCreating a Default Value with a Func

Oggetto Func può essere utilizzato per inizializzare il valore predefinito di una proprietà associabile, come illustrato nell'esempio di codice seguente: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));

Il defaultValueCreator parametro è impostato su un Func che richiama la Device.GetNamedSize metodo restituisca un double che rappresenta la dimensione denominata per il tipo di carattere utilizzato in un Label sulla piattaforma 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.

RiepilogoSummary

In questo articolo ha presentato proprietà associabili ed è stato illustrato come creare e il loro uso.This article provided an introduction to bindable properties, and demonstrated how to create and consume them. Una proprietà associabile è un tipo speciale di proprietà, in cui il valore della proprietà viene rilevato dal sistema di proprietà di xamarin. Forms.A bindable property is a special type of property, where the property's value is tracked by the Xamarin.Forms property system.