Syntaxe XAML PropertyPath

Article
08/10/2023

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

Cas d’utilisation de PropertyPath

PropertyPath est un objet courant utilisé dans plusieurs fonctionnalités de Windows Presentation Foundation (WPF). Malgré l’utilisation des informations courantes PropertyPath sur le chemin de propriété, les utilisations pour chaque zone de fonctionnalité utilisée PropertyPath comme type varient. Par conséquent, il est plus pratique de documenter les syntaxes par fonctionnalité.

Principalement, WPF utilise PropertyPath pour décrire les chemins d’accès du modèle objet pour parcourir les propriétés d’une source de données d’objet et décrire le chemin cible pour les animations ciblées.

Certains styles et propriétés de modèle, comme Setter.Property prendre un nom de propriété qualifié qui ressemble superficiellement à un PropertyPath. Mais ce n’est pas vrai PropertyPath; au lieu de cela, il s’agit d’une utilisation de format de chaîne propriétaire.property qualifiée qui est activée par le processeur XAML WPF en combinaison 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é WPF dans laquelle vous pouvez établir une liaison à la valeur cible de n’importe quelle 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, elle peut être n’importe quel type de propriété reconnu par le fournisseur de données applicable. Les chemins de propriété sont particulièrement utilisés pour l’obtention ObjectDataProviderde sources de liaison à partir d’objets CLR (Common Language Runtime) et de leurs propriétés.

Notez que la liaison de données au format XML n’utilise PropertyPathpas , car elle n’est pas utilisée Path dans le Bindingfichier . Au lieu de cela, vous utilisez XPath et spécifiez une syntaxe XPath valide dans 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 ; consultez Lier des données XML à l’aide d’une requête XMLDataProvider et XPath.

Un élément essentiel qui permet de comprendre les chemins de propriété dans la liaison de données est que vous pouvez cibler la liaison à une valeur de propriété individuelle, ou effectuer une liaison pour cibler des propriétés qui acceptent des listes ou des collections. Si vous êtes des collections de liaisons, par exemple, une ListBox liaison qui s’étend en fonction du nombre d’éléments de données dans la collection, votre chemin de propriété doit référencer l’objet de collection, et non les éléments de collection individuels. Le moteur de liaison de données correspond à la collection utilisée comme source de données au type de la cible de liaison automatiquement, ce qui entraîne un comportement tel que le remplissage d’un ListBox tableau d’éléments.

Propriété unique sur l’objet immédiat comme contexte de données

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

propertyName doit être le nom d’une propriété qui se trouve dans le courant DataContext d’une Path utilisation. Si votre liaison met à jour la source, cette propriété doit être accessible en lecture/écriture et l’objet source doit être mutable.

Indexeur unique sur l’objet immédiat comme contexte de données

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

key doit être l’index typé vers un dictionnaire ou une table de hachage, ou l’index entier d’un tableau. Par ailleurs, la valeur de la clé doit être un type pouvant être directement lié à la propriété sur laquelle il est appliqué. Par exemple, une table de hachage qui contient des clés de chaîne et des valeurs de chaîne peut être utilisée de cette façon pour lier du texte pour un TextBox. Si la clé pointe vers une collection ou un sous-index, vous pouvez utiliser cette syntaxe pour effectuer une liaison à une propriété de collection cible. Sinon, vous devez référencer une propriété spécifique par le biais d’une syntaxe de type <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é, consultez Binding.Path.

Plusieurs propriétés (ciblage de propriété indirect)

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

propertyName doit être le nom d’une propriété qui est la propriété actuelle DataContext. Les propriétés de chemin propertyName et propertyName2 peuvent être des propriétés qui existent dans une relation, où propertyName2 est une propriété qui existe sur le type qui est la valeur de propertyName.

Propriété unique, jointe ou typée

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

