Sintassi proprietà-percorsoProperty-path syntax

Puoi usare la classe PropertyPath e la sintassi della stringa per creare un’istanza di un valore PropertyPath in XAML o in codice.You can use the PropertyPath class and the string syntax to instantiate a PropertyPath value either in XAML or in code. I valori PropertyPath sono usati dal data binding.PropertyPath values are used by data binding. Una sintassi simile è usata per la destinazione delle animazioni con storyboard.A similar syntax is used for targeting storyboarded animations. Per entrambi gli scenari, un percorso di proprietà descrive l'attraversamento di uno o più relazioni oggetto-proprietà che finiscono col risolversi in una singola proprietà.For both scenarios, a property path describes a traversal of one or more object-property relationships that eventually resolve to a single property.

Puoi impostare una stringa del percorso di proprietà direttamente su un attributo in XAML.You can set a property path string directly to an attribute in XAML. È possibile utilizzare la stessa sintassi di stringa per costruire un oggetto PropertyPath che imposta un' associazione nel codice o per impostare una destinazione di animazione nel codice utilizzando SetTargetProperty.You can use the same string syntax to construct a PropertyPath that sets a Binding in code, or to set an animation target in code using SetTargetProperty. In Windows Runtime sono presenti due distinte aree di funzionalità che usano il percorso di proprietà: il data binding e la destinazione animazioni.There are two distinct feature areas in the Windows Runtime that use a property path: data binding, and animation targeting. La destinazione animazioni non crea valori con la sintassi PropertyPath sottostanti nell'implementazione di Windows Runtime, ma memorizza le info come stringa. Tuttavia, i concetti alla base dell'attraversamento oggetto-proprietà sono molto simili.Animation targeting doesn't create underlying Property-path syntax values in the Windows Runtime implementation, it keeps the info as a string, but the concepts of object-property traversal are very similar. Il data binding e la destinazione animazioni valutano in modo leggermente diverso il percorso di proprietà, pertanto forniremo due descrizioni distinte del percorso di proprietà.Data binding and animation targeting each evaluate a property path slightly differently, so we describe property path syntax separately for each.

Percorso di proprietà per gli oggetti nel data bindingProperty path for objects in data binding

In Windows Runtime puoi associare il valore di destinazione di qualsiasi proprietà di dipendenza.In Windows Runtime, you can bind to the target value of any dependency property. Il valore della proprietà di origine per un data binding non deve essere necessariamente una proprietà di dipendenza; può essere una proprietà su un oggetto business (ad esempio, una classe scritta in linguaggio Microsoft .NET o C++).The source property value for a data binding doesn't have to be a dependency property; it can be a property on a business object (for example a class written in a Microsoft .NET language or C++). In alternativa, l'oggetto di origine per il valore di binding può essere un oggetto dipendenza esistente, già definito dall'app.Or, the source object for the binding value can be an existing dependency object already defined by the app. All'origine è possibile fare riferimento tramite un semplice nome di proprietà, o tramite un attraversamento delle relazioni oggetto-proprietà nell'oggetto grafico dell'oggetto business.The source can be referenced either by a simple property name, or by a traversal of the object-property relationships in the object graph of the business object.

Puoi creare un binding a un singolo valore di proprietà oppure a una proprietà di destinazione che include elenchi o raccolte.You can bind to an individual property value, or you can bind to a target property that holds lists or collections. Se l'origine è una raccolta o se il percorso specifica una proprietà di raccolta, il motore di associazione dati associa gli elementi della raccolta dell'origine alla destinazione del binding, ottenendo un comportamento come il popolamento di una ListBox con un elenco di elementi di una raccolta di origini dati senza che sia necessario prevedere gli elementi specifici della raccolta.If your source is a collection, or if the path specifies a collection property, the data-binding engine matches the collection items of the source to the binding target, resulting in behavior such as populating a ListBox with a list of items from a data source collection without needing to anticipate the specific items in that collection.

Attraversamento di un oggetto graficoTraversing an object graph

