Sintaxis de PropertyPath de XAMLPropertyPath XAML Syntax

El objeto PropertyPath admite una sintaxis de XAMLXAML en línea compleja para establecer diversas propiedades que toman el tipo de PropertyPath como su valor.The PropertyPath object supports a complex inline XAMLXAML syntax for setting various properties that take the PropertyPath type as their value. En este tema se documenta la sintaxis de PropertyPath tal y como se aplica a las sintaxis de enlace y animación.This topic documents the PropertyPath syntax as applied to binding and animation syntaxes.

Dónde se usa PropertyPathWhere PropertyPath Is Used

PropertyPath es un objeto común que se usa en varias características Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF).PropertyPath is a common object that is used in several Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) features. A pesar de usar la PropertyPath común para transmitir información de la ruta de acceso de la propiedad, los usos de cada área de características donde se usa PropertyPath como un tipo varían.Despite using the common PropertyPath to convey property path information, the usages for each feature area where PropertyPath is used as a type vary. Por lo tanto, es más práctico documentar las sintaxis por característica.Therefore, it is more practical to document the syntaxes on a per-feature basis.

Principalmente, WPFWPF usa PropertyPath para describir las rutas de acceso del modelo de objetos para atravesar las propiedades de un origen de datos de objeto y para describir la ruta de acceso de destino para las animaciones de destino.Primarily, WPFWPF uses PropertyPath to describe object-model paths for traversing the properties of an object data source, and to describe the target path for targeted animations.

Algunas propiedades de estilo y plantilla, como Setter.Property toman un nombre de propiedad completo que se parece superficialmente a un PropertyPath.Some style and template properties such as Setter.Property take a qualified property name that superficially resembles a PropertyPath. Pero esto no es un PropertyPathverdadero; en su lugar, es un propietario calificado. uso del formato de cadena de propiedad que está habilitado por el procesador de XAMLXAML de WPF en combinación con el convertidor de tipos para DependencyProperty.But this is not a true PropertyPath; instead it is a qualified owner.property string format usage that is enabled by the WPF XAMLXAML processor in combination with the type converter for DependencyProperty.

PropertyPath para objetos al enlazar datosPropertyPath for Objects in Data Binding

El enlace de datos es una característica de WPFWPF que permite enlazar con el valor de destino de cualquier propiedad de dependencia.Data binding is a WPFWPF feature whereby you can bind to the target value of any dependency property. Sin embargo, el origen de este tipo de enlace de datos no necesita ser una propiedad de dependencia: puede ser cualquier tipo de propiedad que reconozca el proveedor de datos correspondiente.However, the source of such a data binding need not be a dependency property; it can be any property type that is recognized by the applicable data provider. Las rutas de acceso de propiedad se utilizan especialmente para el ObjectDataProvider, que se usa para obtener los orígenes de enlace de los objetos de Common Language Runtime (CLR) y sus propiedades.Property paths are particularly used for the ObjectDataProvider, which is used for obtaining binding sources from common language runtime (CLR) objects and their properties.

Tenga en cuenta que el enlace de datos a XML no utiliza PropertyPath, porque no utiliza Path en el Binding.Note that data binding to XML does not use PropertyPath, because it does not use Path in the Binding. En su lugar, use XPath y especifique la sintaxis válida de XPath en el Document Object Model XML (DOM) de los datos.Instead, you use XPath and specify valid XPath syntax into the XML Document Object Model (DOM) of the data. XPath también se especifica como una cadena, pero no se documenta aquí; vea enlazar a datos XML mediante XmlDataProvider y consultas XPath.XPath is also specified as a string, but is not documented here; see Bind to XML Data Using an XMLDataProvider and XPath Queries.

