PropertyPath XAML-Syntax

2025-05-07

Das PropertyPath Objekt unterstützt eine komplexe Inline-XAML-Syntax zum Festlegen verschiedener Eigenschaften, die den PropertyPath Typ als Wert verwenden. In diesem Thema wird die PropertyPath Syntax dokumentiert, die auf Bindungs- und Animationssyntaxen angewendet wird.

Wo PropertyPath verwendet wird

PropertyPath ist ein gängiges Objekt, das in mehreren Windows Presentation Foundation (WPF)-Features verwendet wird. Trotz der gemeinsamen PropertyPath Verwendung von Eigenschaftspfadinformationen variieren die Verwendungen für jeden Featurebereich, in dem PropertyPath als Typ verwendet wird. Daher ist es praktischer, die Syntaxen pro Feature zu dokumentieren.

In erster Linie wird PropertyPath WPF verwendet, um Objektmodellpfade zum Durchlaufen der Eigenschaften einer Objektdatenquelle zu beschreiben und den Zielpfad für gezielte Animationen zu beschreiben.

Einige Stil- und Vorlageneigenschaften, z Setter.Property . B. einen qualifizierten Eigenschaftsnamen, der oberflächlich einem PropertyPathähnelt. Aber dies ist kein echtes PropertyPath; stattdessen handelt es sich um eine qualifizierte Anwendung der Zeichenfolgenformatnutzung „owner.property“, die durch den WPF-XAML-Prozessor in Verbindung mit dem Typkonverter für aktiviert wird.

PropertyPath für Objekte in der Datenbindung

Die Datenbindung ist ein WPF-Feature, mit dem Sie eine Bindung an den Zielwert einer beliebigen Abhängigkeitseigenschaft vornehmen können. Die Quelle einer solchen Datenbindung muss jedoch keine Abhängigkeitseigenschaft sein; es kann sich um einen beliebigen Eigenschaftstyp handeln, der vom entsprechenden Datenanbieter erkannt wird. Eigenschaftenpfade werden insbesondere für das ObjectDataProviderAbrufen von Bindungsquellen aus CLR-Objekten (Common Language Runtime) und deren Eigenschaften verwendet.

Beachten Sie, dass die Datenbindung an XML PropertyPath nicht verwendet, weil sie Path nicht in der Binding nutzt. Stattdessen verwenden XPath und geben gültige XPath-Syntax in das XML-Dokumentenobjektmodell (DOM) der Daten ein. XPath ist auch als Zeichenfolge angegeben, wird hier jedoch nicht dokumentiert; siehe Bind to XML Data Using an XMLDataProvider and XPath Queries.

Ein Schlüssel zum Verständnis von Eigenschaftspfaden in der Datenbindung besteht darin, dass Sie die Bindung auf einen einzelnen Eigenschaftswert ausrichten können, oder Sie können stattdessen an Zieleigenschaften binden, die Listen oder Auflistungen enthalten. Wenn Sie Sammlungen binden, z. B. eine Bindung ListBox , die je nach Anzahl der Datenelemente in der Auflistung erweitert wird, sollte ihr Eigenschaftspfad auf das Auflistungsobjekt verweisen, nicht auf einzelne Auflistungselemente. Das Datenbindungsmodul stimmt die als Datenquelle verwendete Sammlung automatisch mit dem Typ des Bindungsziels überein, was zu einem Verhalten wie der Befüllung eines ListBox mit einem Elementenarray führt.

Einzelne Eigenschaft für das Direktobjekt als Datenkontext

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

propertyName muss aufgelöst werden, um der Name einer Eigenschaft zu sein, die sich in der aktuellen DataContext für eine Path Verwendung befindet. Wenn die Bindung die Quelle aktualisiert, muss diese Eigenschaft lese-/schreibgeschützt sein, und das Quellobjekt muss änderbar sein.

Einzelner Indexer für das unmittelbare Objekt als Datenkontext

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

key muss entweder der eingegebene Index für ein Wörterbuch oder eine Hashtabelle oder der ganzzahlige Index eines Arrays sein. Außerdem muss der Wert des Schlüssels ein Typ sein, der direkt an die Eigenschaft gebunden werden kann, auf die er angewendet wird. Beispielsweise kann eine Hashtabelle, die Zeichenfolgenschlüssel und Zeichenfolgenwerte enthält, auf diese Weise verwendet werden, um Text für ein TextBox zu binden. Oder wenn der Schlüssel auf eine Auflistung oder einen Unterindex verweist, können Sie diese Syntax verwenden, um eine Bindung an eine Zielsammlungseigenschaft zu erstellen. Andernfalls müssen Sie über eine Syntax wie <Binding Path="[key].propertyName" .../>z. B. auf eine bestimmte Eigenschaft verweisen.

