Partager via

Propriétés attachées

  • Article

Les propriétés jointes permettent à un objet d’affecter une valeur pour une propriété que sa propre classe ne définit pas. Par exemple, les éléments enfants peuvent utiliser des propriétés jointes pour informer leur élément parent de la façon dont ils doivent être présentés dans l’interface utilisateur. Le Grid contrôle permet à la ligne et à la colonne d’un enfant d’être spécifiée en définissant les Grid.Row propriétés jointes et Grid.Column les propriétés jointes. Grid.Row et Grid.Column sont jointes, car elles sont définies sur des éléments qui sont des enfants d’un Grid, plutôt que sur le Grid lui-même.

Les propriétés qui peuvent être liées doivent être implémentées en tant que propriétés jointes dans les scénarios suivants :

  • Lorsqu’il est nécessaire d’avoir un mécanisme de paramètre de propriété disponible pour les classes autres que la classe de définition.
  • Lorsque la classe représente un service qui doit être facilement intégré à d’autres classes.

Pour plus d’informations sur les propriétés pouvant être liées, consultez Propriétés pouvant être liées.

Créer une propriété jointe

Le processus de création d’une propriété jointe est le suivant :

  1. Créez une instance BindableProperty avec l’une des surcharges de méthode CreateAttached.
  2. Fournissez des méthodes static GetPropertyName et SetPropertyName comme accesseurs de la propriété jointe.

Créer une propriété

Lors de la création d’une propriété jointe à utiliser sur d’autres types, la classe à partir de laquelle la propriété est créée n’a pas besoin d’être dérivée de BindableObject. Toutefois, la propriété cible pour les accesseurs doit être à, ou être dérivée de BindableObject.

Vous pouvez créer une propriété jointe en déclarant une propriété public static readonly de type BindableProperty. La propriété qui peut être liée doit être définie sur la valeur renvoyée de l’une des surcharges de méthode BindableProperty.CreateAttached. La déclaration doit se trouver dans le corps de la classe propriétaire, mais en dehors de toute définition de membre.

Important

Selon la convention d’affectation de noms pour les propriétés jointes, l’identificateur de propriété jointe doit correspondre au nom de propriété spécifié dans la méthode CreateAttached, suivi de « Property ».

Le code suivant montre un exemple de propriété jointe :

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

Cela crée une propriété jointe nommée HasShadowProperty de type bool. La propriété appartient à la classe ShadowEffect et a une valeur par défaut de false.

Pour plus d’informations sur la création de propriétés qui peuvent être liées, notamment les paramètres qui peuvent être spécifiés lors de la création, consultez Créer une propriété qui peut être liée.

Créer des accesseurs

Les méthodes Static GetPropertyName et SetPropertyName sont requises comme accesseurs pour la propriété jointe, sinon le système de propriétés ne pourra pas utiliser la propriété jointe. L’accesseur GetPropertyName doit être conforme à la signature suivante :

public static valueType GetPropertyName(BindableObject target)

L’accesseur GetPropertyName doit retourner la valeur contenue dans le champ BindableProperty correspondant de la propriété jointe. Pour ce faire, appelez la méthode GetValue en passant l’identificateur de la propriété qui peut être liée dont vous souhaitez obtenir la valeur, puis en castant la valeur qui en résulte vers le type requis.

L’accesseur SetPropertyName doit être conforme à la signature suivante :

public static void SetPropertyName(BindableObject target, valueType value)

L’accesseur SetPropertyName doit définir la valeur du champ correspondant BindableProperty pour la propriété jointe. Pour ce faire, appelez la méthode SetValue en passant l’identificateur de la propriété qui peut être liée dont vous souhaitez définir la valeur, et la valeur à définir.

Pour les deux accesseurs, l’objet cible doit être à, ou être dérivé de BindableObject.

L’exemple de code suivant montre les accesseurs pour la propriété jointe HasShadow :

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

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

Consommer une propriété jointe

Une fois qu’une propriété jointe a été créée, elle peut être consommée en XAML ou dans du code. En XAML, déclarez un espace de noms avec un préfixe en indiquant le nom de l’espace de noms CLR (Common Language Runtime) dans la déclaration d’espace de noms et en spécifiant éventuellement un nom d’assembly. Pour plus d’informations, consultez Espaces de noms XAML.

L’exemple de code suivant illustre un espace de noms XAML pour un type personnalisé qui contient une propriété jointe, qui est définie dans le même assembly que le code d’application qui référence le type personnalisé :

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

La déclaration d’espace de noms est ensuite utilisée lors de la définition de la propriété jointe sur un contrôle spécifique, comme illustré dans l’exemple de code XAML suivant :

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

Le code C# équivalent est affiché dans l’exemple de code suivant :

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

Consommer une propriété jointe avec un style

Les propriétés jointes peuvent également être ajoutées à un contrôle par un style. L’exemple de code XAML suivant montre un style explicite qui utilise la HasShadow propriété jointe, qui peut être appliqué aux Label contrôles :

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

Le Style peut être appliqué à un contrôle Label en définissant sa propriété Style sur l’instance Style à l’aide de l’extension de balisage StaticResource, comme illustré dans l’exemple de code suivant :

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

Pour plus d’informations sur les styles, consultez Styles.

Scénarios avancés

Lors de la création d’une propriété jointe, il existe plusieurs paramètres facultatifs qui peuvent être définis pour activer des scénarios de propriétés jointes avancés. Cela inclut la détection des modifications de propriété, la validation des valeurs de propriété et le forçage des valeurs de propriété. Pour plus d'informations, consultez Scénarios avancés.