XAML-Syntax von PropertyPath

Artikel
05/04/2023

Das PropertyPath-Objekt unterstützt eine komplexe XAML-Inlinesyntax zum Festlegen verschiedener Eigenschaften, die den PropertyPath-Typ als Wert annehmen. In diesem Thema wird die PropertyPath-Syntax und deren Anwendung auf die Bindungs- und Animationssyntax dokumentiert.

Verwendung von PropertyPath

PropertyPath ist ein allgemeines Objekt, das in mehreren WPF-Features (Windows Presentation Foundation) verwendet wird. Obwohl das allgemeine PropertyPath-Objekt verwendet wird, um Informationen zum Eigenschaftspfad zu vermitteln, variieren die Verwendungen für jeden Funktionsbereich, in dem PropertyPath als Typ verwendet wird. Daher ist es praktischer, die Syntaxen pro Funktion zu dokumentieren.

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

Einige Stil- und Vorlageneigenschaften wie Setter.Property nehmen einen qualifizierten Eigenschaftennamen an, der oberflächlich betrachtet einem PropertyPath ähnelt. Dies ist jedoch kein echtes PropertyPath-Objekt, sondern eine qualifizierte Verwendung des owner.property-Zeichenfolgenformats, das durch den XAML-Prozessor von WPF in Kombination mit dem Typkonverter für DependencyProperty aktiviert wird.

PropertyPath für Objekte in der Datenbindung

Datenbindung ist eine WPF-Funktion, bei der Sie an den Zielwert einer beliebigen Abhängigkeitseigenschaft binden können. Allerdings muss die Quelle einer solchen Datenbindung keine Abhängigkeitseigenschaft sein. Es kann sich um einen beliebigen Eigenschaftstyp handeln, der vom Anwendungsdatenanbieter erkannt wird. Eigenschaftspfade werden vor allem für das ObjectDataProvider-Objekt verwendet, das zum Abrufen von Bindungsquellen aus CLR-Objekten (Common Language Runtime) und deren Eigenschaften dient.

Beachten Sie, dass Datenbindung an XML nicht PropertyPath verwendet, weil sie nicht Path in Binding verwendet. Stattdessen verwenden Sie XPath und geben gültige XPath-Syntax im XML-Dokumentobjektmodell (DOM) der Daten an. XPath wird auch als Zeichenfolge angegeben, wird aber hier nicht dokumentiert. Weitere Informationen dazu finden Sie unter Binden an XML-Daten mithilfe von XMLDataProvider und XPath-Abfragen.

Für das Verständnis von Eigenschaftspfaden in der Datenbindung ist es wichtig zu wissen, dass Sie einen individuellen Eigenschaftswert als Ziel für die Bindung festlegen oder stattdessen Bindung zu Zieleigenschaften herstellen können, die Listen oder Auflistungen verwenden. Wenn Sie Sammlungen binden, z. B. ein ListBox-Objekt, das je nach Anzahl der Datenelemente in der Sammlungen erweitert wird, sollte der Eigenschaftspfad auf das Sammlungsobjekt und nicht auf einzelne Sammlungselemente verweisen. Die Datenbindungs-Engine ordnet die als Datenquelle verwendete Sammlung automatisch dem Typ des Bindungsziels zu, was zu ähnlichem Verhalten führt wie das Auffüllen von ListBox mit einem Elementarray.

Einzelne Eigenschaft auf dem unmittelbaren Objekt als Datenkontext

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

propertyName muss in den Namen einer Eigenschaft aufgelöst werden, die sich im aktuellen DataContext für eine Path-Syntax befindet. Wenn die Bindung die Quelle aktualisiert, müssen für diese Eigenschaft Schreib- und Leseberechtigungen festgelegt sein, und das Quellobjekt muss geändert werden können.

Einzelner Indexer auf dem unmittelbaren Objekt als Datenkontext

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

key muss der eingegebene Index zu einem Wörterbuch oder einer Hashtabelle oder der ganzzahlige Index eines Arrays sein. Zudem muss der Wert des Schlüssels ein Typ sein, der direkt an die Eigenschaft, auf die er angewendet wird, gebunden werden kann. Eine Hashtabelle mit Zeichenfolgenschlüsseln und Zeichenfolgenwerten kann beispielsweise auf diese Art verwendet werden, um eine Bindung zu Text für ein TextBox-Objekt herzustellen. Wenn der Schlüssel auf eine Auflistung oder einen Unterindex verweist, können Sie mit dieser Syntax eine Bindung zu einer Zielauflistungseigenschaft herstellen. Andernfalls müssen Sie mithilfe einer Syntax wie <Binding Path="[key].propertyName" .../> auf eine bestimmte Eigenschaft verweisen.