L’elemento della sintassi che denota l’attraversamento di una relazione oggetto-proprietà in un oggetto grafico è il carattere punto (.).The element of the syntax that denotes the traversal of an object-property relationship in an object graph is the dot (.) character. Ogni punto in una stringa del percorso di proprietà indica una divisione tra un oggetto (a sinistra del punto) e una proprietà di tale oggetto (a destra del punto).Each dot in a property path string indicates a division between an object (left side of the dot) and a property of that object (right side of the dot). La stringa viene interpretata da sinistra a destra e in questo modo è possibile eseguire una a una le molteplici relazioni oggetto-proprietà.The string is evaluated left-to-right, which enables stepping through multiple object-property relationships. Ecco un esempio:Let's look at an example:

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

Ecco come viene valutato questo percorso:Here's how this path is evaluated:

  1. Nell’oggetto del contesto dei dati (o una proprietà Source specificata dallo stesso Binding) viene eseguita la ricerca di una proprietà denominata "Customer".The data context object (or a Source specified by the same Binding) is searched for a property named "Customer".
  2. Nell'oggetto corrispondente al valore della proprietà "Customer" viene eseguita la ricerca di una proprietà denominata "Address".The object that is the value of the "Customer" property is searched for a property named "Address".
  3. Nell'oggetto corrispondente al valore della proprietà "Address" viene eseguita la ricerca di una proprietà denominata "StreetAddress1".The object that is the value of the "Address" property is searched for a property named "StreetAddress1".

A ognuno di questi passaggi, il valore viene trattato come un oggetto.At each of these steps, the value is treated as an object. Il tipo di risultato viene controllato solo quando l'associazione è applicata a una proprietà specifica.The type of the result is checked only when the binding is applied to a specific property. Questo esempio produrrebbe un errore se "Address" fosse un semplice valore di stringa e non esponesse quale parte della stringa corrisponde all'indirizzo.This example would fail if "Address" were just a string value that didn't expose what part of the string was the street address. In genere l'associazione punta ai valori annidati della proprietà specifica di un oggetto business che ha una struttura di informazioni conosciuta e intenzionale.Typically, the binding is pointing to the specific nested property values of a business object that has a known and deliberate information structure.

Regole per le proprietà in un percorso di proprietà per l'associazione datiRules for the properties in a data-binding property path

  • Tutte le proprietà a cui fa riferimento un percorso di proprietà devono essere pubbliche nell'oggetto business di origine.All properties referenced by a property path must be public in the source business object.
  • La proprietà finale (l'ultima proprietà a essere denominata nel percorso) deve essere obbligatoriamente pubblica e variabile (non è possibile eseguire l'associazione a valori statici).The end property (the property that is the last named property in the path) must be public and must be mutable – you can't bind to static values.
  • La proprietà end deve essere di lettura/scrittura se questo percorso viene utilizzato come informazioni sul percorso per un'associazione bidirezionale.The end property must be read/write if this path is used as the Path information for a two-way binding.

IndicizzatoriIndexers

Un percorso di proprietà per l'associazione dati può includere riferimenti a proprietà indicizzate.A property path for data-binding can include references to indexed properties. Ciò consente il binding a elenchi ordinati/vettori o a dizionari/mappe.This enables binding to ordered lists/vectors, or to dictionaries/maps. Usare le parentesi quadre " [ ] " caratteri per indicare una proprietà indicizzata.Use square brackets "[]" characters to indicate an indexed property. Il contenuto di queste parentesi quadre può essere un valore intero (per un elenco ordinato) o una stringa senza virgolette (per i dizionari).The contents of these brackets can be either an integer (for ordered list) or an unquoted string (for dictionaries). Puoi anche eseguire l'associazione a un dizionario, se la chiave è un valore intero.You can also bind to a dictionary where the key is an integer. Puoi usare diverse proprietà indicizzate nello stesso percorso con un punto a separare la relazione oggetto-proprietà.You can use different indexed properties in the same path with a dot separating the object-property.

