Propriedades AnexadasAttached Properties

Baixar Exemplo Baixar o exemploDownload Sample Download the sample

As propriedades anexadas permitem que um objeto atribua um valor para uma propriedade que sua própria classe não define.Attached properties enable an object to assign a value for a property that its own class doesn't define. Por exemplo, elementos filho podem usar propriedades anexadas para informar o elemento pai de como eles devem ser apresentados na interface do usuário.For example, child elements can use attached properties to inform their parent element of how they are to be presented in the user interface. O Grid controle permite que a linha e a coluna de um filho sejam especificadas definindo as Grid.Row Grid.Column Propriedades anexadas e.The Grid control allows the row and column of a child to be specified by setting the Grid.Row and Grid.Column attached properties. Grid.Row e Grid.Column são propriedades anexadas porque são definidas em elementos que são filhos de a Grid , e não por Grid si só.Grid.Row and Grid.Column are attached properties because they are set on elements that are children of a Grid, rather than on the Grid itself.

As propriedades vinculáveis devem ser implementadas como propriedades anexadas nos seguintes cenários:Bindable properties should be implemented as attached properties in the following scenarios:

  • Quando há a necessidade de ter um mecanismo de configuração de propriedade disponível para classes diferentes da classe de definição.When there's a need to have a property setting mechanism available for classes other than the defining class.
  • Quando a classe representa um serviço que precisa ser facilmente integrado a outras classes.When the class represents a service that needs to be easily integrated with other classes.

Para obter mais informações sobre as propriedades vinculáveis, consulte propriedades vinculáveis.For more information about bindable properties, see Bindable Properties.

Criar uma propriedade anexadaCreate an attached property

O processo para criar uma propriedade anexada é o seguinte:The process for creating an attached property is as follows:

  1. Crie uma BindableProperty instância com uma das CreateAttached sobrecargas de método.Create a BindableProperty instance with one of the CreateAttached method overloads.
  2. Forneça static Get os métodos PropertyName e Set PropertyName como acessadores para a propriedade anexada.Provide static GetPropertyName and SetPropertyName methods as accessors for the attached property.

Criar uma propriedadeCreate a property

Ao criar uma propriedade anexada para uso em outros tipos, a classe na qual a propriedade é criada não precisa derivar de BindableObject .When creating an attached property for use on other types, the class where the property is created does not have to derive from BindableObject. No entanto, a propriedade de destino para acessadores deve ser de, ou derivar de, BindableObject .However, the target property for accessors should be of, or derive from, BindableObject.

Uma propriedade anexada pode ser criada declarando-se uma public static readonly Propriedade do tipo BindableProperty .An attached property can be created by declaring a public static readonly property of type BindableProperty. A propriedade vinculável deve ser definida como o valor retornado de um dos [ BindableProperty.CreateAttached ] (xref: Xamarin.Forms . Associável. createanexado (System. String, System. Type, System. Type, System. Object, Xamarin.Forms . BindingMode, Xamarin.Forms . Vinculproperty. ValidateValueDelegate, Xamarin.Forms . Vinculproperty. BindingPropertyChangedDelegate, Xamarin.Forms . Vinculproperty. BindingPropertyChangingDelegate, Xamarin.Forms . Vinculproperty. CoerceValueDelegate, Xamarin.Forms . O método acopláproperty. CreateDefaultValueDelegate)) é sobrecarregado.The bindable property should be set to the returned value of one of the BindableProperty.CreateAttached method overloads. A declaração deve estar dentro do corpo da classe proprietária, mas fora de qualquer definição de membro.The declaration should be within the body of the owning class, but outside of any member definitions.

Importante

A Convenção de nomenclatura para propriedades anexadas é que o identificador de Propriedade anexado deve corresponder ao nome de propriedade especificado no CreateAttached método, com "Property" acrescentado a ele.The naming convention for attached properties is that the attached property identifier must match the property name specified in the CreateAttached method, with "Property" appended to it.

O código a seguir mostra um exemplo de uma propriedade anexada:The following code shows an example of an attached property:

public static readonly BindableProperty HasShadowProperty =
  BindableProperty.CreateAttached ("HasShadow", typeof(bool), typeof(ShadowEffect), false);

Isso cria uma propriedade anexada chamada HasShadowProperty , do tipo bool .This creates an attached property named HasShadowProperty, of type bool. A propriedade pertence à ShadowEffect classe e tem um valor padrão de false .The property is owned by the ShadowEffect class, and has a default value of false.

Para obter mais informações sobre como criar propriedades vinculáveis, incluindo parâmetros que podem ser especificados durante a criação, consulte criar uma propriedade vinculável.For more information about creating bindable properties, including parameters that can be specified during creation, see Create a bindable property.

Criar acessadoresCreate accessors

GetOs métodos PropertyName e Set PropertyName estáticos são necessários como acessadores para a propriedade anexada, caso contrário, o sistema de propriedades não poderá usar a propriedade anexada.Static GetPropertyName and SetPropertyName methods are required as accessors for the attached property, otherwise the property system will be unable to use the attached property. O Get acessador PropertyName deve estar em conformidade com a seguinte assinatura:The GetPropertyName accessor should conform to the following signature:

public static valueType GetPropertyName(BindableObject target)

O Get acessador PropertyName deve retornar o valor contido no campo correspondente BindableProperty para a propriedade anexada.The GetPropertyName accessor should return the value that's contained in the corresponding BindableProperty field for the attached property. Isso pode ser obtido chamando [ GetValue ] (xref: Xamarin.Forms . Acopláble. GetValue ( Xamarin.Forms . Vinculproperty)), passando o identificador de propriedade vinculável no qual obter o valor e, em seguida, convertendo o valor resultante para o tipo necessário.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 resulting value to the required type.

O Set acessador PropertyName deve estar em conformidade com a seguinte assinatura:The SetPropertyName accessor should conform to the following signature:

public static void SetPropertyName(BindableObject target, valueType value)

O Set acessador PropertyName deve definir o valor do BindableProperty campo correspondente para a propriedade anexada.The SetPropertyName accessor should set the value of the corresponding BindableProperty field for the attached property. Isso pode ser obtido chamando [ SetValue ] (xref: Xamarin.Forms . Acopláble. SetValue ( Xamarin.Forms . Vinculproperty, System. Object), passando o identificador de propriedade vinculável no qual definir o valor e o valor a ser definido.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.

Para os dois acessadores, o objeto de destino deve ser de, ou derivar de, BindableObject .For both accessors, the target object should be of, or derive from, BindableObject.

O exemplo de código a seguir mostra os acessadores da HasShadow Propriedade anexada:The following code example shows accessors for the HasShadow attached property:

public static bool GetHasShadow (BindableObject view)
{
  return (bool)view.GetValue (HasShadowProperty);
}

public static void SetHasShadow (BindableObject view, bool value)
{
  view.SetValue (HasShadowProperty, value);
}

Consumir uma propriedade anexadaConsume an attached property

Depois que uma propriedade anexada tiver sido criada, ela poderá ser consumida do XAML ou do código.Once an attached property has been created, it can be consumed from XAML or code. Em XAML, isso é feito declarando um namespace com um prefixo, com a declaração de namespace indicando o nome do namespace CLR (Common Language Runtime) e, opcionalmente, um nome de assembly.In XAML, this is achieved by declaring a namespace with a prefix, with the namespace declaration indicating the Common Language Runtime (CLR) namespace name, and optionally an assembly name. Para obter mais informações, consulte XAML namespaces.For more information, see XAML Namespaces.

O exemplo de código a seguir demonstra um namespace XAML para um tipo personalizado que contém uma propriedade anexada, que é definida dentro do mesmo assembly que o código do aplicativo que faz referência ao tipo personalizado:The following code example demonstrates a XAML namespace for a custom type that contains an attached property, which is defined within the same assembly as the application code that's referencing the custom type:

<ContentPage ... xmlns:local="clr-namespace:EffectsDemo" ...>
  ...
</ContentPage>

Em seguida, a declaração de namespace é usada ao definir a propriedade anexada em um controle específico, conforme demonstrado no exemplo de código XAML a seguir:The namespace declaration is then used when setting the attached property on a specific control, as demonstrated in the following XAML code example:

<Label Text="Label Shadow Effect" local:ShadowEffect.HasShadow="true" />

O código C# equivalente é mostrado no exemplo de código a seguir:The equivalent C# code is shown in the following code example:

var label = new Label { Text = "Label Shadow Effect" };
ShadowEffect.SetHasShadow (label, true);

Consumir uma propriedade anexada com um estiloConsume an attached property with a style

As propriedades anexadas também podem ser adicionadas a um controle por um estilo.Attached properties can also be added to a control by a style. O exemplo de código XAML a seguir mostra um estilo explícito que usa a HasShadow Propriedade anexada, que pode ser aplicada a Label controles:The following XAML code example shows an explicit style that uses the HasShadow attached property, that can be applied to Label controls:

<Style x:Key="ShadowEffectStyle" TargetType="Label">
  <Style.Setters>
    <Setter Property="local:ShadowEffect.HasShadow" Value="true" />
  </Style.Setters>
</Style>

O Style pode ser aplicado a um Label definindo sua Style propriedade para a Style instância usando a StaticResource extensão de marcação, conforme demonstrado no exemplo de código a seguir:The Style can be applied to a Label by setting its Style property to the Style instance using the StaticResource markup extension, as demonstrated in the following code example:

<Label Text="Label Shadow Effect" Style="{StaticResource ShadowEffectStyle}" />

Para mais informações sobre estilos, confira Estilos.For more information about styles, see Styles.

Cenários avançadosAdvanced scenarios

Ao criar uma propriedade anexada, há vários parâmetros opcionais que podem ser definidos para habilitar cenários de Propriedade anexado avançado.When creating an attached property, there are a number of optional parameters that can be set to enable advanced attached property scenarios. Isso inclui a detecção de alterações de propriedade, a validação de valores de propriedade e a coerção de valores de propriedade.This includes detecting property changes, validating property values, and coercing property values. Para obter mais informações, consulte cenários avançados.For more information, see Advanced scenarios.