Sintassi XAML di PropertyPath

Articolo
10/18/2023

L'oggetto PropertyPath supporta una sintassi XAML inline complessa per impostare varie proprietà che accettano il PropertyPath tipo come valore. In questo argomento viene illustrata la PropertyPath sintassi applicata alle sintassi di associazione e animazione.

Uso di PropertyPath

PropertyPath è un oggetto comune usato in diverse funzionalità di Windows Presentation Foundation (WPF). Nonostante l'uso comune PropertyPath per trasmettere informazioni sul percorso delle proprietà, gli utilizzi per ogni area di funzionalità in cui PropertyPath viene usato come tipo variano. È quindi più pratico documentare le sintassi per ogni funzionalità.

Principalmente, WPF usa PropertyPath per descrivere i percorsi del modello a oggetti per attraversare le proprietà di un'origine dati oggetto e per descrivere il percorso di destinazione per le animazioni di destinazione.

Alcune proprietà di stile e modello, ad Setter.Property esempio accettano un nome di proprietà qualificato che assomiglia superficialmente a un oggetto PropertyPath. Ma questo non è un vero PropertyPath; invece è un utilizzo completo del formato della stringa owner.property abilitato dal processore XAML WPF in combinazione con il convertitore di tipi per DependencyProperty.

PropertyPath per gli oggetti nel data binding

Il data binding è una funzionalità WPF in cui è possibile eseguire il binding al valore di destinazione di qualsiasi proprietà di dipendenza. L'origine di tale data binding non deve però essere necessariamente una proprietà di dipendenza, ma può essere qualsiasi tipo di proprietà riconosciuto dal provider di dati applicabile. I percorsi delle proprietà vengono usati in particolare per , ObjectDataProviderche viene usato per ottenere origini di associazione da oggetti CLR (Common Language Runtime) e le relative proprietà.

Si noti che il data binding a XML non usa PropertyPath, perché non viene utilizzato Path in Binding. Al contrario, si usa XPath e si specifica la sintassi XPath valida nel DOM (Document Object Model) XML dei dati. XPath viene anche specificato come stringa, ma non è documentato qui; vedere Eseguire l'associazione a dati XML tramite query XMLDataProvider e XPath.

Per comprendere i percorsi delle proprietà nel data binding bisogna considerare che è possibile scegliere come destinazione del binding un singolo valore di proprietà oppure è possibile eseguire il binding a proprietà di destinazione che accettano elenchi o raccolte. Se si associano raccolte, ad esempio l'associazione di un oggetto ListBox che si espande a seconda del numero di elementi di dati presenti nella raccolta, il percorso della proprietà deve fare riferimento all'oggetto raccolta, non ai singoli elementi della raccolta. Il motore di associazione dati corrisponderà automaticamente alla raccolta usata come origine dati al tipo della destinazione di associazione, con un comportamento simile al popolamento di un ListBox oggetto con una matrice di elementi.

Singola proprietà sull'oggetto immediato come contesto dati

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

propertyName deve essere risolto in modo che sia il nome di una proprietà che si trova nell'oggetto corrente DataContext per un Path utilizzo. Se il binding aggiorna l'origine, tale proprietà deve essere di lettura/scrittura e l'oggetto di origine deve essere modificabile.

Singolo indicizzatore sull'oggetto immediato come contesto dati

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

key deve essere l'indice tipizzato per un dizionario o una tabella hash oppure l'indice Integer di una matrice. Il valore della chiave deve inoltre essere un tipo direttamente associabile alla proprietà a cui è applicato. Ad esempio, una tabella hash che contiene chiavi stringa e valori stringa può essere usata in questo modo per eseguire l'associazione a Text per un oggetto TextBox. In alternativa, se la chiave punta a una raccolta o a un indice secondario, è possibile usare questa sintassi per il binding a una proprietà della raccolta di destinazione. In caso contrario, è necessario fare riferimento a una proprietà specifica, tramite una sintassi come <Binding Path="[key].propertyName" .../>.

È possibile specificare il tipo dell'indice, se necessario. Per informazioni dettagliate su questo aspetto di un percorso di proprietà indicizzato, vedere Binding.Path.

Più proprietà (impostazione indiretta delle proprietà come destinazioni)

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

propertyName deve essere risolto in modo che sia il nome di una proprietà che è l'oggetto corrente DataContext. Le proprietà del percorso propertyName e propertyName2 possono essere costituite da qualsiasi proprietà presente in una relazione, dove propertyName2 è una proprietà presente nel tipo che corrisponde al valore di propertyName.

Singola proprietà, associata o qualificata in altro modo dal tipo

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

Le parentesi indicano che questa proprietà in un PropertyPath oggetto deve essere costruita usando una qualifica parziale. Può usare uno spazio dei nomi XML per trovare il tipo con un mapping appropriato. I ownerType tipi di ricerca a cui un processore XAML ha accesso, tramite le XmlnsDefinitionAttribute dichiarazioni in ogni assembly. La maggior parte delle applicazioni ha lo spazio dei nomi XML predefinito mappato allo spazio dei nomi http://schemas.microsoft.com/winfx/2006/xaml/presentation, quindi in genere è necessario un prefisso solo per i tipi personalizzati o per i tipi altrimenti esterni allo spazio dei nomi. propertyName deve risolversi nel nome di una proprietà presente in ownerType. Questa sintassi viene in genere usata per uno dei casi seguenti:

Il percorso viene specificato in XAML in uno stile o in un modello che non dispone di un tipo di destinazione specificato. Un utilizzo qualificato non è in genere valido in casi diversi da questo, perché in casi senza uno stile o un modello la proprietà è presente in un'istanza, non in un tipo.
La proprietà è una proprietà associata.
Si sta eseguendo il binding a una proprietà statica.

Per l'uso come destinazione dello storyboard, la proprietà specificata come propertyName deve essere un oggetto DependencyProperty.

Attraversamento dell'origine (binding a gerarchie di raccolte)

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

Il carattere / in questa sintassi viene usato per spostarsi in un oggetto origine dati gerarchico e sono supportati più passaggi nella gerarchia con caratteri / successivi. L'attraversamento dell'origine tiene conto della posizione del puntatore di record corrente, determinata sincronizzando i dati con l'interfaccia utente della relativa visualizzazione. Per informazioni dettagliate sul binding con oggetti origine dati gerarchici e sul concetto di puntatore di record corrente nel data binding, vedere Usare il modello Master-Details con dati gerarchici o Panoramica sul data binding.

Nota

In modo superficiale, questa sintassi è simile a XPath. Un'espressione XPath vera per l'associazione a un'origine dati XML non viene utilizzata come Path valore e deve invece essere utilizzata per la proprietà che si escludono XPath a vicenda.

Visualizzazioni raccolta

Per fare riferimento a una visualizzazione di raccolta denominata, premettere il carattere hash (#) al nome della visualizzazione di raccolta.

Puntatore al record corrente

Per fare riferimento al puntatore al record corrente per una visualizzazione di raccolta o uno scenario di data binding master-dettagli, iniziare la stringa di percorso con una barra (/). Qualsiasi percorso dopo la barra viene attraversato a partire dal puntatore al record corrente.

Indicizzatori multipli

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

oppure

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

Se un determinato oggetto supporta più indicizzatori, è possibile specificare tali indicizzatori in ordine, analogamente a una sintassi che fa riferimento a una matrice. L'oggetto in questione può essere il contesto corrente o il valore di una proprietà contenente un oggetto a più indici.

Per impostazione predefinita, i valori dell'indicizzatore sono tipizzati usando le caratteristiche dell'oggetto sottostante. È possibile specificare il tipo dell'indice, se necessario. Per informazioni dettagliate sulla digitazione degli indicizzatori, vedere Binding.Path.

Sintassi miste

Tutte le sintassi illustrate in precedenza possono essere combinate. Ad esempio, di seguito è riportato un esempio che crea un percorso di proprietà al colore in corrispondenza di una determinata x,y di una ColorGrid proprietà che contiene una matrice di griglia di pixel di SolidColorBrush oggetti:

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

Caratteri di escape per le stringhe di percorso delle proprietà

Per determinati oggetti business è possibile che la stringa di percorso delle proprietà richieda un carattere di escape per poter essere analizzata correttamente. L'esigenza di usare caratteri di escape deve essere rara, perché molti di questi caratteri hanno problemi di interazione-denominazione simili nei linguaggi che in genere vengono usati per definire l'oggetto business.

All'interno degli indicizzatori ([]), l’accento circonflesso (^) funge da escape per il carattere successivo.
È necessario usare caratteri di escape (con entità XML) per alcuni caratteri specifici della definizione del linguaggio XML. Usare & come carattere di escape per "&". Usare > per eseguire l'escape del tag di fine ">".
È necessario usare un carattere di escape (la barra rovesciata \) per i caratteri specifici del comportamento del parser XAML di WPF per l'elaborazione di un'estensione di markup.
- La barra rovesciata (\) è il carattere di escape.
- Il segno di uguale (=) separa il nome della proprietà dal valore della proprietà.
- La virgola (,) separa le proprietà.
- La parentesi graffa chiusa (}) rappresenta la fine di un'estensione di markup.

Nota

Tecnicamente, questi caratteri di escape funzionano anche per un percorso di proprietà dello storyboard, ma in genere si attraversano modelli a oggetti per oggetti WPF esistenti e l'uso di caratteri di escape non è necessario.

PropertyPath per le destinazioni delle animazioni

La proprietà di destinazione di un'animazione deve essere una proprietà di dipendenza che accetta un Freezable tipo primitivo o . La proprietà di destinazione su un tipo e la proprietà animata finale possono tuttavia trovarsi su oggetti diversi. Per le animazioni, un percorso delle proprietà viene usato per definire la connessione tra la proprietà dell'oggetto di destinazione dell'animazione denominata e la proprietà dell'animazione di destinazione prevista, attraversando le relazioni oggetto-proprietà nei valori di proprietà.

Considerazioni generali sulle relazioni oggetto-proprietà per le animazioni

