Syntaxe XAML de PropertyPath

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.

Où PropertyPath est utilisé

PropertyPath est un objet courant utilisé dans plusieurs fonctionnalités de Windows Presentation Foundation (WPF). Malgré l'usage courant de PropertyPath pour transmettre les informations sur le chemin de propriété, l'utilisation pour chaque domaine fonctionnel où PropertyPath est utilisé comme un type varie. 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.

Certaines propriétés de style et de modèle, comme Setter.Property, prennent un nom de propriété qualifié qui ressemble superficiellement à un PropertyPath. Cependant, ce n'est pas un véritable PropertyPath ; au contraire, il s'agit d'un format de chaîne propriétaire.property qualifié, activé par le processeur XAML WPF en combinaison avec le convertisseur de type pour DependencyProperty.

Chemin de propriété 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 telle liaison de données n’a pas besoin d’être une propriété de dépendance ; il peut s’agir de 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 la ObjectDataProvider, qui est utilisée pour obtenir des sources de liaison à partir d'objets CLR (Common Language Runtime) et de leurs propriétés.

Notez que la liaison de données à XML n'utilise pas PropertyPath, parce qu'elle n'utilise pas Path dans le Binding. 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 aspect essentiel pour comprendre les chemins de propriété dans la liaison de données est que vous pouvez orienter la liaison vers une valeur de propriété individuelle, ou vous pouvez plutôt lier à des propriétés cibles acceptant des listes ou des collections. Si vous liez des collections, par exemple, lier un ListBox qui s'étend en fonction du nombre d'éléments de données dans la collection, alors votre chemin de propriété doit référencer l'objet de collection, et non les éléments individuels de la collection. Le moteur de liaison de données fera correspondre automatiquement la collection utilisée comme source de données au type de la cible de liaison, ce qui entraînera un comportement tel que le remplissage d’un tableau d’éléments ListBox.

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 l'actuel DataContext pour une utilisation Path. Si votre liaison met à jour la source, cette propriété doit être en lecture/écriture et l’objet source doit être mutable.

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

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

key doit être l’index typé d’un dictionnaire ou d’une table de hachage, ou l’index entier d’un tableau. En outre, la valeur de la clé doit être un type directement lié à la propriété où elle est appliquée. 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. Ou, si la clé pointe vers une collection ou une sous-index, vous pouvez utiliser cette syntaxe pour établir 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 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é, consultez Binding.Path.

Propriété multiple (ciblage indirect de propriété)

<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 d'accès propertyName et propertyName2 peuvent être toutes propriétés existant dans une relation, lorsque propertyName2 est une propriété présente dans le type qui est la valeur de propertyName.

Propriété unique, attachée ou autrement Type-Qualified

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

Les parenthèses indiquent que cette propriété dans un PropertyPath doit être construite à l’aide d’une qualification partielle. Il peut utiliser un espace de noms XML pour rechercher le type avec un mappage approprié. Le ownerType recherche des types auxquels un processeur XAML a accès, via les XmlnsDefinitionAttribute déclarations dans chaque assembly. La plupart des applications ont l’espace de noms XML par défaut mappé à l’espace de noms http://schemas.microsoft.com/winfx/2006/xaml/presentation. Par conséquent, un préfixe est généralement nécessaire uniquement pour les types personnalisés ou les types autrement hors de cet espace de noms. propertyName doit être le nom d’une propriété existante sur le ownerType. Cette syntaxe est généralement utilisée pour l’un des cas suivants :

• Le chemin est spécifié en XAML dans un style ou un modèle qui n'a pas de type cible défini. Une utilisation qualifiée n’est généralement pas valide pour les cas autres que celui-ci, car dans les cas non-style, non-modèle, la propriété existe sur une instance, et non sur un type.

• La propriété est une propriété attenante.

• Vous vous liez à 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 à des hiérarchies de collections)

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

La barre oblique (/) dans cette syntaxe est utilisée pour naviguer au sein d'un objet de source de données hiérarchique, et plusieurs étapes dans la hiérarchie avec des caractères / successifs sont possibles. Le parcours de la source tient compte de la position actuelle du pointeur de l’enregistrement, qui est déterminée par la synchronisation des 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érarchiques et le concept de pointeur d’enregistrement actif dans la liaison de données, consultez Utiliser le modèle Master-Detail avec des données hiérarchiques ou une vue d’ensemble de la liaison de données.