Prendiamo ad esempio un oggetto business con un elenco di "Squadre" (elenco ordinato), ciascuna delle quali ha un dizionario di "Giocatori", dove la chiave per ogni giocatore è il cognome.For example, consider a business object where there is a list of "Teams" (ordered list), each of which has a dictionary of "Players" where each player is keyed by last name. Un esempio di percorso di proprietà a un lettore specifico nel secondo team è: "Teams [ 1 ] . Giocatori [ Smith ] ".An example property path to a specific player on the second team is: "Teams[1].Players[Smith]". (si usa 1 per indicare il secondo elemento in "Squadre" perché l'elenco è con indice zero).(You use 1 to indicate the second item in "Teams" because the list is zero-indexed.)

Nota    Il supporto dell'indicizzazione per le origini dati C++ è limitato. vedere Data Binding in profondità.Note  Indexing support for C++ data sources is limited; see Data binding in depth.

Proprietà associateAttached properties

I percorsi di proprietà possono includere riferimenti a proprietà associate.Property paths can include references to attached properties. Poiché il nome che identifica una proprietà associata include già un punto, devi aggiungere il nome delle proprietà associate tra parentesi, in modo da evitare che il punto venga interpretato come un passaggio oggetto-proprietà.Because the identifying name of an attached property already includes a dot, you must enclose any attached property name within parentheses so that the dot isn't treated as an object-property step. Ad esempio, la stringa per specificare che desideri usare Canvas.ZIndex come percorso di binding è "(Canvas.ZIndex)".For example, the string to specify that you want to use Canvas.ZIndex as a binding path is "(Canvas.ZIndex)". Per altre informazioni sulle proprietà associate, vedi Panoramica delle proprietà associate.For more info on attached properties see Attached properties overview.

Unione della sintassi del percorso di proprietàCombining property path syntax

Puoi unire vari elementi della sintassi del percorso di proprietà in un'unica stringa.You can combine various elements of property path syntax in a single string. Potresti ad esempio definire un percorso di proprietà che rimandi a una proprietà associata indicizzata, se la tua origine dati avesse tale proprietà.For example, you can define a property path that references an indexed attached property, if your data source had such a property.

Debug di un percorso di proprietà di associazioneDebugging a binding property path

Dal momento che un percorso di proprietà deve essere interpretato da un motore di associazione e si basa su informazioni che potrebbero essere disponibili solo in fase di esecuzione, spesso è necessario eseguire il debug di un percorso di proprietà per un'associazione senza poter contare sull'ordinario supporto in fase di progettazione o in fase di compilazione negli strumenti di sviluppo.Because a property path is interpreted by a binding engine and relies on info that may be present only at run-time, you must often debug a property path for binding without being able to rely on conventional design-time or compile-time support in the development tools. In molti casi, la mancata risoluzione di un percorso di proprietà in fase di esecuzione è il risultato di un valore vuoto senza errori, perché quello è il comportamento di fallback per la risoluzione dell'associazione in fase di progettazione.In many cases the run-time result of failing to resolve a property path is a blank value with no error, because that is the by-design fallback behavior of binding resolution. Fortunatamente Microsoft Visual Studio offre una modalità di output di debug che riesce a isolare la parte non risolta di un percorso di proprietà che rimanda a un'origine di binding.Fortunately, Microsoft Visual Studio provides a debug output mode that can isolate which part of a property path that's specifying a binding source failed to resolve. Per altre info sull’uso di questo strumento di sviluppo, vedi la sezione "Debug" dell’argomento Informazioni approfondite sul data binding.For more info on using this development tool feature, see "Debugging" section of Data binding in depth.

Percorso di proprietà per la destinazione delle animazioniProperty path for animation targeting

Le animazioni hanno come destinazione una proprietà di dipendenza in cui i valori nello storyboard vengono applicati quando l'animazione viene eseguita.Animations rely on targeting a dependency property where storyboarded values are applied when the animation runs. Per identificare l’oggetto nel quale esiste la proprietà da animare, l’animazione definisce come destinazione un elemento in base al nome (attributo x:Name).To identify the object where the property to be animated exists, the animation targets an element by name (x:Name attribute). Spesso è necessario definire un percorso di proprietà che inizia con l’oggetto identificato come Storyboard.TargetName e termina con un particolare valore di proprietà di dipendenza, dove dovrebbe essere applicata l’animazione.It is often necessary to define a property path that starts with the object identified as the Storyboard.TargetName, and ends with the particular dependency property value where the animation should apply. Tale percorso della proprietà viene utilizzato come valore per storyboard. TargetProperty.That property path is used as the value for Storyboard.TargetProperty.

Per altre info sulla definizione di animazioni in XAML, vedi Animazioni con storyboard.For more info on the how to define animations in XAML, see Storyboarded animations.

Destinazione sempliceSimple targeting

Se stai animando una proprietà che esiste nell'oggetto di destinazione stesso e si tratta di un tipo di proprietà a cui è possibile applicare direttamente un'animazione (senza passare indirettamente per una sottoproprietà di un valore della proprietà), allora puoi semplicemente denominare la proprietà da animare senza ulteriori qualificazioni.If you are animating a property that exists on the targeted object itself, and that property's type can have an animation applied directly to it (rather than to a sub-property of a property's value) then you can simply name the property being animated without any further qualification. Se ad esempio si fa riferimento a una sottoclasse di forma , ad esempio un rettangolo, e si applica un colore animato alla proprietà Fill , il percorso della proprietà può essere "Fill".For example, if you are targeting a Shape subclass such as Rectangle, and you are applying an animated Color to the Fill property, your property path can be "Fill".