Una clave para entender las rutas de acceso de propiedad de enlace de datos es que puede tener como destino el enlace a un valor de propiedad individual o, en su lugar, puede enlazar a propiedades de destino que acepten listas o colecciones.A key to understanding property paths in data binding is that you can target the binding to an individual property value, or you can instead bind to target properties that take lists or collections. Si va a enlazar colecciones, por ejemplo enlace un ListBox que se expandirá en función del número de elementos de datos que haya en la colección, la ruta de acceso de la propiedad debe hacer referencia al objeto de colección, no a elementos individuales de la colección.If you are binding collections, for instance binding a ListBox that will expand depending on how many data items are in the collection, then your property path should reference the collection object, not individual collection items. El motor de enlace de datos hará coincidir automáticamente la colección utilizada como origen de datos con el tipo del destino de enlace, lo que producirá un comportamiento como el rellenado de una ListBox con una matriz de elementos.The data binding engine will match the collection used as the data source to the type of the binding target automatically, resulting in behavior such as populating a ListBox with an items array.

Propiedad única en el objeto inmediato como contexto de datosSingle Property on the Immediate Object as Data Context

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

PropertyName debe resolverse como el nombre de una propiedad que está en el DataContext actual para un uso de Path.propertyName must resolve to be the name of a property that is in the current DataContext for a Path usage. Si el enlace actualiza el origen, esa propiedad debe ser de lectura y escritura, y el objeto de destino debe ser mutable.If your binding updates the source, that property must be read/write and the source object must be mutable.

Indizador único en el objeto inmediato como contexto de datosSingle Indexer on the Immediate Object as Data Context

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

key debe ser el índice con tipo de un diccionario o una tabla hash, o el índice de entero de una matriz.key must be either the typed index to a dictionary or hash table, or the integer index of an array. Además, el valor de la clave debe ser un tipo que se pueda enlazar directamente a la propiedad donde se aplica.Also, the value of the key must be a type that is directly bindable to the property where it is applied. Por ejemplo, una tabla hash que contiene claves de cadena y valores de cadena se puede usar de esta manera para enlazar al texto de un TextBox.For instance, a hash table that contains string keys and string values can be used this way to bind to Text for a TextBox. O bien, si la clave apunta a una colección o un subíndice, puede usar esta sintaxis para enlazar a una propiedad de colección de destino.Or, if the key points to a collection or subindex, you could use this syntax to bind to a target collection property. De lo contrario, deberá hacer referencia a una propiedad específica, mediante una sintaxis como <Binding Path="[key].propertyName" .../>.Otherwise, you need to reference a specific property, through a syntax such as <Binding Path="[key].propertyName" .../>.

Puede especificar el tipo del índice si es necesario.You can specify the type of the index if necessary. Para obtener más información sobre este aspecto de una ruta de acceso de propiedad indizada, vea Binding.Path.For details on this aspect of an indexed property path, see Binding.Path.

Varias propiedades (destino de propiedad indirecto)Multiple Property (Indirect Property Targeting)

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

propertyName debe resolverse para ser el nombre de una propiedad que sea el DataContextactual.propertyName must resolve to be the name of a property that is the current DataContext. Las propiedades de ruta de acceso propertyName y propertyName2 pueden ser cualquier propiedad que exista en una relación, donde propertyName2 es una propiedad que existe en el tipo que es el valor de propertyName.The path properties propertyName and propertyName2 can be any properties that exist in a relationship, where propertyName2 is a property that exists on the type that is the value of propertyName.

Propiedad única, adjunta o calificada por tipoSingle Property, Attached or Otherwise Type-Qualified

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

