Condividi tramite

Sintassi XAML di PropertyPath

  • Articolo

Aggiornamento: novembre 2007

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

Nel presente argomento sono contenute le seguenti sezioni.

  • Utilizzo di PropertyPath
  • PropertyPath per oggetti in associazione dati
  • PropertyPath per le destinazioni di animazione
  • PropertyPath nel codice
  • Argomenti correlati

Utilizzo di PropertyPath

PropertyPath è un oggetto comune utilizzato in diverse funzionalità Windows Presentation Foundation (WPF). Nonostante l'utilizzo dell'oggetto PropertyPath comune per comunicare informazioni sul percorso della proprietà, l'impiego di ciascun'area di funzionalità in cui è utilizzato PropertyPath come tipo variano. È pertanto più pratico documentare le sintassi per ogni funzionalità.

Principalmente, WPF utilizza PropertyPath per descrivere i percorsi di modelli 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 quali Setter.Property accettano un nome di proprietà qualificato in apparenza analogo a PropertyPath. Non si tratta tuttavia di un vero oggetto PropertyPath, bensì dell'utilizzo di un formato stringa proprietario.proprietà qualificato, attivato dal processore XAML in combinazione con il convertitore di tipi per DependencyProperty.

PropertyPath per oggetti in associazione dati

L'associazione dati è una funzionalità di WPF che consente di associare al valore di destinazione qualsiasi proprietà di dipendenza. Tuttavia, l'origine di tale associazione dati non deve essere necessariamente una proprietà di dipendenza, ma può essere qualsiasi tipo di proprietà riconosciuto dal provider di dati applicabile. I percorsi delle proprietà sono particolarmente utilizzati per ObjectDataProvider, utilizzato per ottenere origini di associazione da oggetti Common Language Runtime (CLR) e dalle relative proprietà.

Si noti che l'associazione dati a XML non utilizza PropertyPath, poiché non utilizza Path in Binding. Viceversa, si utilizza XPath e si specifica una sintassi XPath valida nel modello di oggetti documento XML DOM (Document Object Model) dei dati. Anche XPath viene specificato come stringa, ma non è illustrato qui; vedere Procedura: eseguire l'associazione a dati XML tramite un oggetto XMLDataProvider e query XPath.

Una chiave per comprendere i percorsi delle proprietà nell'associazione dati consiste nel distinguere se è possibile ottenere l'associazione a un singolo valore di proprietà o, viceversa, se è possibile l'associazione a proprietà di destinazione che utilizzano elenchi o insiemi. Se si associano insiemi, il percorso della proprietà deve fare riferimento a un insieme, non a singoli elementi dell'insieme. Il motore di associazione dati determinerà automaticamente la corrispondenza degli insiemi di origine con la destinazione, con conseguente compilazione di un oggetto ListBox con una matrice di elementi.

Proprietà singola sull'oggetto immediato come contesto dei dati

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

nomeProprietà deve essere risolto nel nome di una proprietà contenuto nell'oggetto DataContext corrente per un utilizzo di Path. Se l'associazione aggiorna l'origine, tale proprietà deve essere di lettura/scrittura e l'oggetto di origine deve essere modificabile.

Indicizzatore singolo sull'oggetto immediato come contesto dei dati

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

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

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

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

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

propertyName deve essere risolto nel nome di una proprietà corrispondente all'oggetto DataContext corrente. Le proprietà di percorso propertyName e propertyName2 possono essere costituite da qualsiasi proprietà presente in una relazione, dove propertyName2 è una proprietà esistente sul tipo che corrisponde al valore di propertyName.

Proprietà singola, esterna all'ambito dei nomi di caricamento XAML, riflessione di runtime

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

Questa sintassi è esclusivamente destinata al percorso di origine per un'associazione dati a una proprietà CLR e può essere costituita solo da un percorso a passaggio singolo nelle proprietà. propertyName deve essere risolto nel nome di una proprietà esistente in ownerType, parametro che deve essere di un tipo individuabile in base alla riflessione di runtime. Pertanto, non è consentito qualificare ownerType con uno spazio dei nomi XML, poiché tale prefisso non ha significato per la riflessione, ma solo per XAML in fase di esecuzione. Vedere la sezione seguente.

Proprietà singola, associata o in attesa di contesto tramite stile o modello

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

Le parentesi indicano che questa proprietà in un oggetto PropertyPath deve essere costruita utilizzando una qualifica parziale. È possibile utilizzare uno spazio dei nomi XML per trovare il tipo. ownerType consente di cercare i tipi a cui un processore XAML ha accesso, tramite le dichiarazioni XmlnsDefinitionAttribute in ogni assembly. Nella maggior parte delle applicazioni, lo spazio dei nomi XML predefinito è mappato allo spazio dei nomi https://schemas.microsoft.com/winfx/2006/xaml/presentation, pertanto un prefisso è in genere necessario solo per i tipi personalizzati o per i tipi che altrimenti sarebbero esterni allo spazio dei nomi. propertyName deve essere risolto nel nome di una proprietà esistente in ownerType. Questa sintassi viene in genere utilizzata per uno dei casi seguenti:

  • Il percorso viene specificato in XAML, ovvero in uno stile o modello che non ha un tipo di destinazione specificato. Un utilizzo qualificato non è generalmente valido in casi diversi da questo, poiché in casi non relativi a uno stile o a un modello, la proprietà esiste in un'istanza, non in un tipo.

  • La proprietà è una proprietà associata.

  • Viene eseguita l'associazione a una proprietà statica. In questo caso, ownerType è realmente un tipo.

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

Attraversamento di origine (associazione a gerarchie di insiemi)

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