Destinazione indiretta della proprietàIndirect property targeting

Puoi animare una proprietà che rappresenta una sottoproprietà dell'oggetto di destinazione.You can animate a property that is a sub-property of the target object. In altre parole, se c'è una proprietà dell'oggetto di destinazione che è essa stessa un oggetto e che a sua volta ha delle proprietà, devi necessariamente definire un percorso di proprietà che spieghi tale relazione oggetto-proprietà passaggio dopo passaggio.In other words, if there's a property of the target object that's an object itself, and that object has properties, you must define a property path that explains how to step through that object-property relationship. Ogni volta che specifichi un oggetto in cui vuoi animare una sottoproprietà, devi racchiudere tra parentesi il nome della proprietà e specificarla nel formato typename.propertyname.Whenever you are specifying an object where you want to animate a sub-property, you enclose the property name in parentheses, and you specify the property in typename.propertyname format. Ad esempio, per specificare che si desidera il valore dell'oggetto della proprietà RenderTransform di un oggetto di destinazione, specificare "(UIElement. RenderTransform)" come primo passaggio nel percorso della proprietà.For example, to specify that you want the object value of a target object's RenderTransform property, you specify "(UIElement.RenderTransform)" as the first step in the property path. Il percorso non è ancora completo, poiché non esistono animazioni che possano essere applicate direttamente a un valore Transform.This isn't yet a complete path, because there are no animations that can apply to a Transform value directly. Per questo esempio devi completare quindi il percorso di proprietà in modo tale che la proprietà finale sia la proprietà di una sottoclasse Transform e che possa essere animata da un valore Double: "(UIElement.RenderTransform).(CompositeTransform.TranslateX)"So for this example, you now complete the property path so that the end property is a property of a Transform subclass that can be animated by a Double value: "(UIElement.RenderTransform).(CompositeTransform.TranslateX)"

Inserimento di un particolare elemento figlio in una raccoltaSpecifying a particular child in a collection

Per inserire un elemento figlio in una proprietà raccolta, puoi usare un indicizzatore numerico.To specify a child item in a collection property, you can use a numeric indexer. [ ] Racchiudere il valore di indice Integer utilizzando le parentesi quadre "".Use square brackets "[]" characters around the integer index value. Puoi creare riferimenti solo agli elenchi ordinati, non ai dizionari.You can reference only ordered lists, not dictionaries. Poiché una raccolta non è un valore che possa essere animato, l'indicizzatore non può mai essere usato come proprietà finale di un percorso di proprietà.Because a collection isn't a value that can be animated, an indexer usage can never be the end property in a property path.

Ad esempio, per specificare che si desidera animare il primo colore di interruzione del colore in un oggetto LinearGradientBrush applicato alla proprietà background di un controllo, si tratta del percorso della proprietà: "(Control. background). (GradientBrush. GradientStops) [ 0 ] . ( GradientStop. Color) ".For example, to specify that you want to animate the first color stop color in a LinearGradientBrush that is applied to a control's Background property, this is the property path: "(Control.Background).(GradientBrush.GradientStops)[0].(GradientStop.Color)". Osserva che l’indicizzatore non è l’ultimo passaggio nel percorso e che, in particolare, l’ultimo percorso deve rimandare alla proprietà GradientStop.Color dell’elemento 0 nella raccolta per applicarvi un valore animato Color.Note how the indexer is not the last step in the path, and that the last step particularly must reference the GradientStop.Color property of item 0 in the collection to apply a Color animated value to it.

