Partager via

Syntaxe de Property-path

  • Article

Vous pouvez utiliser la classe PropertyPath et la syntaxe de chaîne pour instancier une valeur PropertyPath en XAML ou dans du code. Les valeurs PropertyPath sont utilisées par la liaison de données. Une syntaxe similaire est utilisée pour cibler des animations storyboarded. Pour les deux scénarios, un chemin de propriété décrit une traversée d’une ou plusieurs relations de propriété d’objet qui se résolvent finalement en une seule propriété.

Vous pouvez définir une chaîne de chemin de propriété directement sur un attribut en XAML. Vous pouvez utiliser la même syntaxe de chaîne pour construire un PropertyPath qui définit une liaison dans le code, ou pour définir une cible d’animation dans le code à l’aide de SetTargetProperty. Il existe deux zones de fonctionnalités distinctes dans Windows Runtime qui utilisent un chemin de propriété : la liaison de données et le ciblage d’animation. Le ciblage d’animation ne crée pas de valeurs de syntaxe de chemin de propriété sous-jacentes dans l’implémentation de Windows Runtime, il conserve les informations sous forme de chaîne, mais les concepts de traversée de propriété d’objet sont très similaires. La liaison de données et l’animation ciblant chacune évaluent un chemin de propriété légèrement différemment. Nous décrivons donc séparément la syntaxe du chemin de propriété pour chacun d’eux.

Chemin de propriété pour les objets dans la liaison de données

Dans Windows Runtime, vous pouvez établir une liaison à la valeur cible de n’importe quelle propriété de dépendance. La valeur de propriété source d’une liaison de données n’a pas besoin d’être une propriété de dépendance ; il peut s’agir d’une propriété sur un objet métier (par exemple, une classe écrite dans un langage Microsoft .NET ou C++). Ou bien, l’objet source de la valeur de liaison peut être un objet de dépendance existant déjà défini par l’application. La source peut être référencée soit par un nom de propriété simple, soit par une traversée des relations de propriété d’objet dans le graphique d’objets de l’objet métier.

Vous pouvez établir une liaison à une valeur de propriété individuelle, ou vous pouvez la lier à une propriété cible qui contient des listes ou des collections. Si votre source est une collection ou si le chemin d’accès spécifie une propriété de collection, le moteur de liaison de données correspond aux éléments de collection de la source à la cible de liaison, ce qui entraîne un comportement tel que le remplissage d’un ListBox avec une liste d’éléments d’une collection de sources de données sans avoir à anticiper les éléments spécifiques de cette collection.

Traversée d’un graphique d’objet

L’élément de la syntaxe qui désigne la traversée d’une relation objet-propriété dans un graphique d’objet est le caractère point (.). Chaque point d’une chaîne de chemin de propriété indique une division entre un objet (côté gauche du point) et une propriété de cet objet (côté droit du point). La chaîne est évaluée de gauche à droite, ce qui permet de parcourir plusieurs relations de propriété d’objet. Prenons un exemple :

"{Binding Path=Customer.Address.StreetAddress1}"

Voici comment ce chemin est évalué :

  1. L’objet de contexte de données (ou une source spécifiée par la même liaison) est recherché pour une propriété nommée « Customer ».
  2. L’objet qui est la valeur de la propriété « Customer » est recherché pour une propriété nommée « Address ».
  3. L’objet qui est la valeur de la propriété « Address » est recherché pour une propriété nommée « StreetAddress1 ».

À chacune de ces étapes, la valeur est traitée comme un objet. Le type du résultat est vérifié uniquement lorsque la liaison est appliquée à une propriété spécifique. Cet exemple échouerait si « Address » n’était qu’une valeur de chaîne qui n’a pas exposé la partie de la chaîne était l’adresse postale. En règle générale, la liaison pointe vers les valeurs de propriété imbriquées spécifiques d’un objet métier qui a une structure d’informations connue et délibérée.

Règles pour les propriétés dans un chemin de propriété de liaison de données

  • Toutes les propriétés référencées par un chemin de propriété doivent être publiques dans l’objet métier source.
  • La propriété end (la propriété qui est la dernière propriété nommée dans le chemin d’accès) doit être publique et doit être mutable. Vous ne pouvez pas vous lier à des valeurs statiques.
  • La propriété de fin doit être en lecture/écriture si ce chemin d’accès est utilisé comme informations de chemin d’accès pour une liaison bidirectionnelle.

