Partager via

PropertyPath, syntaxe XAML

  • Article

Mise à jour : novembre 2007

L'objet PropertyPath prend en charge une syntaxe XAML inline complexe pour définir différentes propriétés qui acceptent le type PropertyPath comme valeur. Cette rubrique décrit la syntaxe PropertyPath telle qu'elle est appliquée aux syntaxes de liaison et d'animation.

Cette rubrique comprend les sections suivantes.

  • Cas d'emploi de PropertyPath
  • PropertyPath pour les objets dans la liaison de données
  • PropertyPath pour les cibles d'animation
  • PropertyPath dans le code
  • Rubriques connexes

Cas d'emploi de PropertyPath

PropertyPath est un objet commun utilisé dans plusieurs fonctionnalités de Windows Presentation Foundation (WPF). Malgré l'utilisation du PropertyPath commun pour communiquer les informations de chemin de propriété, les utilisations varient pour chaque domaine de fonctionnalités où PropertyPath est utilisé comme type. Par conséquent, il s'avère plus pratique de documenter les syntaxes pour chaque fonctionnalité.

À l'origine, WPF utilise PropertyPath pour décrire les chemins de modèle objet permettant de parcourir les propriétés d'une source de données d'objet, ainsi que pour décrire le chemin d'accès cible pour les animations ciblées.

Certaines propriétés de style et de modèle telles que Setter.Property prennent un nom de propriété qualifié qui ressemble en apparence à PropertyPath. Il ne s'agit toutefois pas d'un vrai PropertyPath, mais plutôt d'une utilisation au format de chaîne owner.property qualifiée activée par le processeur XAML en association avec le convertisseur de type pour DependencyProperty.

PropertyPath pour les objets dans la liaison de données

La liaison de données est une fonctionnalité de WPF qui permet de créer une liaison vers la valeur cible d'une propriété de dépendance. Toutefois, la source d'une liaison de données ne doit pas nécessairement être une propriété de dépendance. Il peut en effet s'agir de n'importe quel type de propriété reconnu par le fournisseur de données applicable. Les chemins de propriété sont utilisés en particulier pour ObjectDataProvider, qui sert à obtenir des sources de liaison à partir d'objets Common Language Runtime (CLR) et de leurs propriétés.

La liaison de données vers XML n'utilise pas PropertyPath, car elle n'utilise pas Path dans Binding. En lieu et place, vous utilisez XPath et spécifiez la syntaxe XPath valide dans le modèle DOM (Document Object Model) XML des données. XPath est également spécifié en tant que chaîne, mais n'est pas documenté ici (voir Comment : effectuer une liaison à des données XML à l'aide d'un XMLDataProvider et de requêtes XPath).

Pour bien comprendre les chemins de propriété dans la liaison de données, vous devez savoir qu'il est possible de cibler la liaison sur une valeur de propriété donnée ou de créer une liaison vers des propriétés cibles qui obtiennent des listes ou des collections. Si vous liez des collections, le chemin de propriété doit référencer une collection, à la place d'éléments de collection individuels. Le moteur de liaison de données établit automatiquement la correspondance des collections de source avec la cible, ce qui entraîne un comportement tel que le remplissage de ListBox avec un tableau d'éléments.

Propriété unique de l'objet immédiat en tant que contexte de données

<Binding Path="propertyName" .../>

propertyName doit correspondre au nom d'une propriété située dans le DataContext actuel pour une utilisation Path. Si la liaison met à jour la source, cette propriété doit être en lecture/écriture et l'objet source doit être mutable.

Indexeur unique de l'objet immédiat en tant que contexte de données

<Binding Path="[key]" .../>

key doit correspondre à l'index typé vers un dictionnaire ou une table de hachage ou à l'index d'entiers d'un tableau. En outre, la valeur de la clé doit être un type pouvant être directement lié à la propriété où elle est appliquée. Par exemple, une table de hachage qui contient des clés et des valeurs de chaîne peut être utilisée de cette manière pour créer une liaison avec du texte pour un TextBox. Ou, si la clé pointe vers une collection ou un sous-index, vous pouvez utiliser cette syntaxe pour créer une liaison avec une propriété de collection cible. Sinon, vous devez référencer une propriété spécifique via une syntaxe telle que <Binding Path="[key].propertyName" .../>.

Vous pouvez spécifier le type de l'index, si nécessaire. Pour plus d'informations sur cet aspect d'un chemin de propriété indexée, consultez Binding.Path.

Propriétés multiples (ciblage de propriété indirect)

<Binding Path="propertyName.propertyName2" .../>

propertyName doit correspondre au nom d'une propriété qui est le DataContext actuel. Les propriétés de chemin propertyName et propertyName2 peuvent être des propriétés qui existent dans une relation, où propertyName2 correspond à une propriété existant dans le type qui est la valeur de propertyName.

Propriété unique, hors de la portée de nom de chargement XAML (réflexion du runtime)

