Привязываемые свойстваBindable Properties

Загрузить образец загрузить примерDownload Sample Download the sample

В Xamarin.Forms функциональные возможности параметров среды выполнения (CLR) расширен с помощью свойства связывания. Может быть привязано — это специальный тип свойства, где значение свойства отслеживается системой свойств Xamarin.Forms. В этой статье содержатся вводные привязываемые свойства, а также показано, как создавать и использовать их.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.

ОбзорOverview

Привязываемые свойства расширяют функциональные возможности свойства CLR, связывание свойства с BindableProperty типа, не связывание свойства с полем.Bindable properties extend CLR property functionality by backing a property with a BindableProperty type, instead of backing a property with a field. Привязываемые свойства служит для предоставления системы свойств, который поддерживает привязку данных, стили, шаблоны и значения, заданные через родительско дочерних отношений.The purpose of bindable properties is to provide a property system that supports data binding, styles, templates, and values set through parent-child relationships. Кроме того привязываемые свойства можно указать значения по умолчанию, проверку значений свойств и обратных вызовов, отслеживающих изменения свойств.In addition, bindable properties can provide default values, validation of property values, and callbacks that monitor property changes.

Свойства должны быть реализованы как привязываемые свойства должно поддерживать одну или несколько из следующих компонентов:Properties should be implemented as bindable properties to support one or more of the following features:

  • Выступает в качестве допустимого целевой свойство для привязки данных.Acting as a valid target property for data binding.
  • Задание свойства с помощью стиля.Setting the property through a style.
  • Предоставление значением свойства по умолчанию, который отличается от по умолчанию для типа свойства.Providing a default property value that's different from the default for the type of the property.
  • Проверка значения свойства.Validating the value of the property.
  • Мониторинг изменений свойств.Monitoring property changes.

Примеры Xamarin.Forms привязываемые свойства Label.Text , Button.BorderRadius , и StackLayout.Orientation .Examples of Xamarin.Forms bindable properties include Label.Text, Button.BorderRadius, and StackLayout.Orientation. Каждое свойство привязки имеет соответствующий public static readonly свойство типа BindableProperty , который предоставляется для одного класса и является идентификатором связываемые свойства.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. Например, соответствующий идентификатор свойство, используемое для Label.Text свойство Label.TextProperty .For example, the corresponding bindable property identifier for the Label.Text property is Label.TextProperty.

Создание и использование может быть привязаноCreating and Consuming a Bindable Property

Процесс создания может быть привязано выглядит следующим образом:The process for creating a bindable property is as follows:

  1. Создание BindableProperty экземпляра с одним из BindableProperty.Create перегрузок метода.Create a BindableProperty instance with one of the BindableProperty.Create method overloads.
  2. Определять методы доступа свойств для BindableProperty экземпляра.Define property accessors for the BindableProperty instance.

Обратите внимание, что все BindableProperty экземпляры должны создаваться в потоке пользовательского интерфейса.Note that all BindableProperty instances must be created on the UI thread. Это означает, что только код, который выполняется в потоке пользовательского интерфейса можно получить или задать значение может быть привязано.This means that only code that runs on the UI thread can get or set the value of a bindable property. Тем не менее BindableProperty экземпляров может осуществляться из других потоков маршалинг в поток пользовательского интерфейса с помощью Device.BeginInvokeOnMainThread метод.However, BindableProperty instances can be accessed from other threads by marshaling to the UI thread with the Device.BeginInvokeOnMainThread method.

Создание свойстваCreating a Property

Чтобы создать BindableProperty экземпляра, содержащего класса должен быть производным от BindableObject класса.To create a BindableProperty instance, the containing class must derive from the BindableObject class. Тем не менее BindableObject класс высокого уровня в иерархии классов, поэтому большинство классов, используемый для привязки свойств поддержки функциональные возможности пользовательского интерфейса.However, the BindableObject class is high in the class hierarchy, so the majority of classes used for user interface functionality support bindable properties.

Может быть привязано могут создаваться путем объявления public static readonly свойство типа BindableProperty .A bindable property can be created by declaring a public static readonly property of type BindableProperty. Возвращаемое значение одного из задается свойство, используемое BindableProperty.Create перегрузок метода.The bindable property should be set to the returned value of one of the BindableProperty.Create method overloads. Объявление должно быть в теле BindableObject производного класса, но вне определения любого из членов.The declaration should be within the body of BindableObject derived class, but outside of any member definitions.