Les parenthèses indiquent que cette propriété dans un PropertyPath doit être construite à l’aide d’une qualification partielle. Elle peut utiliser un espace de noms XML pour rechercher le type avec un mappage approprié. Les ownerType types de recherche auxquels un processeur XAML a accès, via les XmlnsDefinitionAttribute déclarations de chaque assembly. Dans la plupart des applications, l’espace de noms XML par défaut est mappé à l’espace de noms http://schemas.microsoft.com/winfx/2006/xaml/presentation. Un préfixe est donc généralement nécessaire uniquement 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 sur le ownerType. Cette syntaxe est généralement utilisée pour l’un des cas suivants :

Le chemin d’accès est spécifié en XAML qui se trouve dans un style ou un modèle qui n’a pas de type cible spécifié. Une utilisation qualifiée n’est généralement pas valide pour les autres cas, car dans les cas sans style ni modèle, la propriété existe sur une instance et non un type.
La propriété est une propriété jointe.
Vous effectuez une liaison à une propriété statique.

Pour une utilisation comme cible storyboard, la propriété spécifiée comme propertyName doit être un DependencyProperty.

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

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

L’élément / de cette syntaxe est utilisé pour naviguer dans un objet de source de données hiérarchique. Plusieurs étapes dans la hiérarchie présentant des caractères / successifs sont prises en charge. Le parcours de source désigne la position du pointeur d’enregistrement actuel, qui est déterminée en synchronisant les données avec l’interface utilisateur de sa vue. Pour plus d’informations sur la liaison avec des objets de source de données hiérarchique et sur le concept de pointeur d’enregistrement actuel dans la liaison de données, consultez 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

Superficiellement, cette syntaxe ressemble à XPath. Une véritable expression XPath pour la liaison à une source de données XML n’est pas utilisée comme Path valeur et doit plutôt être utilisée pour la propriété mutuellement exclusive XPath .

Vues de collection

Pour référencer une vue de collection nommée, faites précéder le nom de la vue de collection du caractère dièse (#).

Pointeur d’enregistrement actuel

Pour référencer le pointeur d’enregistrement actuel dans un scénario de vue de collection ou de liaison de données maître/détail, démarrez la chaîne de chemin par une barre oblique (/). Tous les chemins après la barre oblique sont parcourus à partir du pointeur d’enregistrement actuel.

Plusieurs indexeurs

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

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

Si un objet donné prend en charge plusieurs indexeurs, ces indexeurs peuvent être spécifiés dans l’ordre, comme une syntaxe de référencement de tableau. L’objet en question peut être le contexte actuel ou la valeur d’une propriété qui contient un objet avec plusieurs index.

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

Mélange de syntaxes

Chacune des syntaxes ci-dessus peut être parsemée. Par exemple, voici un exemple qui crée un chemin de propriété vers la couleur à un x,y particulier d’une ColorGrid propriété qui contient un tableau de grilles de pixels d’objets SolidColorBrush :

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

Échappements pour les chaînes de chemin de propriété

Pour certains objets métiers, la chaîne de chemin de propriété peut nécessiter une séquence d’échappement pour effectuer correctement l’analyse. La nécessité d’une séquence d’échappement doit être rare, car la plupart de ces caractères ont des problèmes d’interactions de noms similaires dans les langages qui doivent normalement être utilisés pour définir l’objet métier.

À l’intérieur des indexeurs ([]), l’accent circonflexe (^) échappe le caractère suivant.
Vous devez échapper (à l’aide d’entités XML) certains caractères qui sont spécifiques de la définition de langage XML. Utilisez & pour échapper le caractère « & ». Permet > d’échapper à la balise de fin «> ».
Vous devez échapper (à l’aide de la barre oblique inverse \) les caractères spécifiques du comportement de l’analyseur XAML WPF pour le traitement d’une extension de balisage.
- La barre oblique inverse (\) est le caractère d’échappement lui-même.
- Le signe égal (=) sépare le nom et la valeur de la propriété.
- La virgule (,) sépare les propriétés.
- L’accolade fermante (}) marque la fin d’une extension de balisage.

Remarque

Techniquement, ces échappements fonctionnent également pour un chemin de propriété de plan conceptuel, mais vous parcourez habituellement des modèles d’objet pour les objets WPF existants et l’échappement est inutile.

PropertyPath pour les cibles d’animation