Los paréntesis indican que esta propiedad de una PropertyPath se debe construir utilizando una calificación parcial.The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. Puede usar un espacio de nombres XML para buscar el tipo con la asignación adecuada.It can use an XML namespace to find the type with an appropriate mapping. El ownerType busca en los tipos a los que un procesador de XAMLXAML tiene acceso, a través de las declaraciones de XmlnsDefinitionAttribute en cada ensamblado.The ownerType searches types that a XAMLXAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. La mayoría de las aplicaciones tienen el espacio de nombres XML predeterminado asignado al espacio de nombres http://schemas.microsoft.com/winfx/2006/xaml/presentation, de modo que, normalmente, solo es necesario para los tipos personalizados o para tipos que queden fuera del espacio de nombres.Most applications have the default XML namespace mapped to the http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. propertyName debe resolverse para ser el nombre de una propiedad que exista en ownerType.propertyName must resolve to be the name of a property existing on the ownerType. Esta sintaxis se usa, normalmente, para uno de los siguientes casos:This syntax is generally used for one of the following cases:

  • Se especifica la ruta de acceso en XAMLXAML que tiene un estilo o plantilla sin un tipo de destino especificado.The path is specified in XAMLXAML that is in a style or template that does not have a specified Target Type. Un uso completo, normalmente, no es válido para otros casos que no sean este, porque en los casos sin estilo o sin plantilla, la propiedad existe en una instancia, no en un tipo.A qualified usage is generally not valid for cases other than this, because in non-style, non-template cases, the property exists on an instance, not a type.

  • La propiedad es una propiedad adjunta.The property is an attached property.

  • Está enlazando a una propiedad estática.You are binding to a static property.

Para usar como destino de guion gráfico, la propiedad especificada como propertyName debe ser un DependencyProperty.For use as storyboard target, the property specified as propertyName must be a DependencyProperty.

Recorrido de origen (enlace a jerarquías de colecciones)Source Traversal (Binding to Hierarchies of Collections)

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

El carácter / de esta sintaxis se usa para navegar dentro de un objeto de origen de datos jerárquicos y se admiten varios pasos en la jerarquía con caracteres / sucesivos.The / in this syntax is used to navigate within a hierarchical data source object, and multiple steps into the hierarchy with successive / characters are supported. El recorrido de origen representa la posición del puntero de registro actual, que se determina mediante la sincronización de los datos con la interfaz de usuario de su vista.The source traversal accounts for the current record pointer position, which is determined by synchronizing the data with the UI of its view. Para obtener más información sobre el enlace con objetos de origen de datos jerárquicos y el concepto de puntero de registro actual en el enlace de datos, consulte Usar el patrón principal-detalle con datos jerárquicos o Información general sobre el enlace de datos.For details on binding with hierarchical data source objects, and the concept of current record pointer in data binding, see Use the Master-Detail Pattern with Hierarchical Data or Data Binding Overview.

Nota

Superficialmente, esta sintaxis es similar a XPath.Superficially, this syntax resembles XPath. Una expresión XPath verdadera para el enlace a un origen de datos XML no se utiliza como valor Path y se debe usar en su lugar para la propiedad XPath mutuamente excluyente.A true XPath expression for binding to an XML data source is not used as a Path value and should instead be used for the mutually exclusive XPath property.

Vistas de colecciónCollection Views

