Sintaxis de PropertyPath de XAML

El objeto PropertyPath admite una sintaxis alineada compleja para establecer varias propiedades que usan el tipo PropertyPath como su valor. En este tema se documenta la sintaxis PropertyPath, que se aplica a las sintaxis de enlace y animación.

Dónde se usa PropertyPath

PropertyPathes un objeto común que se usa en varias características de Windows Presentation Foundation (WPF). A pesar de usar el objeto común PropertyPath para transmitir información de la ruta de acceso de la propiedad, los usos varían para cada área de características donde se usa PropertyPath como tipo. 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 para describir la ruta de acceso de destino para animaciones concretas.

Algunas propiedades de estilo y plantilla como Setter.Property usan un nombre de propiedad cualificado que se parezca ligeramente a PropertyPath. Pero esto no es un objeto PropertyPath auténtico. En su lugar, es un uso de formato de cadena owner.property completo que habilita el procesador XAML de WPF en combinación con el convertidor de tipos para DependencyProperty.

PropertyPath para objetos al enlazar datos

El enlace de datos es una característica de WPF que permite enlazar con el valor de destino de cualquier propiedad de dependencia. 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. Las rutas de acceso de propiedades se usan especialmente para ObjectDataProvider, que se usa para obtener los 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 Binding. En su lugar, se usa XPath y se especifica la sintaxis XPath válida en el Document Object Model (DOM) XML de los datos. XPath también se especifica como cadena, pero no se documenta aquí: consulte Enlazar a datos XML mediante XMLDataProvider y consultas XPath.

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. Si enlaza colecciones, por ejemplo, un objeto ListBox que se expandirá en función de cuántos elementos de datos están en la colección, la ruta de acceso de propiedades debe hacer referencia al objeto de colección, no a los elementos de colección individuales. El motor de enlace de datos hará coincidir automáticamente la colección que se usa como origen de datos con el tipo del destino del enlace, lo que causa un comportamiento como rellenar un objeto ListBox con una matriz de elementos.

Propiedad única en el objeto inmediato como contexto de datos

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

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

Indizador único en el objeto inmediato como contexto de datos

<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. 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 este modo para enlazar a texto para un objeto 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. De lo contrario, deberá hacer referencia a una propiedad específica, mediante una sintaxis como <Binding Path="[key].propertyName" .../>.

Puede especificar el tipo del índice si es necesario. Para obtener información sobre este aspecto de las rutas de acceso indexadas, consulte Binding.Path.

Varias propiedades (destino de propiedad indirecto)

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

propertyName debe resolverse para ser el nombre de una propiedad que exista en 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.

Propiedad única, adjunta o calificada por tipo

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

Los paréntesis indican que esta propiedad de un objeto PropertyPath se debe construir con una calificación parcial. Puede usar un espacio de nombres XML para buscar el tipo con la asignación adecuada. ownerType busca los tipos a los que tiene acceso el procesador XAML mediante las declaraciones XmlnsDefinitionAttribute en cada ensamblado. 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. propertyName debe resolverse para ser el nombre de una propiedad que exista en ownerType. Esta sintaxis se usa, normalmente, para uno de los siguientes casos:

• Se especifica la ruta de acceso en XAML que tiene un estilo o plantilla sin un tipo de destino especificado. 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.

• La propiedad es una propiedad adjunta.

• Está enlazando a una propiedad estática.

Para usarla como destino de guion gráfico, la propiedad especificada como propertyName debe ser DependencyProperty.

Recorrido de origen (enlace a jerarquías de colecciones)

<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. 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. 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.

Vistas de colección

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.

Puntero de registro actual

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 (/). Cualquier ruta de acceso posterior a la barra diagonal se recorre desde el puntero de registro actual.

Varios indizadores

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

o

<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. El objeto en cuestión puede ser el contexto actual o el valor de una propiedad que contenga un objeto de índice múltiple.

De forma predeterminada, se asignan tipos a los valores del indizador con las características del objeto subyacente. Puede especificar el tipo del índice si es necesario. Para obtener información sobre los tipos de indizadores, consulte Binding.Path.

Sintaxis mixtas