La propriété cible d’une animation doit être une propriété de dépendance qui prend 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. Pour les animations, un chemin de propriété permet de définir la connexion entre la propriété de l’objet cible de l’animation nommée et la propriété de l’animation cible prévue, en parcourant les relations objet-propriété dans les valeurs de propriété.

Considérations générales relatives à la relation objet-propriété des animations

Pour plus d’informations sur les concepts d’animation en général, consultez Vue d’ensemble des plans conceptuels et Vue d’ensemble des animations.

Le type valeur ou la propriété animée doit être un Freezable type ou une primitive. La propriété qui démarre le chemin d’accès doit être le nom d’une propriété de dépendance qui existe sur le type spécifié TargetName .

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

Propriété unique sur l’objet cible

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

propertyName doit être le nom d’une propriété de dépendance qui existe sur le type spécifié TargetName .

Ciblage de propriété indirect

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

propertyName doit être une propriété qui est un Freezable type valeur ou une primitive, qui existe sur le type spécifié TargetName .

propertyName2 doit être le nom d’une propriété de dépendance qui existe sur l’objet qui est la valeur de propertyName. En d’autres termes, propertyName2 doit exister en tant que propriété de dépendance sur le type qui est le propertyNamePropertyType.

Le ciblage indirect d’animations est nécessaire en raison des styles et modèles appliqués. Pour cibler une animation, vous avez besoin d’un TargetName objet cible, et ce nom est établi par x :Name ou Name. Bien que les éléments de modèle et de style peuvent également avoir des noms, ces noms sont uniquement valides au sein de la portée de nom du style et du modèle. (Si les modèles et les styles partagent des portées de noms avec le balisage d’application, les noms n’ont pas pu être uniques. Les styles et les modèles sont littéralement partagés entre les instances et perpétuent les noms en double.) Par conséquent, si les propriétés individuelles 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ée qui ne provient pas d’un modèle de style, puis cibler dans l’arborescence visuelle de style ou de modèle pour arriver à la propriété que vous souhaitez animer.

Par exemple, la Background propriété d’un Panel est un modèle de thème complet Brush (en fait un SolidColorBrush) qui provient d’un modèle de thème. Pour animer complètement Brush , il faudrait un BrushAnimation (probablement un pour chaque Brush type) et il n’existe aucun type de ce type. Pour animer un pinceau, vous animez plutôt les propriétés d’un type particulier Brush . Vous devez passer de SolidColorBrush son à son Color pour appliquer un ColorAnimation là-bas. Le chemin de propriété pour cet exemple est Background.Color.

Propriétés attachées

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

Les parenthèses indiquent que cette propriété dans un PropertyPath doit être construite à l’aide d’une qualification partielle. Elle peut utiliser un espace de noms XML pour rechercher le type. Les ownerType types de recherche auxquels un processeur XAML a accès, via les XmlnsDefinitionAttribute déclarations de chaque assembly. Dans la plupart des applications, l’espace de noms XML par défaut est mappé à l’espace de noms http://schemas.microsoft.com/winfx/2006/xaml/presentation. Un préfixe est donc généralement nécessaire uniquement 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 sur le ownerType. Propriété spécifiée comme propertyName doit être un DependencyProperty. (Toutes les propriétés jointes WPF sont implémentées en tant que propriétés de dépendance. Ce problème concerne uniquement les propriétés jointes personnalisées.)

Indexeurs

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

La plupart des propriétés ou Freezable types de dépendance ne prennent pas en charge un indexeur. Par conséquent, la seule utilisation d’un indexeur dans un chemin d’animation est au niveau d’une position intermédiaire entre la propriété qui commence 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, une utilisation de l’indexeur peut être 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 du code pour PropertyPath, y compris la construction d’un PropertyPath, est documentée dans la rubrique de référence pour PropertyPath.

En général, PropertyPath il 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 pour les utilisations d’animation complexes. Utilisez la PropertyPath(Object) signature pour les utilisations de liaison, où l’objet est une chaîne. Utilisez la signature pour les PropertyPath(Object) chemins d’animation en une étape, où l’objet est un DependencyProperty. Utilisez la PropertyPath(String, Object[]) signature pour les animations complexes. Ce dernier 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é.