Vues de collection

Pour référencer une vue de collection nommée, préfixez le nom de la vue de collection avec le caractère de hachage (#).

Pointeur d’enregistrement actuel

Pour référencer le pointeur d’enregistrement actuel pour un scénario de liaison de données de vue de collection ou de maître-détail, démarrez la chaîne de chemin avec une barre oblique (/). Tout chemin au-delà de la barre oblique est parcouru à partir du pointeur d’enregistrement actif.

Plusieurs indexeurs

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

ou

<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 d’index multiple.

Par défaut, les valeurs de l’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 la saisie des indexeurs, consultez Binding.Path.

Combinaison de syntaxes

Chacune des syntaxes indiquées ci-dessus peut être entrelacée. Par exemple, voici un exemple qui crée un chemin de propriété vers la couleur à des coordonnées spécifiques x,y d'une propriété ColorGrid contenant un tableau de grille de pixels avec des objets SolidColorBrush :

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

Échappements pour les chaînes de chemin d’accès aux propriétés

Pour certains objets métier, vous pouvez rencontrer un cas où la chaîne de chemin de propriété nécessite une séquence d’échappement afin d’analyser correctement. La nécessité d’échapper doit être rare, car un grand nombre de ces caractères ont des problèmes d’interaction de nommage similaires dans les langages qui seraient généralement utilisés pour définir l’objet métier.

• À l’intérieur des indexeurs ([ ]), le caractère d’insertion (^) échappe au caractère suivant.

• Vous devez échapper (à l’aide d’entités XML) certains caractères spéciaux à la définition du langage XML. Permet & d’échapper au caractère « & ». Utilisez > pour échapper à la balise de fin «> ».

• Vous devez échapper (à l’aide d’une barre oblique \inverse) caractères spéciaux au comportement d’analyseur XAML WPF pour le traitement d’une extension de balisage.

  • Barre oblique inverse (\) constitue le caractère d'échappement en soi.

  • Le signe égal (=) sépare le nom de propriété de la valeur de propriété.

  • Virgule (,) sépare les propriétés.

  • L'accolade droite (}) est la fin d'une extension de balisage.

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 sur un type et la propriété animée finale peuvent exister sur différents objets. Pour les animations, un chemin de propriété sert à définir la connexion entre la propriété spécifiée de l'objet cible d'animation et la propriété d'animation cible prévue, en naviguant à travers les relations propriété-objet dans les valeurs des propriétés.

Considérations générales Object-Property concernant les animations

Pour plus d’informations sur les concepts d’animation en général, consultez Vue d’ensemble de Storyboards et Vue d’ensemble de l’animation.

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 que le clonage soit pris en charge pour animer un Freezable déjà figé, l'objet spécifié par TargetName doit être une classe dérivée de FrameworkElement ou de FrameworkContentElement.

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és indirectes

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

propertyName doit être une propriété qui est un type de valeur Freezable ou un type primitif, 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 des 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 puissent également avoir des noms, ces noms sont valides uniquement dans 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 Brush complet (en fait un SolidColorBrush) qui provient d’un 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 Color pour y appliquer un ColorAnimation. Le chemin de propriété de cet exemple serait Background.Color.

Propriétés jointes

<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. Il peut utiliser un espace de noms XML pour rechercher le type. Le ownerType recherche des types auxquels un processeur XAML a accès, via les XmlnsDefinitionAttribute déclarations dans chaque assembly. La plupart des applications ont l’espace de noms XML par défaut mappé à l’espace de noms http://schemas.microsoft.com/winfx/2006/xaml/presentation. Par conséquent, un préfixe est généralement nécessaire uniquement pour les types personnalisés ou les types autrement hors de cet espace de noms. propertyName doit être le nom d’une propriété existante 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, un indexeur ne peut être utilisé que dans un chemin d’animation à une position intermédiaire entre la propriété qui initie la chaîne sur la cible désignée et la propriété finalement animée. Dans la syntaxe fournie, cela est 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, a été conçu pour utiliser deux constructeurs différents : l'un pour les usages de liaison et d'animation les plus simples, et l'autre pour les usages 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 des positions dans la chaîne de jeton pour définir une relation de chemin de propriété.

Voir aussi

• PropertyPath
• Vue d’ensemble de la liaison de données
• Vue d'ensemble des storyboards