Sie können falls erforderlich den Typ des Index angeben. Weitere Einzelheiten zu diesem Aspekt eines indizierten Eigenschaftspfads finden Sie unter Binding.Path.

Mehrere Eigenschaften (indirekte Eigenschaftsziele)

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

propertyName muss in den Namen einer Eigenschaft aufgelöst werden, die der aktuelle DataContext ist. Bei den Pfadeigenschaften propertyName und propertyName2 kann es sich um alle Eigenschaften handeln, die in einer Beziehung vorhanden sind, wobei propertyName2 eine Eigenschaft in dem Typ ist, der dem Wert von propertyName entspricht.

Einzelne angefügte oder anderweitig typqualifizierte Eigenschaft

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

Die Klammern zeigen an, dass diese Eigenschaft in einem PropertyPath-Objekt mit einer partiellen Qualifikation erstellt werden sollte. Es kann ein XML-Namespace verwendet werden, um den Typ mit einer entsprechenden Zuordnung zu suchen. ownerType sucht nach Typen, auf die ein XAML-Prozessor über die XmlnsDefinitionAttribute-Deklarationen in jeder Assembly Zugriff besitzt. In den meisten Anwendungen ist dem http://schemas.microsoft.com/winfx/2006/xaml/presentation-Namespace der XML-Standardnamespace zugeordnet. Ein Präfix ist daher normalerweise nur für benutzerdefinierte Typen oder andere Typen erforderlich, die sich anderweitig außerhalb dieses Namespace befinden. propertyName muss in den Namen einer Eigenschaft aufgelöst werden, die im ownerType-Objekt vorhanden ist. Diese Syntax wird in der Regel für einen der folgenden Fälle verwendet:

Der Pfad wird in XAML angegeben, d. h. in einem Stil oder einer Vorlage, die keinen spezifischen Zieltyp aufweist. Eine qualifizierte Verwendung ist normalerweise in anderen Fällen als diesem nicht zulässig, da in Fällen ohne Stil bzw. Vorlage die Eigenschaft in einer Instanz anstatt in einem Typ enthalten ist.
Die Eigenschaft ist eine angefügte Eigenschaft.
Sie binden an eine statische Eigenschaft.

Für die Verwendung als Storyboardziel muss die als propertyName angegebene Eigenschaft eine DependencyProperty sein.

Quellendurchlauf (Binden an Auflistungshierarchien)

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

Das Zeichen / in dieser Syntax ermöglicht die Navigation in einem hierarchischen Datenquellenobjekt. In der Hierarchie werden mehrere Schritte mit aufeinanderfolgenden Schrägstrichen (/) unterstützt. Der Quellendurchlauf kennzeichnet die Zeigerposition des aktuellen Datensatzes, welche durch die Synchronisation der Daten mit der Benutzeroberfläche der Ansicht ermittelt wird. Weitere Informationen zum Binden mit hierarchischen Datenquellenobjekten und zur Bedeutung des Zeigers für den aktuellen Datensatz in der Datenbindung finden Sie unter Verwenden des Master-Detail-Musters mit hierarchischen Daten und Übersicht über die Datenbindung.

Hinweis

Auf den ersten Blick ähnelt diese Syntax XPath. Ein echter XPath-Ausdruck für die Bindung an eine XML-Datenquelle wird nicht als Path-Wert verwendet und sollte stattdessen für die sich gegenseitig ausschließende XPath-Eigenschaft verwendet werden.

Auflistungsansichten

