Sintaxis de property-pathProperty-path syntax

Puede usar la clase PropertyPath y la sintaxis de cadena para crear instancias de un valor PropertyPath en XAML o en código.You can use the PropertyPath class and the string syntax to instantiate a PropertyPath value either in XAML or in code. El enlace de datos usa los valores de PropertyPath.PropertyPath values are used by data binding. Una sintaxis similar se usa para seleccionar el destino de las animaciones de guión gráfico.A similar syntax is used for targeting storyboarded animations. Para los dos escenarios, una ruta de acceso de propiedades describe un cruce seguro de una o más relaciones de propiedades de objeto que finalmente se resuelven en una sola propiedad.For both scenarios, a property path describes a traversal of one or more object-property relationships that eventually resolve to a single property.

Puedes establecer una cadena de ruta de acceso de propiedades directamente en un atributo en XAML.You can set a property path string directly to an attribute in XAML. Es más, puedes usar la misma sintaxis de cadena para construir una clase PropertyPath que establezca una clase Binding en el código, o establecer un destino de animación en el código mediante 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. Existen dos áreas de características distintas en Windows Runtime que usan una ruta de acceso de propiedades: el enlace de datos y el destino de animaciones.There are two distinct feature areas in the Windows Runtime that use a property path: data binding, and animation targeting. La selección del destino de animaciones no crea valores de Property-path syntax subyacentes en la implementación de Windows en tiempo de ejecución, sino que mantiene la información como una cadena, pero los conceptos de cruce seguro de propiedades de objetos son muy similares.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. El enlace de datos y la selección del destino de animaciones evalúan una ruta de acceso de propiedades de un modo ligeramente diferente, de forma que describiremos la sintaxis de la ruta de acceso de propiedad por separado para cada uno.Data binding and animation targeting each evaluate a property path slightly differently, so we describe property path syntax separately for each.

Ruta de acceso de propiedades para objetos en el enlace de datosProperty path for objects in data binding

En Windows en tiempo de ejecución, puedes crear enlaces en el valor de destino de cualquier propiedad de dependencias.In Windows Runtime, you can bind to the target value of any dependency property. El valor de la propiedad de origen de un enlace de datos no tiene por qué ser una propiedad de dependencias; puede ser una propiedad en un objeto empresarial (por ejemplo, una clase escrita en un lenguaje 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++). O, el objeto de origen del valor de enlace puede ser una un objeto de dependencias existente ya definido por la aplicación.Or, the source object for the binding value can be an existing dependency object already defined by the app. Pueden hacer referencia al origen un simple nombre de propiedad o un cruce seguro de las relaciones entre propiedades y objetos del gráfico del objeto empresarial.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.

Puedes crear un enlace con un valor de propiedad individual, o con una propiedad de destino que contenga listas o colecciones.You can bind to an individual property value, or you can bind to a target property that holds lists or collections. Si el origen es una colección, o si la ruta de acceso especifica una propiedad de colección, el motor de enlace de datos hará que los elementos de la colección del origen coincidan con el destino de enlace; esto dará como resultado un comportamiento similar a llenar una clase ListBox con una lista de elementos de una colección de orígenes de datos sin tener que adelantar los elementos específicos de esa colección.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.

Atravesar un gráfico de objetoTraversing an object graph

