Sintaxis XAML de PropertyPath

2025-05-07

El PropertyPath objeto admite una sintaxis XAML en línea compleja para establecer varias propiedades que toman el PropertyPath tipo como su valor. En este tema se documenta la PropertyPath sintaxis tal como se aplica a las sintaxis de enlace y animación.

Donde se usa PropertyPath

PropertyPath es un objeto común que se usa en varias características de Windows Presentation Foundation (WPF). A pesar de usar la información común PropertyPath para transmitir la ruta de acceso de propiedad, los usos de cada área de características donde PropertyPath se usa como un tipo varían. Por lo tanto, es más práctico documentar las sintaxis por característica.

Principalmente, WPF usa PropertyPath para describir las rutas de acceso del modelo de objetos para recorrer las propiedades de un origen de datos de objeto y describir la ruta de acceso de destino para las animaciones de destino.

Ciertas propiedades de estilo y plantilla, como Setter.Property, toman un nombre de propiedad calificado que se asemeja superficialmente a un PropertyPath. Pero esto no es un verdadero PropertyPath; en su lugar, es un uso calificado del formato de cadena owner.property que habilita el procesador XAML de WPF en combinación con el convertidor de tipos para DependencyProperty.

Ruta de propiedad para objetos en enlace de datos

El enlace de datos es una característica de WPF en la que se puede enlazar al valor de destino de cualquier propiedad de dependencia. Sin embargo, el origen de este enlace de datos no debe ser una propiedad de dependencia; puede ser cualquier tipo de propiedad reconocido por el proveedor de datos aplicable. Las rutas de acceso de propiedad se usan especialmente para el ObjectDataProvider, que se utiliza para obtener orígenes de enlace de objetos de Common Language Runtime (CLR) y sus propiedades.

Tenga en cuenta que el enlace de datos a XML no usa PropertyPath, porque no usa Path en el Binding. En su lugar, se usa XPath y se especifica la sintaxis XPath válida en el modelo de objetos de documento XML (DOM) de los datos. XPath también se especifica como una cadena, pero no se documenta aquí; vea Enlazar a datos XML mediante consultas XMLDataProvider y XPath.

Una clave para comprender las rutas de propiedades en el enlace de datos es que puede orientar el enlace a un valor de propiedad individual o, alternativamente, enlazar a propiedades de destino que admiten listas o colecciones. Si estás enlazando colecciones, por ejemplo, enlazando un ListBox que se expandirá dependiendo de cuántos elementos de datos haya en la colección, entonces la ruta de acceso de tu propiedad debe hacer referencia al objeto de la colección, no a los elementos individuales de la colección. El motor de enlace de datos hará coincidir la colección usada como origen de datos con el tipo del destino de enlace automáticamente, lo que da lugar a un comportamiento como rellenar un elemento ListBox con una array de elementos.

Propiedad única en el objeto Inmediato como contexto de datos

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

propertyName debe resolverse para que sea el nombre de una propiedad que se encuentra en el actual DataContext para un Path uso. Si el enlace actualiza el origen, esa propiedad debe ser de lectura y escritura y el objeto de origen debe ser mutable.

Indexador único en el objeto inmediato como contexto de datos

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

key debe ser el índice tipado de un diccionario o tabla hash, o bien el índice numérico de un array. Además, el valor de la clave debe ser un tipo que se pueda enlazar directamente a la propiedad donde se aplica. Por ejemplo, una tabla hash que contiene claves de cadena y valores de cadena se puede usar de esta manera para enlazar con Text para un TextBox. O, si la clave apunta a una colección o subíndice, puede usar esta sintaxis para enlazar a una propiedad de colección de destino. De lo contrario, debe hacer referencia a una propiedad específica a través de una sintaxis como <Binding Path="[key].propertyName" .../>.

Puede especificar el tipo del índice si es necesario. Para obtener más información sobre este aspecto de una ruta de acceso de propiedad indizada, vea Binding.Path.

Propiedad múltiple (destino de propiedad indirecta)

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

propertyName debe resolverse como el nombre de una propiedad que es la actual DataContext. Las propiedades propertyName de ruta de acceso 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.

Propiedad única, adjunta o de otro modo Type-Qualified

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