Sie können bei Bedarf den Indextyp angeben. Ausführliche Informationen zu diesem Aspekt eines indizierten Eigenschaftspfads finden Sie unter Binding.Path.

Mehrfacheigenschaft (Indirekteigenschaft-Zielausrichtung)

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

propertyName muss aufgelöst werden, um der Name einer Eigenschaft zu sein, die aktuell DataContextist. Die Pfadeigenschaften propertyName und propertyName2 können beliebige Eigenschaften sein, die in einer Beziehung vorhanden sind, wobei propertyName2 es sich um eine Eigenschaft handelt, die für den Typ vorhanden ist, der den Wert von propertyName.

Einzelne Immobilie, angeschlossen oder anders Type-Qualified

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

Die Klammern geben an, dass diese Eigenschaft in einer PropertyPath mit einer teilweisen Qualifizierung aufgebaut werden sollte. Sie kann einen XML-Namespace verwenden, um den Typ mit einer geeigneten Zuordnung zu finden. Die ownerType Suchtypen, auf die ein XAML-Prozessor über die XmlnsDefinitionAttribute Deklarationen in jeder Assembly zugreifen kann. Die meisten Anwendungen weisen den Standard-XML-Namespace auf, der dem http://schemas.microsoft.com/winfx/2006/xaml/presentation Namespace zugeordnet ist, daher ist normalerweise nur ein Präfix für benutzerdefinierte Typen oder Typen außerhalb dieses Namespaces erforderlich. propertyName muss aufgelöst werden, um der Name einer eigenschaft zu sein, die für das ownerTypeObjekt vorhanden ist. Diese Syntax wird in der Regel für einen der folgenden Fälle verwendet:

Der Pfad wird in XAML angegeben, das sich in einem Stil oder einer Vorlage befindet, die keinen bestimmten Zieltyp hat. Eine qualifizierte Verwendung ist in der Regel für andere Fälle nicht gültig, da die Eigenschaft in nicht Stil- und nicht Vorlagen-Fällen bei einer Instanz vorhanden ist und nicht bei einem Typ.
Die Eigenschaft ist eine angefügte Eigenschaft.
Sie binden an eine statische Eigenschaft.

Für die Verwendung als Storyboard-Ziel muss die als propertyName angegebene Eigenschaft ein DependencyProperty sein.

Quell-Traversal (Bindung an Hierarchien von Sammlungen)

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

Die /in dieser Syntax wird verwendet, um innerhalb eines hierarchischen Datenquellenobjekts zu navigieren, und mehrere Schritte in die Hierarchie mit aufeinander folgenden / Zeichen werden unterstützt. Bei der Quellenverarbeitung wird die aktuelle Position des Datensatzzeigers berücksichtigt, die durch die Synchronisierung der Daten mit der Benutzeroberfläche der Ansicht bestimmt wird. Ausführliche Informationen zur Bindung mit hierarchischen Datenquellenobjekten und zum Konzept des aktuellen Datensatzzeigers in der Datenbindung finden Sie unter Verwenden Sie das Master-Detail-Muster mit hierarchischen Daten oder Datenbindungsübersicht.

Hinweis

Oberflächlich ähnelt diese Syntax XPath. Ein korrekter XPath-Ausdruck für die Bindung an eine XML-Datenquelle wird nicht als Path-Wert verwendet und sollte stattdessen für die ausschließende XPath-Eigenschaft verwendet werden.

Sammlungsansichten

