Métadonnées de propriété de dépendance (WPF .NET)

  • Article

Le système de propriétés Windows Presentation Foundation (WPF) inclut un système de rapports de métadonnées de propriété de dépendance. Les informations disponibles via le système de rapports de métadonnées dépassent ce qui est disponible par le biais de caractéristiques clR (Common Language Runtime) générales ou de réflexion. Lorsque vous inscrivez une propriété de dépendance, vous avez la possibilité de créer et d’affecter des métadonnées. Si vous dérivez d’une classe qui définit une propriété de dépendance, vous pouvez remplacer les métadonnées de la propriété de dépendance héritée. Et, si vous ajoutez votre classe en tant que propriétaire d’une propriété de dépendance, vous pouvez remplacer les métadonnées de la propriété de dépendance héritée.

Important

La documentation du Guide du bureau pour .NET 7 et .NET 6 est en cours de construction.

Prérequis

L’article suppose une connaissance de base des propriétés de dépendance et que vous avez lu la vue d’ensemble des propriétés de dépendance. Pour suivre les exemples de cet article, il vous aide à connaître le langage XAML (Extensible Application Markup Language) et à savoir comment écrire des applications WPF.

Utilisation des métadonnées

Vous pouvez interroger les métadonnées de propriété de dépendance pour examiner les caractéristiques d’une propriété de dépendance. Lorsque le système de propriétés traite une propriété de dépendance, il accède à ses métadonnées. L’objet de métadonnées d’une propriété de dépendance contient les types d’informations suivants :

  • Valeur par défaut de la propriété de dépendance, qui est définie par le système de propriétés lorsqu’aucune autre valeur ne s’applique, telle qu’une valeur locale, de style ou d’héritage. Pour plus d’informations sur la précédence des valeurs de valeur pendant l’affectation au moment de l’exécution des valeurs de propriété de dépendance, consultez Priorité des valeurs de propriété de dépendance.

  • Références aux rappels de valeur de contrainte et aux rappels de modification de propriété sur le type de propriétaire. Vous pouvez uniquement obtenir des références aux rappels qui ont un modificateur d’accès public ou qui se trouvent dans votre étendue d’accès autorisée. Pour plus d’informations sur les rappels de propriétés de dépendance, consultez Rappels et validation des propriétés de dépendance.

  • Caractéristiques de propriété de dépendance au niveau du framework WPF (si la propriété de dépendance est une propriété d’infrastructure WPF). Les processus WPF, tels que le moteur de disposition de l’infrastructure et la logique d’héritage de propriété, interrogent les métadonnées au niveau du framework WPF. Pour plus d’informations, consultez métadonnées de propriété Framework.

API de métadonnées

La PropertyMetadata classe stocke la plupart des métadonnées utilisées par le système de propriétés. Les instances de métadonnées peuvent être créées et affectées par :

  • Types qui inscrivent les propriétés de dépendance avec le système de propriétés.

  • Types qui héritent d’une classe qui définit une propriété de dépendance.

  • Types qui s’ajoutent en tant que propriétaire d’une propriété de dépendance.

Si un type inscrit une propriété de dépendance sans spécifier de métadonnées, le système de propriétés affecte un PropertyMetadata objet avec des valeurs par défaut pour ce type à la propriété de dépendance.

Pour récupérer les métadonnées d’une propriété de dépendance, appelez l’une GetMetadata des surcharges sur l’identificateur DependencyProperty . Les métadonnées sont retournées en tant qu’objet PropertyMetadata .

Des classes de métadonnées plus spécifiques, dérivées de PropertyMetadata, existent pour différentes zones architecturales. Par exemple, UIPropertyMetadata prend en charge les rapports d’animation et FrameworkPropertyMetadata prend en charge les propriétés de l’infrastructure WPF. Les propriétés de dépendance peuvent également être inscrites auprès des PropertyMetadata classes dérivées. Bien que GetMetadata retourne un objet, le cas échéant, vous pouvez effectuer un PropertyMetadata cast vers un type dérivé pour examiner les propriétés spécifiques au type.

Les caractéristiques de propriété exposées par FrameworkPropertyMetadata sont parfois appelées indicateurs. Lorsque vous créez une FrameworkPropertyMetadata instance, vous avez la possibilité de transmettre une instance du type FrameworkPropertyMetadataOptions d’énumération au FrameworkPropertyMetadata constructeur. FrameworkPropertyMetadataOptions vous permet de spécifier des indicateurs de métadonnées dans une combinaison au niveau du bit. FrameworkPropertyMetadataOptions Utilisations FrameworkPropertyMetadata pour conserver la longueur de sa signature de constructeur raisonnable. Lors de l’inscription de propriétés de dépendance, les indicateurs de métadonnées sur FrameworkPropertyMetadataOptions utilisant FrameworkPropertyMetadata les propriétés sont exposés sous forme Boolean de propriétés plutôt qu’une combinaison de bits d’indicateurs pour rendre les caractéristiques des métadonnées plus intuitives.