Stellen Sie dem Namen der Auflistungsansicht das Hashzeichen (#) voran, um auf eine benannte Auflistungsansicht zu verweisen.

Zeiger auf den aktuellen Datensatz

Beginnen Sie die Pfadzeichenfolge mit einem Schrägstrich (/), um für eine Auflistungsansicht oder ein Master-Detail-Datenbindungsszenario auf den Zeiger für den aktuellen Datensatz zu verweisen. Ein beliebiger Pfad nach dem Schrägstrich wird ab dem Zeiger auf den aktuellen Datensatz 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 der richtigen Reihenfolge angegeben werden, ähnlich wie ein Array, das auf Syntax verweist. Bei diesem Objekt kann es sich entweder um den aktuellen Kontext oder um den Wert einer Eigenschaft handeln, die ein Objekt mit mehreren Indizes enthält.

In der Standardeinstellung werden die Indexerwerte durch Verwendung der Eigenschaften des zugrunde liegenden Objekts eingegeben. Sie können falls erforderlich den Typ des Index angeben. Details zur Typisierung der Indexer finden Sie unter Binding.Path.

Kombinieren von Syntaxen

Jede der oben angegebenen Syntaxen kann mit einer anderen Syntax kombiniert werden. Im folgenden Beispiel wird ein Eigenschaftspfad zu der Farbe an einer bestimmten xy-Koordinate einer ColorGrid-Eigenschaft erstellt, die ein Pixelrasterarray von SolidColorBrush-Objekten enthält:

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

Escapezeichen für Eigenschaftspfadzeichenfolgen

Bei bestimmten Geschäftsobjekten kann es vorkommen, dass die Eigenschaftspfadzeichenfolge eine Escapesequenz erfordert, um ordnungsgemäß analysiert werden zu können. Der Bedarf an Escapezeichen sollte gering sein, da viele dieser Zeichen ähnliche Benennungsinteraktionsprobleme in Sprachen aufweisen, die normalerweise verwendet werden würden, um das Geschäftsobjekt zu definieren.

In Indexern ([ ]) dient das Caretzeichen (^) als Escapezeichen für das nächste Zeichen.
Sie müssen bestimmte Zeichen (mit XML-Entitäten), die für die XML-Sprachdefinition von besonderer Bedeutung sind, mit Escapezeichen versehen. Verwenden Sie &, um das Zeichen „&“ mit Escapezeichen zu versehen. Verwenden Sie >, um das Endtag „>“ mit Escapezeichen zu versehen.
Sie müssen Escapezeichen (mit dem umgekehrten Schrägstrich \) zu Zeichen hinzufügen, die für das WPF-XAML-Parserverhalten beim Verarbeiten einer Markuperweiterung von besonderer Bedeutung sind.
- Der umgekehrte Schrägstrich (\) ist das eigentliche Escapezeichen.
- Das Gleichheitszeichen (=) trennt den Eigenschaftsnamen vom Eigenschaftswert.
- Das Komma (,) trennt Eigenschaften.
- Die rechte geschweifte Klammer (}) gibt das Ende einer Markuperweiterung an.

Hinweis

Technisch gesehen funktionieren diese Escapezeichen auch für einen Storyboardeigenschaftspfad, aber da Sie normalerweise Objektmodelle für vorhandene WPF-Objekte durchlaufen, sollten Escapezeichen unnötig sein.

PropertyPath für Animationsziele

Die Zieleigenschaft einer Animation muss eine Abhängigkeitseigenschaft sein, die einen Freezable-Typ oder einen primitiven Typ annimmt. Die Zieleigenschaft für einen Typ und gegebenenfalls die animierte Eigenschaft können sich jedoch auf unterschiedlichen Objekten befinden. Bei Animationen wird ein Eigenschaftspfad verwendet, um die Verbindung zwischen der Eigenschaft des benannten Animationszielobjekts und der Eigenschaft der gewünschten Zielanimation zu definieren. Hierzu werden die Objekteigenschaftsbeziehungen in den Eigenschaftswerten durchlaufen.

Allgemeine Überlegungen zu Objekteigenschaften für Animationen

Weitere Informationen zu Animationskonzepten im Allgemeinen finden Sie unter Übersicht über Storyboards und Übersicht über Animationen.

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

Um das Klonen für die Animation eines bereits nicht mehr reagierenden Freezable-Elements zu unterstützen, muss das durch TargetName angegebene Objekt eine von FrameworkElement oder FrameworkContentElement abgeleitete Klasse sein.

Einzelne Eigenschaft auf dem Zielobjekt

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

propertyName muss in den Namen einer Abhängigkeitseigenschaft aufgelöst werden, die für den angegebenen TargetName-Typ vorhanden ist.

Indirekte Eigenschaftsziele

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

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

propertyName2 muss der Name einer Abhängigkeitseigenschaft sein, die auf dem Objekt vorhanden ist, das dem Wert von propertyName entspricht. Mit anderen Worten: propertyName2 muss als Abhängigkeitseigenschaft für den Typ vorhanden sein, der propertyNamePropertyType ist.