Um auf eine benannte Auflistungsansicht zu verweisen, stellen Sie dem Namen der Sammlungsansicht das Hashzeichen (#) voran.

Aktueller Datensatzzeiger

Um im Kontext einer Sammlungsansicht oder eines Master-Detail-Datenbindungsszenarios auf den aktuellen Datensatzzeiger zu verweisen, beginnen Sie die Pfadzeichenfolge mit einem Schrägstrich (/). Jeder Pfad hinter dem Schrägstrich wird ab dem aktuellen Datensatzzeiger durchlaufen.

Mehrere Indexer

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

oder

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

Wenn ein bestimmtes Objekt mehrere Indexer unterstützt, können diese Indexer in einer bestimmten Reihenfolge angegeben werden, ähnlich wie bei der Syntax von Arrayverweisen. Das fragliche Objekt kann entweder der aktuelle Kontext oder der Wert einer Eigenschaft sein, die ein mehrfaches Indexobjekt enthält.

Standardmäßig werden die Indexerwerte mithilfe der Merkmale des zugrunde liegenden Objekts eingegeben. Sie können bei Bedarf den Indextyp angeben. Ausführliche Informationen zum Eingeben der Indexer finden Sie unter Binding.Path.

Mischen von Syntaxen

Jede der oben gezeigten Syntaxen kann interspersiert werden. Es folgt beispielsweise ein Beispiel, das einen Eigenschaftspfad zu der Farbe bei einem bestimmten x,y einer ColorGrid Eigenschaft erstellt, die ein Pixelrasterarray von SolidColorBrush Objekten enthält:

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

Escapes für Eigenschaftspfadzeichenfolgen

Bei bestimmten Geschäftsobjekten kann es vorkommen, dass für die Eigenschaftspfadzeichenfolge eine Escapesequenz erforderlich ist, um die richtige Analyse zu ermöglichen. Die Escape-Notwendigkeit sollte selten sein, da viele dieser Zeichen ähnliche Namensinteraktionsprobleme in Sprachen aufweisen, die normalerweise zum Definieren des Geschäftsobjekts verwendet werden.

Innerhalb von Indexern ([ ]) maskiert das Caretzeichen (^) das nächste Zeichen.
Sie müssen bestimmte Zeichen, die speziell für die XML-Sprachdefinition sind, mithilfe von XML-Entitäten maskieren. Wird verwendet & , um das Zeichen "&" zu escapen. Verwenden Sie >, um den Endtag ">" zu umgehen.
Sie müssen Escapezeichen (mithilfe eines umgekehrten Schrägstrichs \) verwenden, um Zeichen zu escapen, die im WPF-XAML-Parserverhalten als speziell für die Verarbeitung einer Markuperweiterung gelten.
- Umgekehrter Schrägstrich (\) ist das Escapezeichen selbst.
- Das Gleichheitszeichen (=) trennt den Eigenschaftsnamen vom Eigenschaftswert.
- Komma (,) trennt Eigenschaften.
- Die rechte geschweifte Klammer (}) ist das Ende einer Markuperweiterung.

Hinweis

Technisch funktionieren diese Escapes auch für einen Storyboard-Eigenschaftspfad, aber normalerweise navigieren Sie durch Objektmodelle für vorhandene WPF-Objekte, und das Escapen sollte unnötig sein.

PropertyPath für Animationsziele

Die Zieleigenschaft einer Animation muss eine Abhängigkeitseigenschaft sein, die entweder einen Freezable oder einen Grundtyp verwendet. Die zielorientierte Eigenschaft für einen Typ und die letztendlich animierte Eigenschaft kann jedoch für verschiedene Objekte vorhanden sein. Bei Animationen wird ein Eigenschaftspfad verwendet, um die Verbindung zwischen der Eigenschaft des benannten Animationszielobjekts und der beabsichtigten Zielanimationseigenschaft zu definieren, indem Objekteigenschaftenbeziehungen in den Eigenschaftswerten durchlaufen werden.

Allgemeine Object-Property Überlegungen zu Animationen

Weitere Informationen zu Animationskonzepten im Allgemeinen finden Sie unter Storyboards Overview and Animation Overview.

Der Werttyp oder die animierte Eigenschaft muss entweder ein Freezable Typ oder ein Grundtyp sein. Die Eigenschaft, die den Pfad beginnt, muss auf den Namen einer Abhängigkeitseigenschaft aufgelöst werden, die für den angegebenen TargetName Typ vorhanden ist.

Um das Klonen zu unterstützen, damit ein Freezable animiert werden kann, das bereits fixiert ist, muss das vom TargetName angegebene Objekt eine Klasse sein, die von FrameworkElement oder FrameworkContentElement abgeleitet ist.

Single-Eigenschaft für das Target-Objekt

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

propertyName muss aufgelöst werden, um der Name einer Abhängigkeitseigenschaft zu sein, die für den angegebenen TargetName Typ vorhanden ist.

Indirekte Eigenschaftszielansprache

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

propertyName muss eine Eigenschaft sein, die entweder ein Freezable Werttyp oder ein Grundtyp ist, der für den angegebenen TargetName Typ vorhanden ist.

propertyName2 muss der Name einer Abhängigkeitseigenschaft sein, die auf dem Objekt existiert, das den Wert von propertyName darstellt. Mit anderen Worten, muss als Abhängigkeitseigenschaft für den Typ vorhanden sein, propertyName2 der dies propertyNamePropertyTypeist.