Remplacer ou créer de nouvelles métadonnées ?

Lorsque vous héritez d’une propriété de dépendance, vous avez la possibilité de modifier les caractéristiques de la propriété de dépendance en substituant ses métadonnées. Toutefois, vous ne pourrez peut-être pas toujours accomplir votre scénario de propriété de dépendance en substituant les métadonnées, et il est parfois nécessaire de définir une propriété de dépendance personnalisée dans votre classe avec de nouvelles métadonnées. Les propriétés de dépendance personnalisées ont les mêmes fonctionnalités que les propriétés de dépendance définies par les types WPF. Pour plus d’informations, consultez propriétés de dépendance personnalisées.

L’une des caractéristiques d’une propriété de dépendance que vous ne pouvez pas remplacer est son type valeur. Si une propriété de dépendance héritée a le comportement approximatif dont vous avez besoin, mais que votre scénario nécessite un type de valeur différent, envisagez d’implémenter une propriété de dépendance personnalisée. Vous pouvez peut-être lier les valeurs de propriété par le biais de la conversion de type ou d’une autre implémentation dans votre classe dérivée.

Scénarios de substitution des métadonnées

Les exemples de scénarios de substitution des métadonnées de propriété de dépendance existantes sont les suivants :

  • Modification de la valeur par défaut, qui est un scénario courant.

  • Modification ou ajout de rappels de modification de propriété, ce qui peut être nécessaire si une propriété de dépendance héritée interagit avec d’autres propriétés de dépendance différemment de son implémentation de base. L’une des caractéristiques d’un modèle de programmation qui prend en charge le code et le balisage, est que les valeurs de propriété peuvent être définies dans n’importe quel ordre. Ce facteur peut affecter la façon dont vous implémentez des rappels de modification de propriété. Pour plus d’informations, consultez Rappels et validation des propriétés de dépendance.

  • Modification des options de métadonnées de propriété de l’infrastructure WPF. En règle générale, les options de métadonnées sont définies lors de l’inscription d’une nouvelle propriété de dépendance, mais vous pouvez les respecifier ou OverrideMetadataAddOwner les appeler. Pour plus d’informations sur la substitution des métadonnées de propriété de framework, consultez Spécification de FrameworkPropertyMetadata. Pour savoir comment définir des options de métadonnées de propriété framework lors de l’inscription d’une propriété de dépendance, consultez propriétés de dépendance personnalisées.

Remarque

Étant donné que les rappels de validation ne font pas partie des métadonnées, ils ne peuvent pas être modifiés en substituant les métadonnées. Pour plus d’informations, consultez Rappels de valeur de validation.

Substitution des métadonnées

Lors de l’implémentation d’une nouvelle propriété de dépendance, vous pouvez définir ses métadonnées à l’aide de surcharges de la Register méthode. Si votre classe hérite d’une propriété de dépendance, vous pouvez remplacer les valeurs de métadonnées héritées à l’aide de la OverrideMetadata méthode. Par exemple, vous pouvez utiliser OverrideMetadata pour définir des valeurs spécifiques au type. Pour plus d’informations et d’exemples de code, consultez Remplacer les métadonnées d’une propriété de dépendance.

Voici un exemple de propriété de dépendance WPF.Focusable La FrameworkElement classe inscrit Focusable. La Control classe dérive de , hérite de FrameworkElementla Focusable propriété de dépendance et remplace les métadonnées de propriété héritées. Le remplacement modifie la valeur de false la propriété par défaut jusqu’à true, mais conserve d’autres valeurs de métadonnées héritées.