Animazione di una proprietà associataAnimating an attached property

Sebbene non si tratti di uno scenario comune, è comunque possibile animare una proprietà associata, a patto che tale proprietà abbia un valore proprietà compatibile con un tipo di animazione.It isn't a common scenario, but it is possible to animate an attached property, so long as that attached property has a property value that matches an animation type. Poiché il nome che identifica una proprietà associata include già un punto, devi aggiungere il nome delle proprietà associate tra parentesi, in modo da evitare che il punto venga interpretato come un passaggio oggetto-proprietà.Because the identifying name of an attached property already includes a dot, you must enclose any attached property name within parentheses so that the dot isn't treated as an object-property step. Ad esempio, la stringa per specificare che si desidera aggiungere un'animazione alla proprietà Grid. Row associata su un oggetto, utilizzare il percorso della proprietà "(Grid. Row)".For example, the string to specify that you want to animate the Grid.Row attached property on an object, use the property path "(Grid.Row)".

Nota    Per questo esempio, il valore di Grid. Row è un tipo di proprietà Int32 .Note  For this example, the value of Grid.Row is an Int32 property type. pertanto non può essere animato con un’animazione Double.so you can't animate it with a Double animation. Devi invece definire un oggetto ObjectAnimationUsingKeyFrames che abbia componenti DiscreteObjectKeyFrame, dove la proprietà ObjectKeyFrame.Value è impostata su un valore intero, ad esempio "0" o "1".Instead, you'd define an ObjectAnimationUsingKeyFrames that has DiscreteObjectKeyFrame components, where the ObjectKeyFrame.Value is set to an integer such as "0" or "1".

Regole per le proprietà in un percorso di proprietà di destinazione delle animazioniRules for the properties in an animation targeting property path

  • Il punto di partenza di un percorso di proprietà è l’oggetto identificato da Storyboard.TargetName.The assumed starting point of the property path is the object identified by a Storyboard.TargetName.
  • Tutti gli oggetti e le proprietà a cui si fa riferimento lungo il percorso di proprietà devono essere pubblici.All objects and properties referenced along the property path must be public.
  • La proprietà finale (l'ultima proprietà a essere denominata nel percorso) deve essere pubblica, deve essere accessibile in lettura-scrittura e deve essere una proprietà di dipendenza.The end property (the property that is the last named property in the path) must be public, be read-write, and be a dependency property.
  • Il tipo di proprietà della proprietà finale deve poter essere animato da una delle classi generali dei tipi di animazione (animazioni Color, animazioni Double, animazioni Point , ObjectAnimationUsingKeyFrames).The end property must have a property type that is able to be animated by one of the broad classes of animation types (Color animations, Double animations, Point animations, ObjectAnimationUsingKeyFrames).

La classe PropertyPathThe PropertyPath class

La classe PropertyPath è il tipo di proprietà sottostante di Binding. Path per lo scenario di associazione.The PropertyPath class is the underlying property type of Binding.Path for the binding scenario.

Il più delle volte, puoi applicare una classe PropertyPath in XAML senza usare altro codice.Most of the time, you can apply a PropertyPath in XAML without using any code at all. In alcuni casi, tuttavia, potrebbe essere necessario usare il codice per definire un oggetto PropertyPath e assegnarlo a una proprietà in fase di esecuzione.But in some cases you may want to define a PropertyPath object using code and assign it to a property at run-time.

PropertyPath dispone di un costruttore PropertyPath (String) e non dispone di un costruttore predefinito.PropertyPath has a PropertyPath(String) constructor, and doesn't have a default constructor. La stringa che passi a questo costruttore è una stringa che viene definita usando la sintassi del percorso di proprietà nel modo descritto in precedenza.The string you pass to this constructor is a string that's defined using the property path syntax as we explained earlier. Si tratta anche della stessa stringa usata per assegnare il percorso come attributo XAML.This is also the same string you'd use to assign Path as a XAML attribute. L’unica altra API della classe PropertyPath è la proprietà Path, che è di sola lettura.The only other API of the PropertyPath class is the Path property, which is read-only. Potresti usare questa proprietà come stringa di costruzione per un’altra istanza di PropertyPath.You could use this property as the construction string for another PropertyPath instance.