Per altre informazioni sui concetti di animazione in generale, vedere Cenni preliminari sugli storyboard e Cenni preliminari sull'animazione.

Il tipo di valore o la proprietà animata deve essere un Freezable tipo o una primitiva. La proprietà che avvia il percorso deve essere il nome di una proprietà di dipendenza esistente nel tipo specificato TargetName .

Per supportare la clonazione per l'animazione di un oggetto Freezable già bloccato, l'oggetto specificato da TargetName deve essere una FrameworkElement classe derivata o FrameworkContentElement .

Singola proprietà nell'oggetto di destinazione

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

propertyName deve essere risolto in modo che sia il nome di una proprietà di dipendenza esistente nel tipo specificato TargetName .

Impostazione indiretta delle proprietà come destinazioni

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

propertyName deve essere una proprietà che è un Freezable tipo valore o una primitiva, che esiste nel tipo specificato TargetName .

propertyName2 deve essere il nome di una proprietà di dipendenza presente nell'oggetto che costituisce il valore di propertyName. In altre parole, propertyName2 deve esistere come proprietà di dipendenza nel tipo che è .propertyNamePropertyType

L'impostazione indiretta delle animazioni come destinazioni è necessaria a causa degli stili e dei modelli applicati. Per impostare come destinazione un'animazione, è necessario un TargetName oggetto su un oggetto di destinazione e tale nome viene stabilito da x:Name o Name. Sebbene gli elementi di modelli e stili possano avere nomi, tali nomi sono validi solo all'interno dell'ambito dei nomi dello stile e del modello. Se i modelli e gli stili condividono ambiti dei nomi con il markup dell'applicazione, i nomi non possono essere univoci. Gli stili e i modelli sono letteralmente condivisi tra istanze e perpetuano nomi duplicati. Pertanto, se le singole proprietà di un elemento che si desidera animare provengono da uno stile o da un modello, è necessario iniziare con un'istanza di elemento denominata che non proviene da un modello di stile e quindi scegliere come destinazione nella struttura ad albero visuale dello stile o del modello per arrivare alla proprietà che si desidera animare.

Ad esempio, la Background proprietà di un Panel oggetto è un oggetto completo Brush (in realtà un SolidColorBrush) proveniente da un modello di tema. Per animare completamente un Brush oggetto, sarebbe necessario un BrushAnimation (probabilmente uno per ogni Brush tipo) e non esiste un tipo di questo tipo. Per animare un oggetto Brush, devi invece animare le proprietà di un determinato Brush tipo. È necessario passare da SolidColorBrush al suo Color per applicare un lì ColorAnimation . Il percorso della proprietà per questo esempio sarebbe Background.Color.

Proprietà associate

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

Le parentesi indicano che questa proprietà in un PropertyPath oggetto deve essere costruita usando una qualifica parziale. Può usare uno spazio dei nomi XML per trovare il tipo. I ownerType tipi di ricerca a cui un processore XAML ha accesso, tramite le XmlnsDefinitionAttribute dichiarazioni in ogni assembly. La maggior parte delle applicazioni ha lo spazio dei nomi XML predefinito mappato allo spazio dei nomi http://schemas.microsoft.com/winfx/2006/xaml/presentation, quindi in genere è necessario un prefisso solo per i tipi personalizzati o per i tipi altrimenti esterni allo spazio dei nomi. propertyName deve risolversi nel nome di una proprietà presente in ownerType. La proprietà specificata come propertyName deve essere un oggetto DependencyProperty. Tutte le proprietà associate WPF vengono implementate come proprietà di dipendenza, pertanto questo problema riguarda solo le proprietà associate personalizzate.

Indicizzatori

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

La maggior parte delle proprietà o Freezable dei tipi di dipendenza non supporta un indicizzatore. L'unico utilizzo di un indicizzatore in un percorso di animazione è quindi in una posizione intermedia tra la proprietà che inizia la catena nella destinazione denominata e la proprietà animata finale. Nella sintassi fornita si tratta di propertyName2. Ad esempio, un utilizzo dell'indicizzatore potrebbe essere necessario se la proprietà intermedia è una raccolta, TransformGroupad esempio , in un percorso di proprietà, RenderTransform.Children[1].Anglead esempio .

PropertyPath nel codice

L'utilizzo del codice per PropertyPath, incluso come costruire un PropertyPathoggetto , è documentato nell'argomento di riferimento per PropertyPath.

In generale, PropertyPath è progettato per usare due costruttori diversi, uno per gli utilizzi di binding e gli utilizzi di animazione più semplici e uno per gli utilizzi di animazione complessi. Usare la PropertyPath(Object) firma per l'utilizzo dell'associazione, in cui l'oggetto è una stringa. Usare la firma per i PropertyPath(Object) percorsi di animazione in un unico passaggio, dove l'oggetto è un DependencyPropertyoggetto . Usa la PropertyPath(String, Object[]) firma per animazioni complesse. Quest'ultimo costruttore usa una stringa token per il primo parametro e una matrice di oggetti che riempiono le posizioni nella stringa token per definire una relazione di percorso di proprietà.