Para hacer referencia a una vista de colección con nombre, use el carácter almohadilla (#) como prefijo del nombre de vista de colección.To reference a named collection view, prefix the collection view name with the hash character (#).

Puntero de registro actualCurrent Record Pointer

Para hacer referencia al puntero de registro actual de un escenario de vista de colección o enlace de datos principal-detalle, inicie la cadena de ruta de acceso con una barra diagonal (/).To reference the current record pointer for a collection view or master detail data binding scenario, start the path string with a forward slash (/). Cualquier ruta de acceso posterior a la barra diagonal se recorre desde el puntero de registro actual.Any path past the forward slash is traversed starting from the current record pointer.

Varios indizadoresMultiple Indexers

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

oor

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

Si un objeto determinado admite varios indizadores, estos pueden especificarse en orden, de un modo similar a una matriz que hace referencia a la sintaxis.If a given object supports multiple indexers, those indexers can be specified in order, similar to an array referencing syntax. El objeto en cuestión puede ser el contexto actual o el valor de una propiedad que contenga un objeto de índice múltiple.The object in question can be either the current context or the value of a property that contains a multiple index object.

De forma predeterminada, se asignan tipos a los valores del indizador con las características del objeto subyacente.By default, the indexer values are typed by using the characteristics of the underlying object. Puede especificar el tipo del índice si es necesario.You can specify the type of the index if necessary. Para obtener más información sobre cómo escribir los indizadores, vea Binding.Path.For details on typing the indexers, see Binding.Path.

Sintaxis mixtasMixing Syntaxes

Se pueden intercalar todas las sintaxis mostradas anteriormente.Each of the syntaxes shown above can be interspersed. Por ejemplo, a continuación se muestra un ejemplo que crea una ruta de acceso de propiedad al color en una x, y determinada de una ColorGrid propiedad que contiene una matriz de cuadrícula de píxeles de objetos SolidColorBrush:For instance, the following is an example that creates a property path to the color at a particular x,y of a ColorGrid property that contains a pixel grid array of SolidColorBrush objects:

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

Secuencias de escape para cadenas de ruta de acceso de propiedadEscapes for Property Path Strings

Para ciertos objetos de negocios, puede encontrar un caso donde la cadena de ruta de acceso de propiedad necesite una secuencia de escape para poder analizarse correctamente.For certain business objects, you might encounter a case where the property path string requires an escape sequence in order to parse correctly. La necesidad de la secuencia de escape no es habitual, ya que muchos de estos caracteres tienen problemas similares de interacción con nombres en lenguajes que, normalmente, se usarían para definir el objeto de negocios.The need to escape should be rare, because many of these characters have similar naming-interaction issues in languages that would typically be used to define the business object.

  • Dentro de los indizadores ([ ]), el carácter de intercalación (^) realiza el escape del carácter siguiente.Inside indexers ([ ]), the caret character (^) escapes the next character.

  • Debe realizar el escape (mediante entidades XML) de determinados caracteres que son especiales para la definición del lenguaje XML.You must escape (using XML entities) certain characters that are special to the XML language definition. Use & para realizar el escape del carácter "&".Use & to escape the character "&". Use > para realizar el escape de la etiqueta final ">".Use > to escape the end tag ">".

  • Debe realizar el escape (con la barra diagonal inversa \) de caracteres que son especiales para el comportamiento del analizador XAML de WPF para procesar una extensión de marcado.You must escape (using backslash \) characters that are special to the WPF XAML parser behavior for processing a markup extension.

    • La barra diagonal inversa (\) es el mismo carácter de escape.Backslash (\) is the escape character itself.

    • El signo igual (=) separa el nombre de propiedad del valor de propiedad.The equal sign (=) separates property name from property value.

    • La coma (,) separa las propiedades.Comma (,) separates properties.

    • La llave de cierre (}) es el final de una extensión de marcado.The right curly brace (}) is the end of a markup extension.

Nota

Técnicamente, estos escapes también funcionan para una ruta de acceso de propiedad de guion gráfico, pero, normalmente, se recorren modelos de objetos para los objetos WPF existentes y las secuencias de escape no deberían ser necesarias.Technically, these escapes work for a storyboard property path also, but you are usually traversing object models for existing WPF objects, and escaping should be unnecessary.

PropertyPath para destinos de animaciónPropertyPath for Animation Targets

La propiedad de destino de una animación debe ser una propiedad de dependencia que toma una Freezable o un tipo primitivo.The target property of an animation must be a dependency property that takes either a Freezable or a primitive type. Sin embargo, la propiedad de destino de un tipo y la propiedad animada final pueden existir en objetos diferentes.However, the targeted property on a type and the eventual animated property can exist on different objects. Para las animaciones, se usa una ruta de acceso de propiedad para definir la conexión entre la propiedad del objeto de destino de animación con nombre y la propiedad de animación de destino prevista, si se recorren las relaciones de propiedad del objeto en los valores de propiedad.For animations, a property path is used to define the connection between the named animation target object's property and the intended target animation property, by traversing object-property relationships in the property values.