Indexeurs

Un chemin de propriété pour la liaison de données peut inclure des références aux propriétés indexées. Cela permet de lier des listes/vecteurs ordonnés ou à des dictionnaires/cartes. Utilisez des crochets « [] » pour indiquer une propriété indexée. Le contenu de ces crochets peut être un entier (pour la liste ordonnée) ou une chaîne nonquoée (pour les dictionnaires). Vous pouvez également établir une liaison à un dictionnaire où la clé est un entier. Vous pouvez utiliser différentes propriétés indexées dans le même chemin d’accès avec un point séparant la propriété objet.

Par exemple, considérez un objet métier dans lequel il existe une liste de « Teams » (liste ordonnée), chacun ayant un dictionnaire de « Joueurs » où chaque joueur est clé par nom. Un exemple de chemin de propriété vers un joueur spécifique sur la deuxième équipe est le suivant : « Teams[1]. Joueurs[Smith]". (Vous utilisez 1 pour indiquer le deuxième élément dans « Teams », car la liste est indexée zéro.)

Notez que la prise en charge de l’indexation pour les sources de données C++ est limitée ; consultez la liaison de données en profondeur.

Propriétés jointes

Les chemins de propriété peuvent inclure des références aux propriétés jointes. Étant donné que le nom d’identification d’une propriété jointe inclut déjà un point, vous devez placer un nom de propriété attaché entre parenthèses afin que le point ne soit pas traité comme une étape de propriété d’objet. Par exemple, la chaîne à spécifier que vous souhaitez utiliser Canvas.ZIndex comme chemin de liaison est « (Canvas.ZIndex) ». Pour plus d’informations sur les propriétés jointes, consultez la vue d’ensemble des propriétés jointes.

Combinaison de la syntaxe du chemin d’accès aux propriétés

Vous pouvez combiner différents éléments de la syntaxe de chemin de propriété dans une seule chaîne. Par exemple, vous pouvez définir un chemin de propriété qui fait référence à une propriété jointe indexée, si votre source de données avait une telle propriété.

Débogage d’un chemin de propriété de liaison

Étant donné qu’un chemin de propriété est interprété par un moteur de liaison et s’appuie sur des informations qui peuvent être présentes uniquement au moment de l’exécution, vous devez souvent déboguer un chemin de propriété pour la liaison sans pouvoir compter sur la prise en charge conventionnelle du moment de la conception ou de la compilation dans les outils de développement. Dans de nombreux cas, le résultat d’exécution de l’échec de la résolution d’un chemin de propriété est une valeur vide sans erreur, car il s’agit du comportement de secours de secours de conception de la résolution de liaison. Heureusement, Microsoft Visual Studio fournit un mode de sortie de débogage qui peut isoler la partie d’un chemin de propriété qui spécifie une source de liaison n’a pas pu être résolue. Pour plus d’informations sur l’utilisation de cette fonctionnalité d’outil de développement, consultez la section « Débogage » de la liaison de données en profondeur.

Chemin de propriété pour le ciblage d’animation

Les animations s’appuient sur le ciblage d’une propriété de dépendance où les valeurs storyboarded sont appliquées lors de l’exécution de l’animation. Pour identifier l’objet où la propriété à animer existe, l’animation cible un élément par son nom (attribut x :Name). Il est souvent nécessaire de définir un chemin de propriété qui commence par l’objet identifié comme Storyboard.TargetName et se termine par la valeur de propriété de dépendance particulière où l’animation doit s’appliquer. Ce chemin de propriété est utilisé comme valeur pour Storyboard.TargetProperty.

Pour plus d’informations sur la façon de définir des animations en XAML, consultez animations storyboarded.

Ciblage simple

Si vous animez une propriété qui existe sur l’objet ciblé lui-même et que le type de cette propriété peut avoir une animation appliquée directement à celle-ci (plutôt qu’à une sous-propriété de la valeur d’une propriété), vous pouvez simplement nommer la propriété animée sans aucune qualification supplémentaire. Par exemple, si vous ciblez une sous-classe Shape telle que Rectangle et que vous appliquez une couleur animée à la propriété Fill, votre chemin de propriété peut être « Fill ».

Ciblage de propriétés indirectes