<object property="ownerType.propertyName" .../>

Cette syntaxe est réservée exclusivement pour le chemin source pour une liaison de données avec une propriété CLR et ne peut correspondre qu'à un seul chemin vers des propriétés. propertyName doit correspondre au nom d'une propriété existant dans ownerType. ownerType est censé être un type pouvant être déterminé d'après la réflexion du runtime. Il est de ce fait interdit de qualifier ownerType avec un espace de noms XML, car ce préfixe n'a de sens que pour le langage XAML de compilation et non pour la réflexion. Consultez la section suivante.

Propriété unique, attachée ou en attente de contexte via un style/modèle

<object property="(ownerType.propertyName)" .../>

Les parenthèses indiquent que cette propriété dans PropertyPath doit être construite à l'aide d'une qualification partielle. Elle peut utiliser un espace de noms XML pour rechercher le type. Le ownerType recherche les types auxquels un processeur XAML peut accéder via les déclarations XmlnsDefinitionAttribute de chaque assembly. La plupart des applications disposent de l'espace de noms XML par défaut mappé à l'espace de noms https://schemas.microsoft.com/winfx/2006/xaml/presentation. Un préfixe ne s'avère de ce fait généralement nécessaire que pour les types personnalisés ou les types en dehors de cet espace de noms. propertyName doit correspondre au nom d'une propriété existant dans l'ownerType. En règle générale, cette syntaxe est utilisée dans l'un des cas suivants :

  • Le chemin est spécifié en langage XAML dont le style ou le modèle n'est associé à aucun type de cible. Une utilisation qualifiée n'est généralement pas valide pour les autres cas que celui-ci. En effet, dans les cas sans style et sans modèle, la propriété existe dans une instance, pas dans un type.

  • La propriété est attachée.

  • Vous créez une liaison avec une propriété statique. Dans ce cas, ownerType est réellement un type.

Pour une utilisation en tant que cible de table de montage séquentiel, la propriété spécifiée en tant que propertyName doit être DependencyProperty.

Parcours de source (liaison avec des hiérarchies de collections)

<object Path="propertyName/propertyNameX" .../>

L'élément / de cette syntaxe sert à naviguer dans un objet source de données hiérarchique. Il est possible de spécifier plusieurs pas dans la hiérarchie à l'aide de caractères / successifs. Le parcours de source tient compte de la position du pointeur d'enregistrement actif, déterminée en synchronisant les données avec l'interface utilisateur de la vue. Pour plus d'informations sur la liaison avec des objets source de données hiérarchiques et sur le pointeur d'enregistrement actif dans le cadre de la liaison de données, consultez Comment : utiliser le modèle maître/détail avec des données hiérarchiques ou Vue d'ensemble de la liaison de données.

Remarque :

En apparence, cette syntaxe ressemble à XPath. Une vraie expression XPath permettant de créer une liaison avec une source de données XML n'est pas utilisée comme valeur Path et doit plutôt être utilisée pour la propriété XPath mutuellement exclusive.

Indexeurs multiples

<object Path="[index1,index2...]" .../>
or
<object Path="propertyName[index,index2...]" .../>

Si un objet donné prend en charge plusieurs indexeurs, ceux-ci peuvent être spécifiés dans l'ordre, de la même manière qu'un tableau faisant référence à une syntaxe. L'objet en question peut correspondre au contexte actuel ou à la valeur d'une propriété qui contient un objet d'index multiple.

Par défaut, les valeurs d'indexeur sont typées à l'aide des caractéristiques de l'objet sous-jacent. Vous pouvez spécifier le type de l'index, si nécessaire. Pour plus d'informations sur le typage des indexeurs, consultez Binding.Path.

Mélange des syntaxes

Chacune des syntaxes ci-dessus peut être intercalée. Par exemple, l'exemple suivant crée un chemin de propriété vers la couleur à une coordonnée x,y particulière d'une propriété ColorGrid qui contient un tableau de grille de pixels d'objets SolidColorBrush :

<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" .../>

PropertyPath pour les cibles d'animation

La propriété cible d'une animation doit être une propriété de dépendance qui comporte un Freezable ou un type primitif. Toutefois, la propriété ciblée d'un type et la propriété animée éventuelle peuvent exister sur des objets différents. En ce qui concerne les animations, un chemin de propriété sert à définir la connexion entre la propriété de l'objet de cible d'animation nommé et la propriété d'animation cible prévue, en parcourant les relations des propriétés d'objets dans les valeurs de propriété.

Considérations générales relatives aux propriétés d'objet pour les animations

Pour plus d'informations sur les concepts d'animation en général, consultez Vue d'ensemble des tables de montage séquentiel et Vue d'ensemble de l'animation.

Le type valeur ou la propriété animée doit correspondre à un Freezable ou à un type primitif. La propriété qui commence le chemin doit correspondre au nom d'une propriété de dépendance qui existe pour le type TargetName spécifié.