Consideraciones de las propiedades de objetos generales para animacionesGeneral Object-Property Considerations for Animations

Para obtener más información sobre los conceptos de animación en general, consulte Información general sobre objetos Storyboard e Información general sobre animaciones.For more information on animation concepts in general, see Storyboards Overview and Animation Overview.

El tipo de valor o la propiedad que se está animando debe ser un tipo Freezable o un primitivo.The value type or the property being animated must be either a Freezable type or a primitive. La propiedad que inicia la ruta de acceso debe resolverse como el nombre de una propiedad de dependencia que existe en el tipo de TargetName especificado.The property that starts the path must resolve to be the name of a dependency property that exists on the specified TargetName type.

Con el fin de admitir la clonación para animar una Freezable que ya está inmovilizada, el objeto especificado por TargetName debe ser una FrameworkElement o FrameworkContentElement clase derivada.In order to support cloning for animating a Freezable that is already frozen, the object specified by TargetName must be a FrameworkElement or FrameworkContentElement derived class.

Propiedad única en el objeto de destinoSingle Property on the Target Object

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

propertyName debe resolverse para ser el nombre de una propiedad de dependencia que exista en el tipo de TargetName especificado.propertyName must resolve to be the name of a dependency property that exists on the specified TargetName type.

Destino de propiedad indirectoIndirect Property Targeting

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

propertyName debe ser una propiedad que sea un tipo de valor de Freezable o un primitivo, que existe en el tipo de TargetName especificado.propertyName must be a property that is either a Freezable value type or a primitive, which exists on the specified TargetName type.

propertyName2 debe ser el nombre de una propiedad de dependencia que exista en el objeto que es el valor de propertyName.propertyName2 must be the name of a dependency property that exists on the object that is the value of propertyName. En otras palabras, propertyName2 debe existir como una propiedad de dependencia en el tipo que es el PropertyTypede propertyName.In other words, propertyName2 must exist as a dependency property on the type that is the propertyName PropertyType.