Los paréntesis indican que esta propiedad de un PropertyPath objeto debe construirse mediante una calificación parcial. Puede usar un espacio de nombres XML para buscar el tipo con una asignación adecuada. Busca tipos ownerType a los que puede acceder un procesador XAML, a través de las declaraciones XmlnsDefinitionAttribute en cada ensamblaje. La mayoría de las aplicaciones tienen el espacio de nombres XML predeterminado asignado al http://schemas.microsoft.com/winfx/2006/xaml/presentation espacio de nombres, por lo que un prefijo normalmente solo es necesario para tipos personalizados o tipos que no estén fuera de ese espacio de nombres. propertyName debe resolverse para ser el nombre de una propiedad existente en ownerType. Esta sintaxis se usa generalmente para uno de los casos siguientes:

La ruta se especifica en un estilo o plantilla en XAML que no tiene un tipo de destino especificado. Por lo general, un uso calificado no es válido para casos diferentes a este, ya que en condiciones que no son de estilo ni de plantilla, la propiedad existe en una instancia, no en un tipo.
La propiedad es una propiedad adjunta.
Está enlazando a una propiedad estática.

Para su uso como destino de guión gráfico, la propiedad especificada como propertyName debe ser un DependencyProperty.

Recorrido de la fuente (vinculación a jerarquías de colecciones)

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

El símbolo "/" en esta sintaxis se utiliza para navegar dentro de un objeto de fuente de datos jerárquico, y se admiten múltiples pasos en la jerarquía con caracteres sucesivos "/". El recorrido de origen tiene en cuenta la posición actual del puntero de registro, que se determina mediante la sincronización de los datos con la interfaz de usuario de su vista. 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 Uso del patrón de Master-Detail con datos jerárquicos o información general sobre el enlace de datos.

Nota:

Superficialmente, esta sintaxis es similar a XPath. Una expresión XPath verdadera para el enlace a un origen de datos XML no se usa como valor Path y, en su lugar, debe usarse para la propiedad mutuamente excluyente XPath .

Vistas de colección

Para hacer referencia a una vista de colección con nombre, prefijo el nombre de la vista de colección con el carácter hash (#).

Puntero del registro actual

Para referirse al puntero del registro actual en una vista de colección o en un escenario de enlace de datos maestro-detalle, inicie la cadena de ruta de acceso con una barra diagonal (/). Cualquier ruta de acceso posterior a la barra diagonal se recorre a partir del apuntador de registro actual.

Varios indexadores

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

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

Si un objeto determinado admite varios indexadores, esos indexadores se pueden especificar en orden, de forma similar a una sintaxis de referencia de matriz. El objeto en cuestión puede ser el contexto actual o el valor de una propiedad que contiene un objeto de índice múltiple.

De forma predeterminada, los valores del indexador se escriben mediante las características del objeto subyacente. Puede especificar el tipo del índice si es necesario. Para obtener más información sobre cómo escribir los indexadores, vea Binding.Path.

Sintaxis de mezcla

Cada una de las sintaxis mostradas anteriormente se puede intercalar. Por ejemplo, el siguiente es un ejemplo que crea una ruta de propiedad al color en una determinada x,y de una ColorGrid propiedad que contiene una matriz de cuadrícula de píxeles de SolidColorBrush objetos.

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

Escapes para las cadenas de rutas de propiedades

Para ciertos objetos de negocio, puede encontrarse con un caso en el que la cadena de ruta de acceso de la propiedad requiera una secuencia de escape para analizarse correctamente. La necesidad de escapar debe ser poco frecuente, 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 negocio.

Dentro de los indizadores ([ ]), el carácter de intercalación (^) escapa al carácter siguiente.
Debe escapar (mediante entidades XML) determinados caracteres especiales para la definición del lenguaje XML. Use & para escapar el carácter "&". Use > para escapar de la etiqueta final ">".
Debes escapar (usando la barra invertida \) los caracteres especiales que son importantes para el comportamiento del analizador XAML de WPF al procesar una extensión de marcado.
- La barra diagonal inversa (\) es el mismo carácter de escape.
- El signo igual (=) separa el nombre de propiedad del valor de la propiedad.
- Coma (,) separa las propiedades.
- La llave derecha (}) es el final de una extensión de marcado.

Nota:

Técnicamente, estos escapes también funcionan para una ruta de acceso de propiedad de storyboard, pero normalmente se recorren modelos de objetos para objetos WPF existentes y el escape suele ser innecesario.

PropertyPath para destinos de animación

La propiedad de destino de una animación debe ser una propiedad de dependencia que acepte un tipo primitivo o un Freezable. Sin embargo, la propiedad objetivo en un tipo y la propiedad animada final pueden existir en diferentes objetos. En el caso de las animaciones, se utiliza una ruta de acceso de propiedad para definir la conexión entre la propiedad del objeto de animación nombrado y la propiedad de animación deseada, navegando por las relaciones de objeto-propiedad en los valores de propiedad.

