Sintassi proprietà-percorso

  • Articolo

È possibile usare la classe PropertyPath e la sintassi della stringa per creare un'istanza di un valore PropertyPath in XAML o nel codice. I valori PropertyPath vengono utilizzati dal data binding. Viene usata una sintassi simile per le animazioni con storyboard. Per entrambi gli scenari, un percorso di proprietà descrive un attraversamento di una o più relazioni di proprietà oggetto che alla fine si risolvono in una singola proprietà.

È possibile impostare una stringa di percorso della proprietà direttamente su un attributo in XAML. È possibile usare la stessa sintassi di stringa per costruire un PropertyPath che imposta un Binding nel codice o impostare una destinazione di animazione nel codice usando SetTargetProperty. In Windows Runtime sono presenti due aree di funzionalità distinte che usano un percorso di proprietà: data binding e destinazione dell'animazione. La destinazione dell'animazione non crea valori di sintassi property-path sottostanti nell'implementazione di Windows Runtime, ma mantiene le informazioni come stringa, ma i concetti dell'attraversamento delle proprietà degli oggetti sono molto simili. Il data binding e l'animazione destinati a ognuno valutano un percorso di proprietà in modo leggermente diverso, quindi viene descritta separatamente la sintassi del percorso delle proprietà per ognuna.

Property path per gli oggetti nel data binding

In Windows Runtime è possibile eseguire il binding al valore di destinazione di qualsiasi proprietà di dipendenza. Il valore della proprietà di origine per un data binding non deve essere una proprietà di dipendenza; può essere una proprietà in un oggetto business ,ad esempio una classe scritta in un linguaggio Microsoft .NET o C++. In alternativa, l'oggetto di origine per il valore di associazione può essere un oggetto di dipendenza esistente già definito dall'app. È possibile fare riferimento all'origine tramite un nome di proprietà semplice o un attraversamento delle relazioni tra proprietà oggetto nel grafico oggetti dell'oggetto business.

È possibile eseguire l'associazione a un singolo valore di proprietà oppure è possibile eseguire il binding a una proprietà di destinazione che contiene elenchi o raccolte. Se l'origine è una raccolta o se il percorso specifica una proprietà di raccolta, il motore di associazione dati corrisponde agli elementi della raccolta dell'origine alla destinazione di associazione, determinando un comportamento simile al popolamento di un controllo ListBox con un elenco di elementi di una raccolta di origini dati senza la necessità di prevedere gli elementi specifici di tale raccolta.

Attraversamento di un oggetto grafico

L'elemento della sintassi che indica l'attraversamento di una relazione di proprietà oggetto in un oggetto grafico è il carattere punto (.). Ogni punto in una stringa di percorso della proprietà indica una divisione tra un oggetto (lato sinistro del punto) e una proprietà di tale oggetto (lato destro del punto). La stringa viene valutata da sinistra a destra, che consente l'esecuzione di più relazioni tra proprietà oggetto. Ecco un esempio:

"{Binding Path=Customer.Address.StreetAddress1}"

Ecco come viene valutato questo percorso:

  1. L'oggetto contesto dati (o un oggetto Source specificato dallo stesso Binding) viene cercato una proprietà denominata "Customer".
  2. L'oggetto che rappresenta il valore della proprietà "Customer" cerca una proprietà denominata "Address".
  3. L'oggetto che rappresenta il valore della proprietà "Address" cerca una proprietà denominata "StreetAddress1".

In ognuno di questi passaggi, il valore viene considerato come oggetto . Il tipo del risultato viene controllato solo quando l'associazione viene applicata a una proprietà specifica. Questo esempio ha esito negativo se "Address" era solo un valore stringa che non esponeva quale parte della stringa era l'indirizzo stradale. In genere, l'associazione punta ai valori specifici delle proprietà annidate di un oggetto business con una struttura informativa nota e intenzionale.