Die indirekte Ausrichtung von Animationen ist aufgrund angewendeter Stile und Vorlagen erforderlich. Um eine Animation als Ziel festzulegen, benötigen Sie ein TargetName Zielobjekt, und dieser Name wird durch x:Name oder Name. Obwohl Vorlagen- und Stilelemente auch Namen haben können, sind diese Namen nur innerhalb des Namensbereichs der Stile und Vorlagen gültig. (Wenn Vorlagen und Stile Namensbereiche mit Anwendungsmarkups teilen würden, könnten Namen nicht einzigartig sein. Die Stile und Vorlagen werden buchstäblich zwischen Instanzen geteilt und würden doppelte Namen enthalten.) Wenn also die einzelnen Eigenschaften eines Elements, das Sie animieren möchten, aus einer Formatvorlage oder Vorlage stammen, müssen Sie mit einer benannten Elementinstanz beginnen, die nicht aus einer Stilvorlage stammt, und dann auf die visuelle Struktur der Formatvorlage oder der Vorlage anvisieren, um zu der Eigenschaft zu gelangen, die Sie animieren möchten.

Beispielsweise ist die Background-Eigenschaft eines Panel eine vollständige Brush (eigentlich eine SolidColorBrush), die aus einer Themenvorlage stammt. Um eine Brush vollständig zu animieren, müsste eine BrushAnimation (wahrscheinlich eine für jeden Brush Typ) vorhanden sein, und es gibt keinen solchen Typ. Zum Animieren eines Pinsels animieren Sie stattdessen Eigenschaften eines bestimmten Brush Typs. Sie müssen von SolidColorBrush zu dessen Color gelangen, um dort ein ColorAnimation anzuwenden. Der Eigenschaftspfad für dieses Beispiel wäre Background.Color.

Angefügte Eigenschaften

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

Die Klammern geben an, dass diese Eigenschaft in einer PropertyPath mit einer teilweisen Qualifizierung aufgebaut werden sollte. Er kann einen XML-Namespace verwenden, um den Typ zu finden. Die ownerType Suchtypen, auf die ein XAML-Prozessor über die XmlnsDefinitionAttribute Deklarationen in jeder Assembly zugreifen kann. Die meisten Anwendungen weisen den Standard-XML-Namespace auf, der dem http://schemas.microsoft.com/winfx/2006/xaml/presentation Namespace zugeordnet ist, daher ist normalerweise nur ein Präfix für benutzerdefinierte Typen oder Typen außerhalb dieses Namespaces erforderlich. propertyName muss aufgelöst werden, um der Name einer eigenschaft zu sein, die für das ownerTypeObjekt vorhanden ist. Die Eigenschaft, die als propertyName angegeben ist, muss eine DependencyProperty sein. (Alle angefügten WPF-Eigenschaften werden als Abhängigkeitseigenschaften implementiert, sodass dieses Problem nur für benutzerdefinierte angefügte Eigenschaften von Bedeutung ist.)

Indexierer

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

Die meisten Abhängigkeitseigenschaften oder Freezable Typen unterstützen keinen Indexer. Daher ist die einzige Verwendung eines Indexers in einem Animationspfad an einer Zwischenposition zwischen der Eigenschaft, die die Kette am benannten Ziel beginnt, und der letztendlich animierten Eigenschaft. In der bereitgestellten Syntax, das heißt propertyName2. Eine Indexerverwendung kann z. B. erforderlich sein, wenn die Zwischeneigenschaft eine Auflistung wie TransformGroup ist, z. B. in einem Eigenschaftspfad wie RenderTransform.Children[1].Angle.

Eigenschaftspfad im Code

Die Codeverwendung für PropertyPath, einschließlich der Erstellung eines PropertyPath, wird im Referenzthema für PropertyPath dokumentiert.

Im Allgemeinen ist PropertyPath so konzipiert, dass zwei unterschiedliche Konstruktoren verwendet werden, einer für die Bindungsanwendungen und die einfachsten Animationsanwendungen und einer für die komplexen Animationsanwendungen. Verwenden Sie die PropertyPath(Object) Signatur für Bindungsverwendungen, wobei das Objekt eine Zeichenfolge ist. Verwenden Sie die Signatur PropertyPath(Object) für Einschritt-Animationspfade, wobei das Objekt ein DependencyProperty ist. Verwenden Sie die PropertyPath(String, Object[]) Signatur für komplexe Animationen. Dieser letztere Konstruktor verwendet eine Tokenzeichenfolge für den ersten Parameter und ein Array von Objekten, die Positionen in der Tokenzeichenfolge ausfüllen, um eine Eigenschaftspfadbeziehung zu definieren.