El elemento de la sintaxis que denota el cruce seguro de una relación entre propiedades y objetos en el gráfico de objetos es el carácter de punto (.).The element of the syntax that denotes the traversal of an object-property relationship in an object graph is the dot (.) character. Cada punto en una cadena de ruta de acceso de propiedades indica una división entre un objeto (lado izquierdo del punto) y una propiedad de ese objeto (lado derecho 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 cadena se evalúa de izquierda a derecha, lo que habilita el paso a través de varias relaciones de propiedades de objetos.The string is evaluated left-to-right, which enables stepping through multiple object-property relationships. Veamos un ejemplo:Let's look at an example:

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

Esta ruta de acceso se evalúa del modo siguiente:Here's how this path is evaluated:

  1. Se busca en el objeto de contexto de datos (o en una propiedad Source especificada por la misma clase Binding) una propiedad denominada "Customer".The data context object (or a Source specified by the same Binding) is searched for a property named "Customer".
  2. Se busca en el objeto que corresponde al valor de la propiedad "Customer" una propiedad denominada "Address".The object that is the value of the "Customer" property is searched for a property named "Address".
  3. Se busca en el objeto que corresponde al valor de la propiedad "Address" una propiedad llamada "StreetAddress1".The object that is the value of the "Address" property is searched for a property named "StreetAddress1".

En cada uno de estos pasos, el valor se trata como un objeto.At each of these steps, the value is treated as an object. El tipo de resultado se comprueba solo cuando se aplica el enlace a una propiedad específica.The type of the result is checked only when the binding is applied to a specific property. Este ejemplo daría un error si "Address" fuera solo un valor de cadena que no indicara qué parte de la cadena corresponde a la dirección.This example would fail if "Address" were just a string value that didn't expose what part of the string was the street address. Por lo general, el enlace apunta a los valores de propiedades anidados específicos de un objeto empresarial que tiene una estructura de información conocida y deliberada.Typically, the binding is pointing to the specific nested property values of a business object that has a known and deliberate information structure.

Reglas de las propiedades en una ruta de acceso de propiedades de enlace de datosRules for the properties in a data-binding property path

  • Todas las propiedades a las que hace referencia una ruta de acceso de propiedades deben ser públicas en el objeto empresarial de origen.All properties referenced by a property path must be public in the source business object.
  • La propiedad final (la propiedad que es la última propiedad con nombre de la ruta de acceso) debe ser pública y mutable; no se puede enlazar con valores estáticos.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 propiedad final debe ser de lectura y escritura si esta ruta de acceso se usa como información de la propiedad Path para un enlace bidireccional.The end property must be read/write if this path is used as the Path information for a two-way binding.

IndizadoresIndexers

Una ruta de acceso de propiedades para el enlace de datos puede incluir referencias a propiedades indexadas.A property path for data-binding can include references to indexed properties. Esto te permite habilitar el enlace a listas y vectores ordenadas, o a diccionarios y mapas.This enables binding to ordered lists/vectors, or to dictionaries/maps. Use corchetes " [ ] " para indicar una propiedad indizada.Use square brackets "[]" characters to indicate an indexed property. El contenido de estos corchetes puede ser un entero (para la lista ordenada) o una cadena sin comillas (para los diccionarios).The contents of these brackets can be either an integer (for ordered list) or an unquoted string (for dictionaries). También puedes enlazar con un diccionario en el que la clave sea un entero.You can also bind to a dictionary where the key is an integer. Puedes usar propiedades indizadas diferentes en la misma ruta de acceso con un punto separando la propiedad del objeto.You can use different indexed properties in the same path with a dot separating the object-property.

Por ejemplo, imagina que tienes un objeto empresarial en el que hay una lista denominada "Teams" (lista ordenada) en la cual, cada equipo consta de un diccionario denominado "Players" donde se puede encontrar a cada integrante según su apellido.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. Una ruta de acceso de propiedad de ejemplo a un reproductor específico en el segundo equipo es: "Teams [ 1 ] . Jugadores [ Smith ] ".An example property path to a specific player on the second team is: "Teams[1].Players[Smith]". (Debes usar 1 para indicar el segundo elemento en "Teams" porque la lista tiene un índice de cero).(You use 1 to indicate the second item in "Teams" because the list is zero-indexed.)

Nota:    La compatibilidad con la indización de los orígenes de datos de C++ es limitada; consulte enlace de datos en profundidad.Note  Indexing support for C++ data sources is limited; see Data binding in depth.

Propiedades adjuntasAttached properties

Las rutas de acceso de propiedades pueden incluir referencias a propiedades adjuntas.Property paths can include references to attached properties. Como el nombre identificador de una propiedad adjunta ya incluye un punto, deberás encerrar el nombre de la propiedad adjunta entre paréntesis para que el punto no se considere un paso de propiedad de objeto.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. Por ejemplo, la cadena dedicada a especificar que quieres usar Canvas.ZIndex como ruta de acceso de enlace es "(Canvas.ZIndex)".For example, the string to specify that you want to use Canvas.ZIndex as a binding path is "(Canvas.ZIndex)". Para obtener más información sobre las propiedades adjuntas, consulta Introducción a las propiedades adjuntas.For more info on attached properties see Attached properties overview.

Combinación de sintaxis de ruta de acceso de propiedadesCombining property path syntax

Puedes combinar varios elementos de la sintaxis de ruta de acceso de propiedades en una sola cadena.You can combine various elements of property path syntax in a single string. Por ejemplo, puedes definir una ruta de acceso de propiedades que haga referencia a una propiedad adjunta indizada si tu origen de datos tuviera dicha propiedad.For example, you can define a property path that references an indexed attached property, if your data source had such a property.

Depuración de una ruta de acceso de propiedades de enlaceDebugging a binding property path

Como la ruta de acceso de la propiedad se interpreta mediante un motor de enlace y depende de la información que pueda estar presente solo en tiempo de ejecución, deberás depurar con frecuencia una ruta de acceso de propiedades del enlace sin poder depender de la compatibilidad convencional de las opciones tiempo de diseño o del tiempo de compilación que encontrarás en las herramientas de desarrollo.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. En muchos casos, el resultado en tiempo de ejecución de error al resolver una ruta de acceso de propiedades es un valor en blanco sin errores, porque ese es el comportamiento de reserva que tiene la resolución de enlaces.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. Afortunadamente, Microsoft Visual Studio proporciona un modo de salida de depuración que puede aislar la parte de una ruta de acceso de propiedades que especifica un origen de enlace que no se pudo resolver.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. Para más información sobre el uso de esta herramientas de desarrollo, consulta la sección "Depuración" del tema Enlace de datos en profundidad.For more info on using this development tool feature, see "Debugging" section of Data binding in depth.

Ruta de acceso de propiedades para selección de destino de animacionesProperty path for animation targeting

Las animaciones dependen de la selección del destino de una propiedad de dependencias en la que los valores de guión gráfico se aplican cuando se ejecuta la animación.Animations rely on targeting a dependency property where storyboarded values are applied when the animation runs. Para identificar el objeto en el que existe la propiedad que se va a animar, la animación selecciona como destino un elemento con el nombre (atributo x:Name).To identify the object where the property to be animated exists, the animation targets an element by name (x:Name attribute). Con frecuencia es necesario definir una ruta de acceso de propiedades que comience con el objeto identificado como Storyboard.TargetName y que termine con el valor de propiedad de dependencias particular en el que debe aplicarse la animación.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. La ruta de acceso de propiedades se usa como valor de la propiedad Storyboard.TargetProperty.That property path is used as the value for Storyboard.TargetProperty.

Para obtener más información sobre cómo definir animaciones en XAML, consulta Animaciones con guion gráfico.For more info on the how to define animations in XAML, see Storyboarded animations.

Selección de destino simpleSimple targeting

Si vas a animar una propiedad que ya existe en el propio objeto de destino y al tipo de esa propiedad se le puede aplicar directamente una animación (en vez de aplicársela a una subpropiedad del valor de una propiedad), entonces podrás asignar un nombre a la propiedad que se va a animar sin una cualificación adicional.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. Por ejemplo, si seleccionas como destino una subclase Shape como Rectangle, y aplicas una estructura Color animada a la propiedad Fill, la ruta de acceso de la propiedad podrá ser "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".

Selección indirecta del destino de propiedadesIndirect property targeting

Puedes animar una propiedad que es una subpropiedad del objeto de destino.You can animate a property that is a sub-property of the target object. Dicho de otro modo, si hay una propiedad del objeto de destino que es un objeto en sí mismo, y ese objeto tiene propiedades, deberás definir una ruta de acceso de propiedades que explique cómo pasar por esa relación de propiedades de objeto.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. Siempre que especifiques el objeto donde deseas animar una subpropiedad, puedes escribir el nombre de la propiedad entre paréntesis y especificar la propiedad en el 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. Por ejemplo, para especificar que quieres ver el valor de objeto de la propiedad RenderTransform de un objeto de destino, primero debes especificar "(UIElement.RenderTransform)" en la ruta de acceso de la propiedad.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. Recuerda que esto no es aún una ruta de acceso completa, ya que no hay animaciones que se puedan aplicar a un valor de la clase Transform directamente.This isn't yet a complete path, because there are no animations that can apply to a Transform value directly. Así pues, en este ejemplo completarás la ruta de acceso de la propiedad de forma que la propiedad final sea una propiedad de una subclase Transform a la cual pueda animar un valor 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)"

Especificar un elemento secundario en particular de una colecciónSpecifying a particular child in a collection

Para especificar un elemento secundario de una propiedad de colección, puedes usar un indexador numérico.To specify a child item in a collection property, you can use a numeric indexer. Use corchetes " [ ] " en torno al valor de índice de entero.Use square brackets "[]" characters around the integer index value. Ten en cuenta que puedes hacer referencia solo a listas ordenadas y no a diccionarios.You can reference only ordered lists, not dictionaries. Como una colección no es un valor que se pueda animar, el uso de un indizador nunca puede ser la propiedad final en una ruta de acceso de propiedades.Because a collection isn't a value that can be animated, an indexer usage can never be the end property in a property path.

Por ejemplo, para especificar que desea animar el primer color de detención de color de un LinearGradientBrush que se aplica a la propiedad de fondo de un control, esta es la ruta de acceso de la propiedad: "(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)". Ten en cuenta que el indexador no es el último paso de la ruta de acceso, sino que el último paso debe hacer referencia, en particular, a la propiedad GradientStop.Color del elemento 0 que se encuentra en la colección, para aplicarle un valor animado 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.

Animar una propiedad adjuntaAnimating an attached property

No suele ser habitual, pero es posible animar una propiedad adjunta siempre que esta tenga un valor que coincida con un tipo de animación.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. Como el nombre identificador de una propiedad adjunta ya incluye un punto, deberás encerrar el nombre de la propiedad adjunta entre paréntesis para que el punto no se considere un paso de propiedad de objeto.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. Por ejemplo, la cadena para especificar que quieres animar la propiedad adjunta Grid.Row en un objeto, usa la ruta de acceso de propiedad "(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:    En este ejemplo, el valor de Grid. Row es un tipo de propiedad Int32 .Note  For this example, the value of Grid.Row is an Int32 property type. Debido a ello, no podrás animarlo con una animación Double.so you can't animate it with a Double animation. En cambio, sí que puedes definir una clase ObjectAnimationUsingKeyFrames que tenga componentes DiscreteObjectKeyFrame en los cuales la propiedad ObjectKeyFrame.Value esté establecida como un entero "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".

Reglas de las propiedades en una ruta de acceso de propiedades de selección de destino de animacionesRules for the properties in an animation targeting property path

  • El punto inicial supuesto de la ruta de acceso de propiedades es el objeto identificado por una propiedad Storyboard.TargetName.The assumed starting point of the property path is the object identified by a Storyboard.TargetName.
  • Todos los objetos y las propiedades a los que se hace referencia en la ruta de acceso de propiedad deben ser públicos.All objects and properties referenced along the property path must be public.
  • La propiedad final (la propiedad que es la última propiedad con nombre de la ruta de acceso) debe ser pública, de escritura y de dependencias.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.
  • La propiedad final debe ser un tipo de propiedad que sea capaz de animarse mediante una de las amplias clases de tipos de animaciones (por ejemplo, de tipo Color, Double, Point, ObjectAnimationUsingKeyFrames, etc.).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).