Vous pouvez animer une propriété qui est une sous-propriété de l’objet cible. En d’autres termes, s’il existe une propriété de l’objet cible qui est un objet lui-même et que cet objet a des propriétés, vous devez définir un chemin de propriété qui explique comment parcourir cette relation objet-propriété. Chaque fois que vous spécifiez un objet dans lequel vous souhaitez animer une sous-propriété, vous placez le nom de la propriété entre parenthèses et vous spécifiez la propriété dans typename.format propertyname . Par exemple, pour spécifier que vous souhaitez que la valeur de l’objet de la propriété RenderTransform d’un objet cible, vous spécifiez « (UIElement.RenderTransform) » comme première étape dans le chemin de propriété. Ce n’est pas encore un chemin d’accès complet, car aucune animation ne peut s’appliquer directement à une valeur transform. Ainsi, pour cet exemple, vous terminez maintenant le chemin de propriété afin que la propriété de fin soit une propriété d’une sous-classe Transform qui peut être animée par une valeur double : « (UIElement.RenderTransform).( CompositeTransform.TranslateX)"

Spécification d’un enfant particulier dans une collection

Pour spécifier un élément enfant dans une propriété de collection, vous pouvez utiliser un indexeur numérique. Utilisez des crochets « [] » autour de la valeur d’index entier. Vous ne pouvez référencer que des listes triées, et non des dictionnaires. Étant donné qu’une collection n’est pas une valeur qui peut être animée, l’utilisation d’un indexeur ne peut jamais être la propriété de fin dans un chemin de propriété.

Par exemple, pour spécifier que vous souhaitez animer la première couleur d’arrêt de couleur dans un LinearGradientBrush appliqué à la propriété Background d’un contrôle, il s’agit du chemin de propriété : « (Control.Background).( GradientBrush.GradientStops)[0]. (GradientStop.Color)". Notez comment l’indexeur n’est pas la dernière étape du chemin d’accès, et que la dernière étape doit en particulier référencer la propriété GradientStop.Color de l’élément 0 de la collection pour appliquer une valeur animée Color à celle-ci.

Animation d’une propriété jointe

Ce n’est pas un scénario courant, mais il est possible d’animer une propriété jointe, tant que cette propriété jointe a une valeur de propriété qui correspond à un type d’animation. Étant donné que le nom d’identification d’une propriété jointe inclut déjà un point, vous devez placer un nom de propriété attaché entre parenthèses afin que le point ne soit pas traité comme une étape de propriété d’objet. Par exemple, la chaîne à spécifier que vous souhaitez animer la propriété jointe Grid.Row sur un objet, utilisez le chemin de propriété « (Grid.Row) ».

Remarque Pour cet exemple, la valeur de Grid.Row est un type de propriété Int32. vous ne pouvez donc pas l’animer avec une animation double . Au lieu de cela, vous devez définir un ObjectAnimationUsingKeyFrames qui a des composants DiscreteObjectKeyFrame, où ObjectKeyFrame.Value est défini sur un entier tel que « 0 » ou « 1 ».

Règles pour les propriétés d’un chemin de propriété de ciblage d’animation

  • Le point de départ supposé du chemin de propriété est l’objet identifié par un Storyboard.TargetName.
  • Tous les objets et propriétés référencés le long du chemin de propriété doivent être publics.
  • La propriété end (propriété qui est la dernière propriété nommée dans le chemin d’accès) doit être publique, être en lecture-écriture et être une propriété de dépendance.
  • La propriété de fin doit avoir un type de propriété capable d’être animé par l’une des classes étendues de types d’animation (animations couleur, animations doubles, animations point, ObjectAnimationUsingKeyFrames).

Classe PropertyPath

La classe PropertyPath est le type de propriété sous-jacent de Binding.Path pour le scénario de liaison.

La plupart du temps, vous pouvez appliquer un PropertyPath en XAML sans utiliser du code du tout. Toutefois, dans certains cas, vous pouvez définir un objet PropertyPath à l’aide du code et l’affecter à une propriété au moment de l’exécution.

PropertyPath a un constructeur PropertyPath(String) et n’a pas de constructeur par défaut. La chaîne que vous passez à ce constructeur est une chaîne définie à l’aide de la syntaxe du chemin de propriété, comme nous l’avons expliqué précédemment. Il s’agit également de la même chaîne que celle que vous utiliseriez pour affecter le chemin d’accès en tant qu’attribut XAML. La seule autre API de la classe PropertyPath est la propriété Path , qui est en lecture seule. Vous pouvez utiliser cette propriété comme chaîne de construction pour une autre instance PropertyPath .