Propriétés jointes

Article
05/14/2024

Les propriétés jointes .NET Multi-platform App UI (.NET MAUI) 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. La disposition Grid permet de spécifier la ligne et la colonne d’un élément enfant en définissant les propriétés jointes Grid.Row et Grid.Column. 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 qui peuvent être liées, consultez Propriétés qui peuvent être liées.

Créer une propriété jointe

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

Créez une instance BindableProperty avec l’une des surcharges de méthode CreateAttached.
Fournissez des méthodes staticGetPropertyName 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. Pour plus d’informations sur les propriétés cibles, consultez Liaisons de base.

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 class MyControl
{
    public static readonly BindableProperty HasShadowProperty =
        BindableProperty.CreateAttached("HasShadow", typeof(bool), typeof(MyControl), false);
}

Cela crée une propriété jointe nommée HasShadowProperty de type bool. La propriété appartient à la classe MyControl et a une valeur par défaut de false. La propriété, dans ce cas, signifie que la propriété est accessible en XAML à l’aide du format Type.Property, par exemple MyControl.HasShadow.

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. Pour plus d’informations sur les objets cibles, consultez Liaisons de base.

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

public class MyControl
{
    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 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:ShadowDemo" ...>
  ...
</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 le code XAML suivant :

<Label Text="Label with shadow" local:MyControl.HasShadow="true" />

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

Label label = new Label { Text = "Label with shadow" };
MyControl.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 pour les contrôles Label qui utilisent la propriété jointe HasShadow :

<Style x:Key="ShadowStyle" TargetType="Label">
  <Style.Setters>
    <Setter Property="local:MyControl.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 with shadow" Style="{StaticResource ShadowStyle}" />

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

Scénarios avancés

Lors de la création d’une propriété jointe, certains paramètres facultatifs 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.

Partager via