Pour prendre en charge le clonage afin d'animer un Freezable déjà figé, l'objet spécifié par TargetName doit être une classe dérivée FrameworkElement ou FrameworkContentElement.

Propriété unique sur l'objet cible

<animation Storyboard.TargetProperty="propertyName" .../>

propertyName doit correspondre au nom d'une propriété de dépendance qui existe pour le type TargetName spécifié.

Ciblage de propriété indirect

<animation Storyboard.TargetProperty="propertyName.propertyName2" .../>

propertyName doit être une propriété correspondant à un type valeur Freezable ou à un type primitif, qui existe pour le type TargetName spécifié.

propertyName2 doit correspondre au nom d'une propriété de dépendance qui existe sur l'objet représentant la valeur de propertyName. Autrement dit, propertyName2 doit exister en tant que propriété de dépendance sur le type correspondant à propertyNamePropertyType.

Le ciblage indirect d'animations est nécessaire en raison des styles et modèles appliqués. Pour pouvoir cibler une animation, vous avez besoin d'un TargetName sur un objet cible. Ce nom est défini par x:Name ou par Name. Les éléments de modèle et de style peuvent également avoir des noms. Toutefois, ces noms ne sont valides que dans la portée de nom du style et du modèle. (Si des modèles et des styles partagent des portées de nom avec une balise d'application, les noms ne peuvent pas être uniques. En effet, les styles et modèles sont littéralement partagés entre des instances et préservent les noms en double.) Par conséquent, si les propriétés d'un élément que vous souhaitez animer proviennent d'un style ou d'un modèle, vous devez commencer par une instance d'élément nommé qui n'est pas issue d'un modèle de style. Ensuite, vous devez cibler l'arborescence d'éléments visuels du style ou du modèle pour accéder à la propriété à animer.

Par exemple, la propriété Background d'un Panel est un Brush complet (en réalité, un SolidColorBrush) qui provient d'un modèle de thème. Pour animer complètement un Brush, il devrait y avoir un BrushAnimation (probablement un pour chaque type Brush), mais ce type n'existe pas. Pour animer un Brush, vous animez plutôt des propriétés d'un type Brush particulier. Vous devez partir de SolidColorBrush vers Color afin d'y appliquer un ColorAnimation. Pour cet exemple, le chemin de propriété serait Background.Color.

Propriétés attachées

<animation Storyboard.TargetProperty="(ownerType.propertyName)" .../>

Les parenthèses indiquent que cette propriété dans PropertyPath doit être construite à l'aide d'une qualification partielle. Elle peut utiliser un espace de noms XML pour rechercher le type. Le ownerType recherche les types auxquels un processeur XAML peut accéder via les déclarations XmlnsDefinitionAttribute de chaque assembly. La plupart des applications disposent de l'espace de noms XML par défaut mappé à l'espace de noms https://schemas.microsoft.com/winfx/2006/xaml/presentation. Un préfixe ne s'avère de ce fait généralement nécessaire que pour les types personnalisés ou les types en dehors de cet espace de noms. propertyName doit correspondre au nom d'une propriété existante dans l'ownerType. La propriété spécifiée en tant que propertyName doit être un DependencyProperty. (Toutes les propriétés attachées WPF étant implémentées en tant que propriétés de dépendance, ce problème ne concerne que les propriétés attachées personnalisées.)

Indexeurs

<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" .../>

La plupart des propriétés de dépendance ou des types Freezable ne prennent pas d'indexeur en charge. Par conséquent, la seule utilisation d'un indexeur dans un chemin d'animation se situe à une position intermédiaire entre la propriété qui démarre la chaîne sur la cible nommée et la propriété animée éventuelle. Dans la syntaxe fournie, il s'agit de propertyName2. Par exemple, l'utilisation d'un indexeur peut s'avérer nécessaire si la propriété intermédiaire est une collection telle que TransformGroup, dans un chemin de propriété tel que RenderTransform.Children[1].Angle.

PropertyPath dans le code

L'utilisation de code pour PropertyPath, notamment la construction de PropertyPath, est documentée dans la rubrique de référence relative à PropertyPath.

En règle générale, PropertyPath est conçu pour utiliser deux constructeurs différents : un pour les utilisations de liaison et les utilisations d'animation les plus simples, et un autre pour les utilisations d'animation complexes. Utilisez la signature PropertyPath(Object) dans le cadre d'une liaison, où l'objet correspond à une chaîne. Utilisez la signature PropertyPath(Object) pour les chemins d'animation pas à pas, où l'objet correspond à DependencyProperty. Utilisez la signature PropertyPath(String, array<Object[]) pour les animations complexes. Ce constructeur utilise une chaîne de jeton pour le premier paramètre et un tableau d'objets qui remplissent les positions de la chaîne de jeton pour définir une relation de chemin de propriété.

Voir aussi

Concepts

Vue d'ensemble de la liaison de données

Vue d'ensemble des tables de montage séquentiel

Référence

PropertyPath