Consideraciones generales de Object-Property para animaciones

Para obtener más información sobre los conceptos de animación en general, vea Información general de guiones gráficos e Información general sobre animaciones.

El tipo de valor o la propiedad que se está animando deben ser de tipo Freezable o primitivo. La propiedad que inicia la ruta de acceso debe resolverse como el nombre de una propiedad de dependencia que exista en el tipo especificado TargetName.

Para admitir la clonación para animar un Freezable que ya está inmovilizado, el objeto especificado por TargetName debe ser una clase derivada de FrameworkElement o FrameworkContentElement.

Propiedad única en el objeto de destino

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

propertyName debe resolverse para que sea el nombre de una propiedad de dependencia que exista en el tipo especificado TargetName .

Selección de destino de propiedades indirectas

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

propertyName debe ser una propiedad que sea un tipo de valor o un tipo primitivo, y que exista en el tipo especificado Freezable.

propertyName2 debe ser el nombre de una propiedad de dependencia que existe en el objeto que es el valor de propertyName. En otras palabras, propertyName2 debe existir como una propiedad de dependencia en el tipo que es .propertyNamePropertyType

El destino indirecto de las animaciones es necesario debido a los estilos y plantillas aplicados. Para establecer un destino de animación, necesita un TargetName en un objeto objetivo, y ese nombre se establece mediante x:Name o Name. Aunque los elementos de plantilla y estilo también pueden tener nombres, esos nombres solo son válidos dentro del ámbito de nombres del estilo y la plantilla. (Si las plantillas y estilos compartieran ámbitos de nombres con el marcado de la aplicación, los nombres no podrían ser únicos. Los estilos y plantillas se comparten efectivamente 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 plantilla, debe comenzar con una instancia de elemento nombrada que no provenga de una plantilla de estilo, y luego dirigirse al árbol visual del estilo o plantilla para llegar a la propiedad que desea animar.

Por ejemplo, la Background propiedad de una Panel es un Brush completo (realmente una SolidColorBrush) que procede de una plantilla de tema. Para animar un Brush completamente, se necesitaría una BrushAnimation (probablemente una para cada tipo de Brush) y no existe tal tipo. Para animar un pincel, en vez de eso se animan las propiedades de un tipo particular Brush. Debe llegar de SolidColorBrush a su Color para aplicar allí un ColorAnimation. La ruta de acceso de la propiedad para este ejemplo sería Background.Color.

Propiedades adjuntas

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

Los paréntesis indican que esta propiedad de un PropertyPath objeto debe construirse mediante una calificación parcial. Puede usar un espacio de nombres XML para buscar el tipo. Busca tipos ownerType a los que puede acceder un procesador XAML, a través de las declaraciones XmlnsDefinitionAttribute en cada ensamblaje. La mayoría de las aplicaciones tienen el espacio de nombres XML predeterminado asignado al http://schemas.microsoft.com/winfx/2006/xaml/presentation espacio de nombres, por lo que un prefijo normalmente solo es necesario para tipos personalizados o tipos que no estén fuera de ese espacio de nombres. propertyName debe resolverse para ser el nombre de una propiedad existente en ownerType. La propiedad especificada como propertyName debe ser un DependencyProperty. (Todas las propiedades adjuntas de WPF se implementan como propiedades de dependencia, por lo que este problema solo es importante para las propiedades adjuntas personalizadas).

Indexadores

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

La mayoría de las propiedades o Freezable tipos de dependencia no admiten un indexador. Por lo tanto, el único uso de un indexador en una ruta de acceso de animación está en una posición intermedia entre la propiedad que inicia la cadena en el destino nombrado y la propiedad animada final. En la sintaxis proporcionada, es propertyName2. Por ejemplo, podría ser necesario usar un indexador si la propiedad intermedia es una colección como TransformGroup, en una ruta de propiedad como RenderTransform.Children[1].Angle.

PropertyPath en código

El uso de código para PropertyPath, incluido cómo construir un PropertyPath, se documenta en el tema de referencia de 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. Use la PropertyPath(Object) firma para los usos de enlace, donde el objeto es una cadena. Use la firma PropertyPath(Object) para las trayectorias de animación de un solo paso, donde el objeto es un DependencyProperty. Use la PropertyPath(String, Object[]) firma para animaciones complejas. Este último constructor utiliza una cadena de tokens para el primer parámetro y una matriz de objetos que ocupan posiciones en la cadena de tokens para definir una relación de ruta de propiedad.