Как минимум, идентификатор должен быть указан при создании BindableProperty , а также следующие параметры:At a minimum, an identifier must be specified when creating a BindableProperty, along with the following parameters:

  • Имя BindableProperty .The name of the BindableProperty.
  • Тип свойства.The type of the property.
  • Тип объекта-владельца.The type of the owning object.
  • Значение по умолчанию для свойства.The default value for the property. Это гарантирует, что свойство всегда возвращает значение определенного по умолчанию, если оно не установлено, и он может отличаться от значения по умолчанию для типа свойства.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. Значение по умолчанию будут восстановлены при ClearValue на свойство, используемое вызывается метод.The default value will be restored when the ClearValue method is called on the bindable property.

Ниже приведен пример привязки свойства, с идентификатором и значения четыре обязательных параметров: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);

При этом создается BindableProperty экземпляр с именем EventName, типа string.This creates a BindableProperty instance named EventName, of type string. Свойство принадлежит EventToCommandBehavior класса, и имеет значение по умолчанию null.The property is owned by the EventToCommandBehavior class, and has a default value of null. Соглашение об именовании привязываемые свойства — это что может быть привязано идентификатор должен соответствовать имени свойства, указанные в Create метод, с добавленным к нему «Property».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. Таким образом, в приведенном выше примере идентификатор может быть привязано является EventNameProperty.Therefore, in the example above, the bindable property identifier is EventNameProperty.

При необходимости при создании BindableProperty экземпляра, следующие параметры можно указать:Optionally, when creating a BindableProperty instance, the following parameters can be specified:

  • Режим привязки.The binding mode. Используется для указания направления, в котором будут распространены изменения значений свойств.This is used to specify the direction in which property value changes will propagate. В режиме привязки по умолчанию, изменения распространялись из источника для целевой.In the default binding mode, changes will propagate from the source to the target.
  • Делегат проверки, который будет вызываться, когда свойство имеет значение.A validation delegate that will be invoked when the property value is set. Дополнительные сведения см. в разделе обратные вызовы проверки.For more information, see Validation Callbacks.
  • Делегат, который будет вызываться при изменении значения свойства изменено свойство.A property changed delegate that will be invoked when the property value has changed. Дополнительные сведения см. в разделе обнаружение изменений свойств.For more information, see Detecting Property Changes.
  • Свойство, изменение делегата, который будет вызываться, когда изменится значение свойства.A property changing delegate that will be invoked when the property value will change. Этот делегат имеет ту же сигнатуру, что делегат изменения свойства.This delegate has the same signature as the property changed delegate.
  • Делегат значение принудительного, который будет вызываться при изменении значения свойства.A coerce value delegate that will be invoked when the property value has changed. Дополнительные сведения см. в разделе приведение обратных вызовов значение.For more information, see Coerce Value Callbacks.
  • Объект Func , используемый для инициализации значения свойства по умолчанию.A Func that's used to initialize a default property value. Дополнительные сведения см. в разделе создающий значение по умолчанию с Func.For more information, see Creating a Default Value with a Func.

Создание методов доступаCreating Accessors

К свойствам должны использовать синтаксис свойства для доступа к может быть привязано.Property accessors are required to use property syntax to access a bindable property. Get Доступа должна возвращать значение, которое содержится в соответствующее свойство привязки.The Get accessor should return the value that's contained in the corresponding bindable property. Это достигается путем вызова GetValue метод, передав идентификатор может быть привязано, для которого необходимо получить значение и затем преобразование результата в требуемый тип.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. Set Доступа следует устанавливать значение соответствующего свойства привязки.The Set accessor should set the value of the corresponding bindable property. Это достигается путем вызова SetValue метод, передавая идентификатор может быть привязано, для которого требуется задать значение и присваиваемое значение.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.

В следующем примере кода показаны методы доступа для EventName свойство, используемое:The following code example shows accessors for the EventName bindable property:

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

Использование может быть привязаноConsuming a Bindable Property

После создания может быть привязано, его можно будет использовать из XAML или кода.Once a bindable property has been created, it can be consumed from XAML or code. В XAML это достигается путем объявления пространства имен с префиксом, с объявлением пространства имен, указывающее имя пространства имен CLR и при необходимости, имя сборки.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. Дополнительные сведения см. в разделе пространства имен XAML.For more information, see XAML Namespaces.

В следующем примере кода показано пространство имен XAML для пользовательского типа, который содержит свойство привязки, который определен в сборке, в качестве код приложения, который ссылается на пользовательский тип: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>

Объявление пространства имен используется при задании EventName свойство, используемое, как показано в следующем примере кода XAML: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>