Étant donné que la plupart des propriétés de dépendance existantes ne sont pas des propriétés virtuelles, leur implémentation héritée ombrage le membre existant. Lorsque vous remplacez une caractéristique de métadonnées, la nouvelle valeur de métadonnées remplace la valeur d’origine ou elle est fusionnée :

  • Pour un DefaultValue, la nouvelle valeur remplace la valeur par défaut existante. Si vous ne spécifiez pas de DefaultValue métadonnées de remplacement, la valeur provient de l’ancêtre le plus proche spécifié dans les DefaultValue métadonnées.

  • Pour un PropertyChangedCallback, la logique de fusion par défaut stocke toutes les PropertyChangedCallback valeurs d’une table et toutes sont appelées sur une modification de propriété. L’ordre de rappel est déterminé par profondeur de classe, où un rappel inscrit par la classe de base de la hiérarchie s’exécuterait en premier.

  • Pour un CoerceValueCallback, la nouvelle valeur remplace la valeur existante CoerceValueCallback . Si vous ne spécifiez pas de CoerceValueCallback métadonnées de remplacement, la valeur provient de l’ancêtre le plus proche spécifié dans les CoerceValueCallback métadonnées.

Remarque

La logique de fusion par défaut est implémentée par la Merge méthode. Vous pouvez spécifier une logique de fusion personnalisée dans une classe dérivée qui hérite d’une propriété de dépendance, en substituant Merge cette classe.

Ajouter une classe en tant que propriétaire

Pour « hériter » d’une propriété de dépendance inscrite dans une hiérarchie de classes différente, utilisez la AddOwner méthode. Cette méthode est généralement utilisée lorsque la classe d’ajout n’est pas dérivée du type qui a inscrit la propriété de dépendance. Dans l’appel AddOwner , la classe d’ajout peut créer et affecter des métadonnées spécifiques au type pour la propriété de dépendance héritée. Pour être un participant complet au système de propriétés, par le biais du code et du balisage, la classe d’ajout doit implémenter ces membres publics :

  • Champ d’identificateur de propriété de dépendance. La valeur de l’identificateur de propriété de dépendance est la valeur de retour de l’appel AddOwner . Ce champ doit être un public static readonly champ de type DependencyProperty.

  • Wrapper CLR qui implémente get et set accesseurs. En utilisant un wrapper de propriétés de propriété, les consommateurs de propriétés de dépendance peuvent obtenir ou définir des valeurs de propriété de dépendance, comme ils le feraient pour n’importe quelle autre propriété CLR. set Les get accesseurs interagissent avec le système de propriétés sous-jacent via DependencyObject.GetValue et DependencyObject.SetValue appellent, en passant l’identificateur de propriété de dépendance en tant que paramètre. Implémentez le wrapper de la même façon que vous le feriez lors de l’inscription d’une propriété de dépendance personnalisée. Pour plus d’informations, consultez propriétés de dépendance personnalisées

Une classe qui appelle AddOwner a les mêmes exigences pour exposer le modèle objet de la propriété de dépendance héritée en tant que classe qui définit une nouvelle propriété de dépendance personnalisée. Pour plus d’informations, consultez Ajouter un type de propriétaire pour une propriété de dépendance.

Métadonnées de propriété jointes

Dans WPF, la plupart des propriétés jointes liées à l’interface utilisateur sur les types WPF sont implémentées en tant que propriétés de dépendance. Les propriétés jointes implémentées en tant que propriétés de dépendance prennent en charge les concepts de propriété de dépendance, tels que les métadonnées que les classes dérivées peuvent remplacer. Les métadonnées d’une propriété jointe ne sont généralement pas différentes de celles d’une propriété de dépendance. Vous pouvez remplacer la valeur par défaut, les rappels de modification de propriété et les propriétés de l’infrastructure WPF pour la propriété jointe héritée, sur les instances de la classe de substitution. Pour plus d’informations, consultez métadonnées de propriété jointes

Remarque

Utilisez RegisterAttached toujours pour inscrire les propriétés dans lesquelles vous spécifiez Inherits les métadonnées. Bien que l’héritage de valeur de propriété semble fonctionner pour les propriétés de dépendance non attachées, le comportement d’héritage de valeur d’une propriété non attachée via certaines divisions d’objet-objet dans l’arborescence runtime n’est pas défini. La Inherits propriété n’est pas pertinente pour les propriétés non attachées. Pour plus d’informations, consultez RegisterAttached(String, Type, Type, PropertyMetadata)la section notes de Inherits.

Ajouter une classe en tant que propriétaire d’une propriété jointe

Pour hériter d’une propriété jointe d’une autre classe, mais l’exposer en tant que propriété de dépendance non attachée sur votre classe :

  • Appelez AddOwner pour ajouter votre classe en tant que propriétaire de la propriété de dépendance jointe.

  • Affectez la valeur de retour de l’appel AddOwner à un public static readonly champ, à utiliser comme identificateur de propriété de dépendance.

  • Définissez un wrapper CLR, qui ajoute la propriété en tant que membre de classe et prend en charge l’utilisation des propriétés non attachées.

Voir aussi