Clase PropertyPathThe PropertyPath class

La clase PropertyPath es el tipo de propiedad subyacente de Binding.Path del escenario de enlace.The PropertyPath class is the underlying property type of Binding.Path for the binding scenario.

La mayor parte de las veces, puedes aplicar una clase PropertyPath en XAML sin tener usar ningún código en absoluto.Most of the time, you can apply a PropertyPath in XAML without using any code at all. Pero en algunos casos, deberás definir un objeto PropertyPath mediante código y asignarlo a una propiedad en tiempo de ejecución.But in some cases you may want to define a PropertyPath object using code and assign it to a property at run-time.

PropertyPath tiene un constructor PropertyPath(String), pero no tiene un constructor predeterminado.PropertyPath has a PropertyPath(String) constructor, and doesn't have a default constructor. La cadena que pases a ese constructor deberá ser una cadena definida mediante la sintaxis de ruta de acceso de propiedades, tal como ya hemos explicado.The string you pass to this constructor is a string that's defined using the property path syntax as we explained earlier. Además, es también la misma cadena que usarías para asignar Path como atributo XAML.This is also the same string you'd use to assign Path as a XAML attribute. Ten en cuenta que la única API de la clase PropertyPath es la propiedad Path, la cual es de solo lectura.The only other API of the PropertyPath class is the Path property, which is read-only. Puedes usar esta propiedad como la cadena de construcción de otra instancia PropertyPath.You could use this property as the construction string for another PropertyPath instance.