Il carattere / in questa sintassi viene utilizzato per spostarsi in un oggetto di origine dati gerarchico; sono supportati più passaggi nella gerarchia con successivi caratteri /. L'attraversamento di origine tiene conto della posizione del puntatore a record corrente, determinata dalla sincronizzazione dei dati con l'interfaccia utente della relativa visualizzazione. Per informazioni dettagliate sull'associazione a oggetti di origine dati gerarchici e per informazioni sul concetto di puntatore a record corrente nell'associazione dati, vedere Procedura: utilizzare il modello Master-Details con dati gerarchici o Cenni preliminari sull'associazione dati.

Nota

Questa sintassi è apparentemente analoga a XPath. Un'espressione XPath effettiva per l'associazione a un'origine dati XML non viene utilizzata come valore di Path e deve viceversa essere utilizzata per la proprietà XPath reciprocamente esclusiva.

Più indicizzatori

<object Path="[index1,index2...]" .../>
or
<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 utilizzando le caratteristiche dell'oggetto sottostante. È possibile specificare il tipo dell'indice, se necessario. Per informazioni dettagliate sugli indicizzatori, vedere Binding.Path.

Sintassi miste

Tutte le sintassi illustrate in precedenza possono essere combinate. Di seguito è riportato un esempio in cui viene creato un percorso di proprietà al colore in corrispondenza di un determinato punto x,y di una proprietà ColorGrid contenente una matrice griglia in pixel di oggetti SolidColorBrush:

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

PropertyPath per le destinazioni di animazione

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

Considerazioni generali su oggetto-proprietà per le animazioni

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

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

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

Proprietà singola sull'oggetto di destinazione

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

propertyName deve essere risolto nel nome di una proprietà di dipendenza esistente sul tipo TargetName specificato.

Impostazione indiretta delle destinazioni delle proprietà

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

propertyName deve essere una proprietà costituita da un tipo di valore Freezable o primitivo, esistente sul tipo TargetName specificato.

propertyName2 deve essere il nome di una proprietà di dipendenza esistente sull'oggetto che costituisce il valore di propertyName. In altre parole, propertyName2 deve esistente come proprietà di dipendenza sul tipo che costituisce propertyName PropertyType.

L'impostazione indiretta delle destinazioni delle animazioni è necessaria a causa degli stili e dei modelli applicati. Per impostare la destinazione di un'animazione, è necessario TargetName su un oggetto di destinazione e tale nome è stabilito da x:Name o Name. Sebbene gli elementi di modello e stile possano avere nomi, tali nomi sono validi solo all'interno dell'ambito dei nomi dello stile e del modello. Se modelli e stili non condividono gli ambiti dei nomi con il markup dell'applicazione, i nomi non possono essere univoci. Stili e modelli sono condivisi letteralmente tra le istanze e trasmetterebbero 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 denominato non proveniente da un modello di stile, quindi impostare la destinazione nella struttura ad albero visuale dello stile o del modello affinché arrivi alla proprietà che si desidera animare.

Ad esempio, la proprietà Background di un oggetto Panel è un oggetto Brush completo (ovvero un oggetto SolidColorBrush) proveniente da un modello di tema. Per animare completamente un oggetto Brush, sarebbe necessario BrushAnimation (probabilmente uno per ogni tipo Brush) e tale tipo non è presente. Per animare un pennello, vengono invece animate le proprietà di un determinato tipo Brush. È necessario ottenere da SolidColorBrush al relativo oggetto Color per applicarvi un oggetto 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 oggetto PropertyPath deve essere costruita utilizzando una qualifica parziale. È possibile utilizzare uno spazio dei nomi XML per trovare il tipo. ownerType consente di cercare i tipi a cui un processore XAML ha accesso, tramite le dichiarazioni XmlnsDefinitionAttribute in ogni assembly. Nella maggior parte delle applicazioni, lo spazio dei nomi XML predefinito è mappato allo spazio dei nomi https://schemas.microsoft.com/winfx/2006/xaml/presentation, pertanto un prefisso è in genere necessario solo per i tipi personalizzati o per i tipi che altrimenti sarebbero esterni allo spazio dei nomi. propertyName deve essere risolto nel nome di una proprietà esistente in ownerType. La proprietà specificata come propertyName deve essere DependencyProperty. Tutte le proprietà associate WPF sono 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à di dipendenza o i tipi Freezable non supportano un indicizzatore. Pertanto, l'unico utilizzo di un indicizzatore in un percorso di animazione è una posizione intermedia tra la proprietà che avvia la catena sulla destinazione denominata e la proprietà animata finale. Nella sintassi fornita, si tratta di propertyName2. Ad esempio, l'utilizzo di un indicizzatore può essere necessario se la proprietà intermedia è un insieme quale TransformGroup, in un percorso di proprietà quale RenderTransform.Children[1].Angle.

PropertyPath nel codice

L'utilizzo del codice per PropertyPath, inclusa la modalità di costruzione di PropertyPath, è illustrato nell'argomento di riferimento relativo a PropertyPath.

In genere, PropertyPath è progettato per utilizzare due costruttori diversi, uno per gli utilizzi di associazione e di animazione più semplici e uno per gli utilizzi di animazione complessi. Utilizzare la firma PropertyPath(Object) per gli utilizzi di associazione, dove l'oggetto è una stringa. Utilizzare la firma PropertyPath(Object) per percorsi di animazione a un solo passaggio, dove l'oggetto è DependencyProperty. Utilizzare la firma PropertyPath(String, array<Object[]) per le animazioni complesse. Quest'ultimo costruttore utilizza 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à.

Vedere anche

Concetti

Cenni preliminari sull'associazione dati

Cenni preliminari sugli storyboard

Riferimenti

PropertyPath