El destino indirecto de animaciones es necesario debido a los estilos y las plantillas que se aplican.Indirect targeting of animations is necessary because of applied styles and templates. Para dirigirse a una animación, necesita una TargetName en un objeto de destino y ese nombre se establece mediante x:Name o Name.In order to target an animation, you need a TargetName on a target object, and that name is established by x:Name or Name. Aunque los elementos de plantilla y estilo también pueden tener nombres, esos nombres solo son válidos en el ámbito de nombres de la plantilla y el estilo.Although template and style elements also can have names, those names are only valid within the namescope of the style and template. (Si las plantillas y los estilos compartieran ámbitos de nombres con el marcado de la aplicación, los nombres no podrían ser únicos.(If templates and styles did share namescopes with application markup, names couldn't be unique. Los estilos y las plantillas se comparten literalmente entre instancias y perpetuarían nombres duplicados.) Por lo tanto, si las propiedades individuales de un elemento que desea animar provienen de un estilo o una plantilla, debe comenzar con una instancia de elemento con nombre que no sea de una plantilla de estilo y, a continuación, establecer como destino el árbol visual de estilo o plantilla para llegar a la propiedad. desea animar.The styles and templates are literally shared between instances and would perpetuate duplicate names.) Thus, if the individual properties of an element that you might wish to animate came from a style or template, you need to start with a named element instance that is not from a style template, and then target into the style or template visual tree to arrive at the property you wish to animate.

Por ejemplo, la propiedad Background de una Panel es una Brush completa (en realidad una SolidColorBrush) procedente de una plantilla de tema.For instance, the Background property of a Panel is a complete Brush (actually a SolidColorBrush) that came from a theme template. Para animar un Brush completamente, debería haber un BrushAnimation (probablemente uno por cada tipo de Brush) y no existe ese tipo.To animate a Brush completely, there would need to be a BrushAnimation (probably one for every Brush type) and there is no such type. Para animar un pincel, en lugar de animar las propiedades de un tipo de Brush determinado.To animate a Brush, you instead animate properties of a particular Brush type. Debe obtener SolidColorBrush a su Color para aplicar una ColorAnimation.You need to get from SolidColorBrush to its Color to apply a ColorAnimation there. La ruta de acceso de propiedad de este ejemplo sería Background.Color.The property path for this example would be Background.Color.

Propiedades adjuntasAttached Properties

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

Los paréntesis indican que esta propiedad de una PropertyPath se debe construir utilizando una calificación parcial.The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. Puede usar un espacio de nombres XML para buscar el tipo.It can use an XML namespace to find the type. El ownerType busca en los tipos a los que un procesador de XAMLXAML tiene acceso, a través de las declaraciones de XmlnsDefinitionAttribute en cada ensamblado.The ownerType searches types that a XAMLXAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. La mayoría de las aplicaciones tienen el espacio de nombres XML predeterminado asignado al espacio de nombres http://schemas.microsoft.com/winfx/2006/xaml/presentation, de modo que, normalmente, solo es necesario para los tipos personalizados o para tipos que queden fuera del espacio de nombres.Most applications have the default XML namespace mapped to the http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. propertyName debe resolverse para ser el nombre de una propiedad que exista en ownerType.propertyName must resolve to be the name of a property existing on the ownerType. La propiedad especificada como propertyName debe ser un DependencyProperty.The property specified as propertyName must be a DependencyProperty. (Todas las propiedades adjuntas WPFWPF se implementan como propiedades de dependencia, por lo que este problema solo afecta a las propiedades adjuntas personalizadas).(All WPFWPF attached properties are implemented as dependency properties, so this issue is only of concern for custom attached properties.)

IndizadoresIndexers

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

La mayoría de las propiedades de dependencia o los tipos de Freezable no admiten un indexador.Most dependency properties or Freezable types do not support an indexer. Por lo tanto, el único uso de un indizador en una ruta de acceso de animación está en una posición intermedia entre la propiedad que inicia la cadena en el destino con nombre y la propiedad animada final.Therefore, the only usage for an indexer in an animation path is at an intermediate position between the property that starts the chain on the named target and the eventual animated property. En la sintaxis proporcionada, es propertyName2.In the provided syntax, that is propertyName2. Por ejemplo, un uso del indexador podría ser necesario si la propiedad intermedia es una colección como TransformGroup, en una ruta de acceso de propiedad como RenderTransform.Children[1].Angle.For instance, an indexer usage might be necessary if the intermediate property is a collection such as TransformGroup, in a property path such as RenderTransform.Children[1].Angle.

PropertyPath en códigoPropertyPath in Code

El uso de código para PropertyPath, incluido cómo construir un PropertyPath, se documenta en el tema de referencia de PropertyPath.Code usage for PropertyPath, including how to construct a PropertyPath, is documented in the reference topic for PropertyPath.

En general, PropertyPath está diseñado para usar dos constructores diferentes, uno para los usos de enlace y los usos de animación más sencillos, y otro para los usos de animación complejos.In general, PropertyPath is designed to use two different constructors, one for the binding usages and simplest animation usages, and one for the complex animation usages. Utilice la firma PropertyPath(Object) para los usos de enlace, donde el objeto es una cadena.Use the PropertyPath(Object) signature for binding usages, where the object is a string. Utilice la firma PropertyPath(Object) para las rutas de acceso de animación de un paso, donde el objeto es un DependencyProperty.Use the PropertyPath(Object) signature for one-step animation paths, where the object is a DependencyProperty. Use la firma PropertyPath(String, Object[]) para animaciones complejas.Use the PropertyPath(String, Object[]) signature for complex animations. Este último constructor usa una cadena de token para el primer parámetro y una matriz de objetos que rellenan las posiciones en la cadena de token para definir una relación de ruta de acceso de propiedad.This latter constructor uses a token string for the first parameter and an array of objects that fill positions in the token string to define a property path relationship.

Vea tambiénSee also