Les propriétés pouvant être liées .NET MAUI (.NET Multi-Platform App UI) étendent la fonctionnalité des propriétés CLR (Common Language Runtime) en prenant en charge une propriété avec un type BindableProperty à la place d’un champ. Le but des propriétés pouvant être liées est de fournir un système de propriétés qui prend en charge la liaison de données, les styles, les modèles et les valeurs définis par le biais de relations parent-enfant. En outre, les propriétés pouvant être liées peuvent fournir des valeurs par défaut, la validation de valeurs de propriété et des rappels qui surveillent les modifications de propriété.
Dans les applications .NET MAUI, vous devez implémenter des propriétés en tant que propriétés pouvant être liées pour prendre en charge une ou plusieurs des fonctionnalités suivantes :
Agir en tant que propriété cible valide pour la liaison de données. Pour plus d’informations sur les propriétés cibles, consultez Liaisons de base.
Définir la propriété par le biais d’un style.
Fournir une valeur de propriété par défaut différente de la valeur par défaut pour le type de la propriété.
Valider la valeur de la propriété.
Surveiller les modifications de propriété.
Label.Text, Button.BorderRadius et StackLayout.Orientation sont des exemples de propriétés pouvant être liées .NET MAUI. Chaque propriété pouvant être liée possède un champ public static readonly correspondant de type BindableProperty qui est exposé sur la même classe et qui est l’identificateur de la propriété pouvant être liée. Par exemple, l’identificateur de propriété pouvant être liée correspondant pour la propriété Label.Text est Label.TextProperty.
Créer une propriété pouvant être liée
Le processus de création d’une propriété pouvant être liée est le suivant :
Créez une instance BindableProperty avec l’une des surcharges de méthode BindableProperty.Create.
Définissez les accesseurs de propriété pour l’instance BindableProperty.
Toutes les instances BindableProperty doivent être créées sur le thread d’interface utilisateur. Cela signifie que seul le code qui s’exécute sur le thread d’interface utilisateur peut obtenir ou définir la valeur d’une propriété pouvant être liée. Toutefois, les instances BindableProperty sont accessibles à partir d’autres threads via un marshaling vers le thread d’interface utilisateur. Pour plus d’informations, consultez Exécuter du code sur le thread d’interface utilisateur.
Créer une propriété
Pour créer une instance BindableProperty, la classe contenante doit dériver de la classe BindableObject. Toutefois, la classe BindableObject se trouvant dans la partie supérieure de la hiérarchie des classes, la majorité des classes utilisées pour les fonctionnalités d’interface utilisateur prennent en charge les propriétés pouvant être liées.
Vous pouvez créer une propriété pouvant être liée en déclarant une propriété public static readonly de type BindableProperty. La propriété pouvant être liée doit être définie sur la valeur renvoyée de l’une des surcharges de méthode BindableProperty.Create. La déclaration doit se trouver dans le corps de la classe dérivée BindableObject, mais en dehors de toute définition de membre.
Au minimum, vous devez spécifier un identificateur lors de la création de BindableProperty, ainsi que les paramètres suivants :
Valeur par défaut de la propriété. Cela garantit que la propriété retourne toujours une valeur par défaut particulière si elle n’est pas définie et qu’elle peut être différente de la valeur par défaut pour le type de la propriété. La valeur par défaut est restaurée lorsque la méthode ClearValue est appelée sur la propriété pouvant être liée.
Important
Selon la convention d’affectation de noms pour les propriétés pouvant être liées, l’identificateur de propriété pouvant être lié doit correspondre au nom de propriété spécifié dans la méthode Create et être suivi de « Property ».
Le code suivant montre un exemple de propriété pouvant être liée, avec un identificateur et des valeurs pour les quatre paramètres requis :
Une instance BindableProperty nommée IsExpandedProperty de type bool est créée. La propriété appartient à la classe Expander et a pour valeur par défaut false.
Notes
Expander est un contrôle de le kit de ressources de la communauté .NET MAUI. Pour plus d’informations, consultez Expandeur.
Lors de la création d’une instance BindableProperty, vous pouvez éventuellement spécifier les paramètres suivants :
Mode de liaison. Il est utilisé pour spécifier la direction dans laquelle les modifications de valeur de propriété se propagent. Dans le mode de liaison par défaut, les modifications se propagent de la source à la cible. Pour plus d’informations, consultez Liaisons de base.
Un délégué de validation qui est appelé lorsque la valeur de propriété est définie. Pour plus d’informations, consultez Rappels de validation.
Un délégué de propriété modifiée qui est appelé lorsque la valeur de propriété a été modifiée. Pour plus d’informations, consultez Détecter les modifications de propriété.
Un délégué de modification de propriété qui est appelé lorsque la valeur de propriété va être modifiée. Ce délégué a la même signature que le délégué de propriété modifiée.
Un délégué de forçage de valeur qui est appelé lorsque la valeur de propriété a été modifiée. Pour plus d’informations, consultez Rappels de forçage de valeur.
Les accesseurs de propriété doivent utiliser la syntaxe de propriété pour accéder à une propriété pouvant être liée. L’accesseur Get doit retourner la valeur contenue dans la propriété pouvant être liée correspondante. Pour ce faire, appelez la méthode GetValue, passez l’identificateur de la propriété pouvant être liée dont vous souhaitez obtenir la valeur, puis castez le résultat vers le type requis. L’accesseur Set doit définir la valeur de la propriété pouvant être liée correspondante. Pour ce faire, appelez la méthode SetValue, puis passez l’identificateur de la propriété pouvant être liée dont vous souhaitez définir la valeur et la valeur à définir.
L’exemple de code suivant montre les accesseurs pour la propriété pouvant être liée IsExpanded :
public bool IsExpanded
{
get => (bool)GetValue(IsExpandedProperty);
set => SetValue(IsExpandedProperty, value);
}
Consommer une propriété pouvant être liée
Une fois qu’une propriété pouvant être liée a été créée, vous pouvez la consommer 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 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é pouvant être liée, définie dans le même assembly que le code d’application qui référence le type personnalisé :
La déclaration d’espace de noms est utilisée lors de la définition de la propriété pouvant être liée IsExpanded, comme illustré dans l’exemple de code XAML suivant :
<Expander IsExpanded="true">
...
</Expander>
Le code C# équivalent est affiché dans l’exemple de code suivant :
Expander expander = new Expander
{
IsExpanded = true
};
Scénarios avancés
Lors de la création d’une instance BindableProperty, vous pouvez définir un certain nombre de paramètres facultatifs pour prendre en charge des scénarios avancés avec des propriétés pouvant être liées. Cette section explore ces scénarios.
Détecter les modifications de propriété
Vous pouvez inscrire une méthode de rappel de propriété modifiée static auprès d’une propriété pouvant être liée en spécifiant le paramètre propertyChanged pour la méthode BindableProperty.Create. La méthode de rappel spécifiée est appelée lorsque la valeur de la propriété pouvant être liée est modifiée.
L’exemple de code suivant montre comment la propriété pouvant être liée IsExpanded inscrit la méthode OnIsExpandedChanged en tant que méthode de rappel de propriété modifiée :
Dans la méthode de rappel de propriété modifiée, le paramètre BindableObject est utilisé pour indiquer l’instance de la classe propriétaire qui a signalé une modification, et les valeurs des deux paramètres object représentent l’ancienne valeur et la nouvelle valeur de la propriété pouvant être liée.
Rappels de validation
Vous pouvez inscrire une méthode de rappel de validation static auprès d’une propriété pouvant être liée en spécifiant le paramètre validateValue pour la méthode BindableProperty.Create. La méthode de rappel spécifiée est appelée lorsque la valeur de la propriété pouvant être liée est définie.
L’exemple de code suivant montre comment la propriété pouvant être liée Angle inscrit la méthode IsValidValue en tant que méthode de rappel de validation :
Les rappels de validation sont fournis avec une valeur et doivent retourner true si la valeur est valide pour la propriété (sinon, false). Une exception est levée si un rappel de validation retourne false. Vous devez gérer cette exception. Une méthode de rappel de validation est généralement utilisée pour limiter les valeurs d’entiers ou de doubles lorsque la propriété pouvant être liée est définie. Par exemple, la méthode IsValidValue vérifie que la valeur de propriété est un double compris entre 0 et 360.
Rappels de forçage de valeur
Vous pouvez inscrire une méthode de rappel de forçage de valeur static auprès d’une propriété pouvant être liée en spécifiant le paramètre coerceValue pour la méthode BindableProperty.Create. La méthode de rappel spécifiée est appelée lorsque la valeur de la propriété pouvant être liée est sur le point d’être modifiée, ce qui vous permet d’ajuster la nouvelle valeur avant son application.
Important
Les rappels de forçage de valeur peuvent être déclenchés par le moteur de propriété pouvant être liée, mais vous pouvez aussi les appeler à partir du code. Le type BindableObject possède une méthode CoerceValue qui peut être appelée pour forcer une réévaluation de la valeur de son argument BindableProperty, en appelant son rappel de forçage de valeur.
Les rappels de forçage de valeur sont utilisés pour forcer une réévaluation d’une propriété pouvant être liée lorsque la valeur de la propriété est sur le point d’être modifiée. Par exemple, un rappel de forçage de valeur peut être utilisé pour s’assurer que la valeur d’une propriété pouvant être liée n’est pas supérieure à la valeur d’une autre propriété pouvant être liée.
L’exemple de code suivant montre comment la propriété pouvant être liée Angle inscrit la méthode CoerceAngle en tant que méthode de rappel de forçage de valeur :
La méthode CoerceAngle vérifie la valeur de la propriété MaximumAngle et, si la valeur de la propriété Angle est supérieure, force la valeur à être égale à la valeur de la propriété MaximumAngle. De plus, lorsque la propriété MaximumAngle est modifiée, le rappel de forçage de valeur est appelé sur la propriété Angle en appelant la méthode CoerceValue.
Créer une valeur par défaut avec Func
Vous pouvez utiliser un Func pour initialiser la valeur par défaut d’une propriété pouvant être liée, comme illustré dans l’exemple suivant :
Le paramètre defaultValueCreator est défini sur un Func qui retourne un DateTime représentant la date du jour.
Collaborer avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
Commentaires sur .NET MAUI
.NET MAUI est un projet open source. Sélectionnez un lien pour fournir des commentaires :
Créer une interface utilisateur avec la liaison de données. Votre interface utilisateur est automatiquement mise à jour en fonction des données les plus récentes, tandis que les données sont mises à jour suite aux modifications apportées à l’interface utilisateur.
Découvrez comment implémenter la propriété Command avec des liaisons de données MAUI .NET. L’interface de commande offre une autre approche pour implémenter des commandes adaptées à l’architecture MVVM.
Les déclencheurs vous permettent d’exprimer des actions de manière déclarative en XAML. Les actions en question modifient l’apparence des contrôles en fonction des événements ou des modifications apportées aux propriétés.
Les liaisons relatives .NET MAUI sont créées avec l’extension de balisage RelativeSource, qui définit la source de liaison par rapport à la position de la cible de liaison.