Die indirekte Verwendung von Animationen als Ziel ist aufgrund der angewendeten Stile und Vorlagen erforderlich. Um eine Animation als Ziel zu verwenden, benötigen Sie einen TargetName für das Zielobjekt, und dieser Name wird durch x:Name oder Name festgelegt. Vorlagen- und Stilelemente können zwar ebenfalls Namen haben, aber diese Namen sind nur innerhalb des Namescope des Stils bzw. der Vorlage gültig. (Wenn Vorlagen und Stile den gleichen Namensbereich wie das Anwendungsmarkup verwenden würden, wären die Namen nicht eindeutig. Die Stile und Vorlagen würden dann von verschiedenen Instanzen gleichzeitig verwendet werden und würden doppelte Namen weitergeben.) Wenn die spezifischen Eigenschaften eines zu animierenden Elements aus einem Stil oder einer Vorlage stammen, müssen Sie daher mit einer benannten Elementinstanz beginnen, die nicht aus der Formatvorlage stammt, und dann als Ziel die visuelle Struktur des Stils oder der Vorlage angeben, um zu der Eigenschaft zu gelangen, die Sie animieren möchten.

Beispielsweise ist die Background-Eigenschaft eines Panel-Elements ein vollständiges Brush-Element (eigentlich ein SolidColorBrush-Element), das aus einer Designvorlage stammt. Zur vollständigen Animation von Brush müsste eine BrushAnimation vorhanden sein (wahrscheinlich eine für jeden Brush-Typ), aber ein solcher Typ ist nicht vorhanden. Zur Animation eines Brush-Typs animieren Sie stattdessen die Eigenschaften eines bestimmten Brush-Typs. Sie müssen von SolidColorBrush zu Color gelangen, um dort eine ColorAnimation anzuwenden. Der Eigenschaftspfad für dieses Beispiel wäre Background.Color.

Angefügte Eigenschaften

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

Die Klammern zeigen an, dass diese Eigenschaft in einem PropertyPath-Objekt mit einer partiellen Qualifikation erstellt werden sollte. Es kann ein XML-Namespace verwendet werden, um nach dem Typ zu suchen. ownerType sucht nach Typen, auf die ein XAML-Prozessor über die XmlnsDefinitionAttribute-Deklarationen in jeder Assembly Zugriff besitzt. In den meisten Anwendungen ist dem http://schemas.microsoft.com/winfx/2006/xaml/presentation-Namespace der XML-Standardnamespace zugeordnet. Ein Präfix ist daher normalerweise nur für benutzerdefinierte Typen oder andere Typen erforderlich, die sich anderweitig außerhalb dieses Namespace befinden. propertyName muss in den Namen einer Eigenschaft aufgelöst werden, die im ownerType-Objekt vorhanden ist. Die als propertyName angegebene Eigenschaft muss eine DependencyProperty sein. (Alle in WPF angefügten Eigenschaften werden als Abhängigkeitseigenschaften implementiert, weshalb dies nur bei benutzerdefinierten, angefügten Eigenschaften relevant ist.)

Indexer

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

Die meisten Abhängigkeitseigenschaften oder Freezable-Typen unterstützen keinen Indexer. Indexer können deshalb in einem Animationspfad nur an einer Zwischenposition zwischen der Eigenschaft, mit der die Kette am benannten Ziel beginnt, und gegebenenfalls der animierten Eigenschaft verwendet werden. In der dargestellten Syntax ist dies propertyName2. Ein Indexer kann beispielsweise erforderlich sein, wenn die Zwischeneigenschaft eine Vektorpfad wie TransformGroup in einem Eigenschaftspfad wie RenderTransform.Children[1].Angle ist.

PropertyPath im Code

Die Syntax des Codes für PropertyPath, einschließlich der Erstellung eines PropertyPath, wird im Referenzthema zu PropertyPath dokumentiert.

Im Allgemeinen ist PropertyPath für die Verwendung von zwei verschiedenen Konstruktoren ausgelegt, davon einer für Bindungsverwendungen und einfache Animationen und einer für komplexe Animationen. Verwenden Sie die PropertyPath(Object)-Signatur für Bindungssyntax, bei der das Objekt eine Zeichenfolge ist. Verwenden Sie die PropertyPath(Object)-Signatur für einstufige Animationspfade, bei denen das Objekt eine DependencyProperty ist. Verwenden Sie die PropertyPath(String, Object[])-Signatur für komplexe Animationen. Dieser zweite Konstruktor verwendet eine Tokenzeichenfolge für den ersten Parameter und ein Array von Objekten, die Positionen in der Tokenzeichenfolge füllen, um eine Eigenschaftspfadbeziehung zu definieren.