Regole per le proprietà in un percorso di proprietà di associazione dati

  • Tutte le proprietà a cui fa riferimento un percorso di proprietà devono essere pubbliche nell'oggetto business di origine.
  • La proprietà finale (la proprietà che è l'ultima proprietà denominata nel percorso) deve essere pubblica e deve essere modificabile. Non è possibile eseguire l'associazione a valori statici.
  • La proprietà finale deve essere di lettura/scrittura se questo percorso viene utilizzato come informazioni sul percorso per un'associazione bidirezionale.

Indicizzatori

Un percorso di proprietà per il data binding può includere riferimenti alle proprietà indicizzate. In questo modo è possibile eseguire l'associazione a elenchi/vettori ordinati o a dizionari/mappe. Usare parentesi quadre "[]" caratteri per indicare una proprietà indicizzata. Il contenuto di queste parentesi quadre può essere un numero intero (per l'elenco ordinato) o una stringa senza virgolette (per i dizionari). È anche possibile eseguire l'associazione a un dizionario in cui la chiave è un numero intero. È possibile utilizzare proprietà indicizzate diverse nello stesso percorso con un punto che separa la proprietà dell'oggetto.

Si consideri, ad esempio, un oggetto business in cui è presente un elenco di "Teams" (elenco ordinato), ognuno dei quali ha un dizionario "Giocatori" in cui ogni giocatore ha come chiave il cognome. Un percorso di proprietà di esempio per un giocatore specifico nella seconda squadra è: "Teams[1]. Giocatori[Smith]". (Si usa 1 per indicare il secondo elemento in "Teams" perché l'elenco è indicizzato a zero).

Nota Il supporto dell'indicizzazione per le origini dati C++ è limitato. Vedere Informazioni approfondite sul data binding.

Proprietà associate

I percorsi delle proprietà possono includere riferimenti alle proprietà associate. Poiché il nome di identificazione di una proprietà associata include già un punto, è necessario racchiudere qualsiasi nome di proprietà associata tra parentesi in modo che il punto non venga considerato come passaggio della proprietà dell'oggetto. Ad esempio, la stringa per specificare che si vuole usare Canvas.ZIndex come percorso di associazione è "(Canvas.ZIndex)". Per ulteriori informazioni sulle proprietà associate vedere Panoramica sulle proprietà associate.

Combinazione della sintassi del percorso delle proprietà

È possibile combinare vari elementi della sintassi del percorso della proprietà in una singola stringa. Ad esempio, è possibile definire un percorso di proprietà che fa riferimento a una proprietà associata indicizzata, se l'origine dati dispone di tale proprietà.

Debug di un percorso della proprietà di associazione

Poiché un percorso di proprietà viene interpretato da un motore di associazione e si basa su informazioni che possono essere presenti solo in fase di esecuzione, è spesso necessario eseguire il debug di un percorso di proprietà per l'associazione senza potersi basare sul supporto convenzionale in fase di progettazione o in fase di compilazione negli strumenti di sviluppo. In molti casi il risultato della fase di esecuzione dell'errore di risoluzione di un percorso di proprietà è un valore vuoto senza errori, perché si tratta del comportamento di fallback in base alla progettazione della risoluzione dell'associazione. Fortunatamente, Microsoft Visual Studio offre una modalità di output di debug in grado di isolare quale parte di un percorso di proprietà che specifica un'origine di associazione non è riuscita a risolvere. Per altre informazioni sull'uso di questa funzionalità dello strumento di sviluppo, vedere la sezione "Debug" di Data binding in modo approfondito.

Property path per destinazioni delle animazioni

Le animazioni si basano sulla destinazione di una proprietà di dipendenza in cui i valori con storyboard vengono applicati quando viene eseguita l'animazione. Per identificare l'oggetto in cui esiste la proprietà da animare, l'animazione è destinata a un elemento in base al nome (attributo x:Name). Spesso è necessario definire un percorso di proprietà che inizia con l'oggetto identificato come Storyboard.TargetName e termina con il valore specifico della proprietà di dipendenza in cui deve essere applicata l'animazione. Il percorso della proprietà viene usato come valore per Storyboard.TargetProperty.

Per altre info su come definire le animazioni in XAML, vedere Animazioni con storyboard.

Destinazione semplice

Se si sta animando una proprietà presente sull'oggetto di destinazione stessa e il tipo della proprietà può avere un'animazione applicata direttamente ad essa (anziché a una sottoproprietà del valore di una proprietà), si può semplicemente denominare la proprietà animata senza ulteriori qualifiche. Ad esempio, se si punta a una sottoclasse Shape come Rectangle, e si sta applicando un Colore animato a Fill il percorso della proprietà può essere "Fill".

Impostazione indiretta delle proprietà come destinazioni

È possibile animare una proprietà che è una sottoproprietà dell'oggetto di destinazione. In altre parole, se è presente una proprietà dell'oggetto di destinazione che è un oggetto stesso e tale oggetto ha proprietà, è necessario definire un percorso di proprietà che spiega come eseguire la relazione tra proprietà oggetto. Ogni volta che si specifica un oggetto in cui si desidera animare una sottoproprietà, racchiudere il nome della proprietà tra parentesi e specificare la proprietà in typename.formato propertyname. Ad esempio, per specificare che si desidera che il valore dell'oggetto della proprietà RenderTransform di un oggetto di destinazione venga specificato "(UIElement.RenderTransform)" come primo passaggio nel percorso della proprietà. Questo non è ancora un percorso completo, perché non esistono animazioni che possono essere applicate direttamente a un valore Transform. Quindi, per questo esempio, si completa il percorso della proprietà in modo che la proprietà finale sia una proprietà di una sottoclasse Transform che può essere animata da un valore Double: "(UIElement.RenderTransform).( CompositeTransform.TranslateX)"

Specifica di un determinato elemento figlio in una raccolta

Per specificare un elemento figlio in una proprietà di raccolta, è possibile usare un indicizzatore numerico. Usare parentesi quadre "[]" caratteri intorno al valore di indice intero. È possibile fare riferimento solo a elenchi ordinati, non a dizionari. Poiché una raccolta non è un valore che può essere animato, un utilizzo dell'indicizzatore non può mai essere la proprietà finale in un percorso di proprietà.

Ad esempio, per specificare che si desidera animare il primo colore di interruzione dei colori in un oggetto LinearGradientBrush applicato alla proprietà Background di un controllo, si tratta del percorso della proprietà: "(Control.Background).( GradientBrush.GradientStops)[0]. (GradientStop.Color)". Si noti che l'indicizzatore non è l'ultimo passaggio del percorso e che l'ultimo passaggio deve fare riferimento alla proprietà GradientStop.Color dell'elemento 0 nell'insieme per applicargli un valore Colore animato.

Animazione di una proprietà associata

Non è uno scenario comune, ma è possibile animare una proprietà associata, purché tale proprietà associata abbia un valore di proprietà corrispondente a un tipo di animazione. Poiché il nome di identificazione di una proprietà associata include già un punto, è necessario racchiudere qualsiasi nome di proprietà associata tra parentesi in modo che il punto non venga considerato come passaggio della proprietà dell'oggetto. Ad esempio, la stringa per specificare che si desidera animare la proprietà associata Grid.Row in un oggetto, utilizzare il percorso della proprietà "(Grid.Row)".

Nota Per questo esempio, il valore di Grid.Row è un tipo di proprietà Int32. quindi non puoi animarla con un'animazione Double. Si definirebbe invece un ObjectAnimationUsingKeyFrames che ha componenti DiscreteObjectKeyFrame, dove ObjectKeyFrame.Value è impostato a un numero intero, ad esempio "0" o "1".

Regole per le proprietà in un percorso della proprietà di destinazione dell'animazione

  • Il punto iniziale presunto del percorso della proprietà è l'oggetto identificato da uno Storyboard.TargetName.
  • Tutti gli oggetti e le proprietà a cui si fa riferimento lungo il percorso della proprietà devono essere pubblici.
  • La proprietà finale (la proprietà che è l'ultima proprietà denominata nel percorso) deve essere pubblica, essere di lettura/scrittura e essere una proprietà di dipendenza.
  • La proprietà end deve avere un tipo di proprietà che può essere animato da una delle classi generali dei tipi di animazione (animazioni Colore, animazioni Double, animazioni Point, ObjectAnimationUsingKeyFrames).

Classe PropertyPath

La classe PropertyPath è il tipo di proprietà sottostante di Binding.Path per lo scenario di associazione.

Nella maggior parte dei casi, è possibile applicare PropertyPath in XAML senza usare codice. In alcuni casi, tuttavia, è possibile definire un oggetto PropertyPath usando il codice e assegnarlo a una proprietà in fase di esecuzione.

PropertyPath ha un costruttore PropertyPath(String) e non ha un costruttore predefinito. La stringa passata a questo costruttore è una stringa definita usando la sintassi del percorso della proprietà come illustrato in precedenza. Questa è anche la stessa stringa usata per assegnare Path come attributo XAML. L'unica API della classe PropertyPath è la proprietà Path, di sola lettura. È possibile utilizzare questa proprietà come stringa di costruzione per un'altra istanza di PropertyPath.