Propriétés attachées

  • Article

Télécharger l’exemple Télécharger l’exemple

Les propriétés jointes permettent à un objet d’affecter une valeur à 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 de spécifier la ligne et la colonne d’un enfant en définissant les Grid.Row propriétés jointes et Grid.Column . Grid.Row et Grid.Column sont des propriétés 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 pouvant ê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 définition 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 un BindableProperty instance avec l’une CreateAttached des surcharges de méthode.
  2. Fournissez les staticGet méthodes PropertyName et SetPropertyName comme accesseurs pour 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 dans laquelle la propriété est créée n’a pas besoin de dériver de BindableObject. Toutefois, la propriété cible pour les accesseurs doit être de , ou dériver de , BindableObject.

Une propriété jointe peut être créée en déclarant une public static readonly propriété de type BindableProperty. La propriété pouvant être liée doit être définie sur la valeur retourné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

La convention d’affectation de noms pour les propriétés jointes est que l’identificateur de propriété jointe doit correspondre au nom de propriété spécifié dans la CreateAttached méthode, avec « Property » ajouté à celui-ci.

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

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

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

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

Créer des accesseurs

Les méthodes Static GetPropertyName et SetPropertyName sont requises en tant qu’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 correspondant BindableProperty pour la propriété jointe. Pour ce faire, appelez la GetValue méthode, transmettez l’identificateur de propriété pouvant être lié sur lequel obtenir la valeur, puis castez la valeur résultante sur 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 SetValue méthode et transmettez l’identificateur de propriété pouvant être lié sur lequel définir la valeur et la valeur à définir.

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

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

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 à partir du code XAML ou du code. En XAML, cela s’effectue en déclarant un espace de noms avec un préfixe, avec la déclaration d’espace de noms indiquant le nom de l’espace de noms CLR (Common Language Runtime) et é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 fait référence au 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ée 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 un certain nombre de paramètres facultatifs qui peuvent être définis pour activer des scénarios de propriétés jointes avancées. Cela inclut la détection des modifications de propriété, la validation des valeurs de propriété et la force des valeurs de propriété. Pour plus d’informations, consultez Scénarios avancés.