Эквивалентный код на языке C# показан в следующем примере:The equivalent C# code is shown in the following code example:

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

Расширенные сценарииAdvanced Scenarios

При создании BindableProperty экземпляра, существует несколько необязательных параметров, которые могут устанавливаться для реализации сценариев дополнительного связываемые свойства.When creating a BindableProperty instance, there are a number of optional parameters that can be set to enable advanced bindable property scenarios. В данном разделе изучаются этих сценариев.This section explores these scenarios.

Обнаружение событий изменения свойствDetecting Property Changes

Объект static метод обратного вызова, изменения свойств может быть зарегистрирован может быть привязано, указав propertyChanged параметр для BindableProperty.Create метод.A static property-changed callback method can be registered with a bindable property by specifying the propertyChanged parameter for the BindableProperty.Create method. Указанный метод обратного вызова будет вызываться при изменении значения свойства привязки.The specified callback method will be invoked when the value of the bindable property changes.

В следующем примере кода показано как EventName регистрирует свойство, используемое OnEventNameChanged метода как метода обратного вызова, изменения свойства: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
}

В методе обратного вызова, изменения свойств BindableObject параметр используется для обозначения того, какой экземпляр класс-владелец обнаружил изменение, а также значения двух object параметры представляют старые и новые значения свойство, используемое.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.

Обратные вызовы проверкиValidation Callbacks

Объект static метод обратного вызова проверки может быть зарегистрирован может быть привязано, указав validateValue параметр для BindableProperty.Create метод.A static validation callback method can be registered with a bindable property by specifying the validateValue parameter for the BindableProperty.Create method. Указанный метод обратного вызова будет вызываться, если задано значение, связываемые свойства.The specified callback method will be invoked when the value of the bindable property is set.

В следующем примере кода показано как Angle регистрирует свойство, используемое IsValidValue метода как метода обратного вызова проверки: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);
}

Обратные вызовы проверки предоставляются со значением и должен возвращать true Если значение является допустимым для свойства, в противном случае false.Validation callbacks are provided with a value, and should return true if the value is valid for the property, otherwise false. Будет порождено исключение, если обратный вызов проверки возвращает false, которого должно обрабатываться разработчиком.An exception will be raised if a validation callback returns false, which should be handled by the developer. Типичное использование метода обратного вызова проверки ограничения значений целых чисел, если задано свойство, используемое.A typical use of a validation callback method is constraining the values of integers or doubles when the bindable property is set. Например IsValidValue метод проверяет, что свойство имеет значение double в диапазоне от 0 до 360.For example, the IsValidValue method checks that the property value is a double within the range 0 to 360.

Приведенных значенийCoerce Value Callbacks

Объект static привязкой к значению метод обратного вызова может быть зарегистрирован может быть привязано, указав coerceValue параметр для BindableProperty.Create метод.A static coerce value callback method can be registered with a bindable property by specifying the coerceValue parameter for the BindableProperty.Create method. Указанный метод обратного вызова будет вызываться при изменении значения свойства привязки.The specified callback method will be invoked when the value of the bindable property changes.

Приведение значения обратные вызовы используются для принудительного переоценки свойство, используемое при изменении значения свойства.Coerce value callbacks are used to force a reevaluation of a bindable property when the value of the property changes. Например чтобы убедиться, что значение одного свойства привязки не больше, чем значение другого привязываемые свойства можно использовать значение принудительного обратного вызова.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.

В следующем примере кода показано как Angle регистрирует свойство, используемое CoerceAngle метода как метода обратного вызова значение принудительного: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;
}

CoerceAngle Метод проверяет значение параметра MaximumAngle свойство и если Angle он превышает значение свойства, он приводит значение к MaximumAngle значение свойства.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.

Создание значения по умолчанию с помощью FuncCreating a Default Value with a Func

Объект Func может использоваться для инициализации значения по умолчанию привязываемые свойства, как показано в следующем примере кода: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));

defaultValueCreator Параметр имеет значение Func , вызывающий Device.GetNamedSize метод для возврата double , представляющий именованный размер шрифта, который используется на Label на собственной платформе.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.

СводкаSummary

В этой статье предоставляются общие сведения о привязываемые свойства, а также показано, как создавать и использовать их.This article provided an introduction to bindable properties, and demonstrated how to create and consume them. Может быть привязано — это специальный тип свойства, где значение свойства отслеживается системой свойств Xamarin.Forms.A bindable property is a special type of property, where the property's value is tracked by the Xamarin.Forms property system.