Se pueden intercalar todas las sintaxis mostradas anteriormente. Por ejemplo, el siguiente es un ejemplo que crea una ruta de acceso de propiedades al color en una posición x,y determinada de una propiedad ColorGrid que contiene una matriz de cuadrícula de píxeles de objetos SolidColorBrush:

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

Secuencias de escape para cadenas de ruta de acceso de propiedad

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. 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.

• Dentro de los indizadores ([ ]), el carácter de intercalación (^) realiza el escape del carácter siguiente.

• Debe realizar el escape (mediante entidades XML) de determinados caracteres que son especiales para la definición del lenguaje XML. Use & para realizar el escape del carácter "&". Use > para realizar el escape de la etiqueta final >.

• 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.

  • La barra diagonal inversa (\) es el mismo carácter de escape.

  • El signo igual (=) separa el nombre de propiedad del valor de propiedad.

  • La coma (,) separa las propiedades.

  • La llave de cierre (}) es el final de una extensión de marcado.

PropertyPath para destinos de animación

La propiedad de destino de una animación debe ser una propiedad de dependencia que obtenga un tipo Freezable o primitivo. Sin embargo, la propiedad de destino de un tipo y la propiedad animada final pueden existir en objetos diferentes. 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.

Consideraciones de las propiedades de objetos generales para animaciones

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.

El tipo de valor o la propiedad que se anima debe ser un tipo Freezable o primitivo. La propiedad que inicia la ruta de acceso debe resolverse para ser el nombre de una propiedad de dependencia que exista en el tipo TargetName especificado.

Para admitir la clonación para animar un Freezable que ya está congelado, 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 ser el nombre de una propiedad de dependencia que existe en el tipo TargetName especificado.

Destino de propiedad indirecto

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

propertyName debe ser una propiedad que es un tipo de valor Freezable o primitivo, que existe en el tipo TargetName especificado.

propertyName2 debe ser el nombre de una propiedad de dependencia que exista en el objeto que es el valor de propertyName. Es decir, propertyName2 debe existir como una propiedad de dependencia en el tipo que es el propertyNamePropertyType.

El destino indirecto de animaciones es necesario debido a los estilos y las plantillas que se aplican. Para destinar una animación, se necesita un TargetName en un objeto de destino, y que el nombre lo establezca x:Name o 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. (Si las plantillas y los estilos compartieran ámbitos de nombres con marcado de aplicación, los nombres no podrían ser únicos. Los estilos y plantillas se comparten literalmente entre instancias y perpetuarían nombres duplicados). Por lo tanto, si las propiedades individuales de un elemento que desea animar proceden de un estilo o plantilla, debe empezar con una instancia de elemento con nombre que no procede de una plantilla de estilo y, a continuación, dirigirse al árbol visual de estilo o plantilla para llegar a la propiedad que desea animar.

Por ejemplo, la propiedad Background de un Panel es un Brush completo (en realidad, un SolidColorBrush) cuyo origen es una plantilla de tema. Para animar un objeto Brush completamente, debería haber un tipo BrushAnimation (probablemente, uno por cada tipo Brush) y dicho tipo no existe. Para animar un pincel, se animan propiedades de un tipo Brush en su lugar. Se debe obtener de SolidColorBrush a su Color para aplicar ahí un ColorAnimation. La ruta de acceso de propiedad de este ejemplo sería Background.Color.

Propiedades adjuntas

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

Los paréntesis indican que esta propiedad de un objeto PropertyPath se debe construir con una calificación parcial. Puede usar un espacio de nombres XML para buscar el tipo. ownerType busca los tipos a los que tiene acceso el procesador XAML mediante las declaraciones XmlnsDefinitionAttribute en cada ensamblado. 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. propertyName debe resolverse para ser el nombre de una propiedad que exista 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 propiedades de dependencia o tipos Freezable no admiten indizadores. 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. En la sintaxis proporcionada, es propertyName2. Por ejemplo, el uso del indizador 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.

PropertyPath en código

El uso del código para PropertyPath, que incluye 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 firma PropertyPath(Object) para los usos de enlace en los que el objeto es una cadena. Use la firma PropertyPath(Object) para trayectorias de animación de un paso en las que el objeto es un DependencyProperty. Use la firma PropertyPath(String, Object[]) para animaciones complejas. 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.

Vea también

• PropertyPath
• Información general sobre el enlace de datos
• Información general sobre objetos Storyboard