Propiedades adjuntas

  • Artículo

Las propiedades adjuntas permiten a un objeto asignar un valor para una propiedad que su propia clase no define. Por ejemplo, los elementos secundarios pueden usar propiedades adjuntas para informar a su elemento primario de cómo se van a presentar en la interfaz de usuario. El control Grid permite especificar la fila y columna de un elemento secundario estableciendo las propiedades adjuntas Grid.Row y Grid.Column. Grid.Row y Grid.Column son propiedades adjuntas porque se establecen en elementos que son secundarios de un Grid, en lugar de en el propio Grid.

Las propiedades enlazables deben implementarse como propiedades adjuntas en los escenarios siguientes:

  • Cuando es necesario un mecanismo de configuración de propiedades para clases distintas de la clase de definición.
  • Cuando la clase representa un servicio que debe integrarse fácilmente con otras clases.

Para más información sobre las propiedades enlazables, vea Propiedades enlazables.

Creación de una propiedad adjunta

El proceso para crear una propiedad adjunta es el siguiente:

  1. Creación de una instancia BindableProperty con una de las sobrecargas del método CreateAttached.
  2. Proporcione métodos static GetPropertyName y SetPropertyName como descriptores de acceso para la propiedad adjunta.

Creación de una propiedad

Al crear una propiedad adjunta para su uso en otros tipos, la clase donde se crea la propiedad no tiene que derivar de BindableObject. Sin embargo, la propiedad de destino para los descriptores de acceso debe ser de, o derivar de, BindableObject.

Se puede crear una propiedad adjunta declarando una propiedad public static readonly de tipo BindableProperty. La propiedad enlazable debe establecerse en el valor devuelto de una de las sobrecargas del método BindableProperty.CreateAttached. La declaración debe estar dentro del cuerpo de la clase propietaria, pero fuera de cualquier definición de miembro.

Importante

La convención de nomenclatura para las propiedades adjuntas es que el identificador de la propiedad adjunta debe coincidir con el nombre de la propiedad especificado en el método CreateAttached, con "Propiedad" agregado.

El siguiente código muestra un ejemplo de una propiedad adjunta:

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

Esto crea una propiedad adjunta denominada HasShadowProperty, de tipo bool. La propiedad pertenece a la clase ShadowEffect, y tiene un valor predeterminado de false.

Para obtener más información sobre la creación de propiedades enlazables, incluyendo los parámetros que se pueden especificar durante la creación, consulta Creación de una propiedad enlazable.

Creación de los descriptores de acceso

Los métodos estáticos GetPropertyName y SetPropertyName son necesarios como descriptores de acceso para la propiedad adjunta, de lo contrario el sistema de propiedades no podrá usar la propiedad adjunta. El descriptor de acceso GetPropertyName debe cumplir con la siguiente firma:

public static valueType GetPropertyName(BindableObject target)

El descriptor de acceso GetPropertyName debe devolver el valor contenido en el campo BindableProperty correspondiente de la propiedad adjunta. Esto se puede lograr llamando al método GetValue, pasando el identificador de la propiedad vinculable sobre la que obtener el valor y después convirtiendo el valor resultante en el tipo requerido.

El descriptor de acceso SetPropertyName debe cumplir con la siguiente firma:

public static void SetPropertyName(BindableObject target, valueType value)

El descriptor de acceso SetPropertyName debe establecer el valor del campo correspondiente BindableProperty para la propiedad adjunta. Esto se puede lograr llamando al método SetValue, pasando el identificador de la propiedad enlazable sobre la que se va a establecer el valor, y el valor que se va a establecer.

Para ambos descriptores de acceso, el objeto de destino debe ser de, o derivar de, BindableObject.

El siguiente ejemplo de código muestra descriptores de acceso para la propiedad adjunta HasShadow:

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

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

Consumo de una propiedad adjunta

Una vez creada una propiedad adjunta, se puede consumir desde XAML o código. En XAML, esto se logra declarando un espacio de nombres con un prefijo, con la declaración de espacio de nombres que indica el nombre del espacio de nombres de Common Language Runtime (CLR) y, opcionalmente, un nombre de ensamblado. Para obtener más información, consulta Espacios de nombres de XAML.

En el ejemplo de código siguiente se muestra un espacio de nombres XAML para un tipo personalizado que contiene una propiedad adjunta, que se define dentro del mismo ensamblado que el código de aplicación que hace referencia al tipo personalizado:

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

A continuación, se usa la declaración de espacio de nombres al establecer la propiedad adjunta en un control específico, como se muestra en el siguiente ejemplo de código XAML:

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

El código de C# equivalente se muestra en el ejemplo de código siguiente:

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

Consumo de una propiedad adjunta con un estilo

Las propiedades adjuntas también se pueden agregar a un control con un estilo. El siguiente ejemplo de código XAML muestra un estilo explícito que usa la propiedad adjunta HasShadow, que puede aplicarse a controles Label:

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

Style se puede aplicar a un control Label si se establece su propiedad Style en la instancia de Style mediante la extensión de marcado StaticResource, como se muestra en el ejemplo de código siguiente:

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

Para obtener más información sobre los estilos, consulta Estilos.

Escenarios avanzados

Al crear una propiedad adjunta, hay una serie de parámetros opcionales que se pueden establecer para habilitar escenarios avanzados de propiedades adjuntas. Esto incluye detectar cambios de propiedad, validar valores de propiedad y reprimir valores de propiedad. Para obtener más información, consulta Escenarios avanzados.