PropertyPath XAML 语法PropertyPath XAML Syntax

PropertyPath 对象支持复杂的内联 XAMLXAML 语法,用于设置采用 PropertyPath 类型作为值的各种属性。The PropertyPath object supports a complex inline XAMLXAML syntax for setting various properties that take the PropertyPath type as their value. 本主题将 PropertyPath 语法记录为应用于绑定和动画语法。This topic documents the PropertyPath syntax as applied to binding and animation syntaxes.

PropertyPath 的使用情景Where PropertyPath Is Used

PropertyPath 是在多个 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. 尽管使用 common PropertyPath 来传达属性路径信息,但每个功能区域的用法(其中 PropertyPath 用作类型)各不相同。Despite using the common PropertyPath to convey property path information, the usages for each feature area where PropertyPath is used as a type vary. 因此,基于每个功能来讨论语法更为可行。Therefore, it is more practical to document the syntaxes on a per-feature basis.

WPFWPF 使用 PropertyPath 来描述对象模型路径,以便遍历对象数据源的属性,以及描述目标动画的目标路径。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.

某些样式和模板属性(如 Setter.Property)采用表面上类似于 PropertyPath的限定属性名称。Some style and template properties such as Setter.Property take a qualified property name that superficially resembles a PropertyPath. 但这并不是真正的 PropertyPath;相反,它是限定所有者。 由 WPF XAMLXAML 处理器与 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.

数据绑定中对象的 PropertyPathPropertyPath for Objects in Data Binding

数据绑定是 WPFWPF 功能,借此可以绑定到任意依赖属性的目标值。Data binding is a WPFWPF feature whereby you can bind to the target value of any dependency property. 但是,此类数据绑定的源不需要是依赖属性;可以是适用数据提供程序能识别的任意属性类型。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. 属性路径特别用于 ObjectDataProvider,后者用于从公共语言运行时(CLR)对象及其属性获取绑定源。Property paths are particularly used for the ObjectDataProvider, which is used for obtaining binding sources from common language runtime (CLR) objects and their properties.

请注意,数据绑定到 XML 不会使用 PropertyPath,因为它不使用 BindingPathNote that data binding to XML does not use PropertyPath, because it does not use Path in the Binding. 相反,可以使用 XPath,并将有效的 XPath 语法指定到数据的 XML 文档对象模型(DOM)中。Instead, you use XPath and specify valid XPath syntax into the XML Document Object Model (DOM) of the data. 还将 XPath 指定为字符串,但此处未记录此内容;请参阅使用 XMLDataProvider 和 XPath 查询绑定到 XML 数据XPath is also specified as a string, but is not documented here; see Bind to XML Data Using an XMLDataProvider and XPath Queries.

理解数据绑定中的属性路径的关键是将绑定到单个属性值设置为目标,或者改为绑定到采用列表或集合的目标属性。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. 如果要绑定集合,例如绑定将根据集合中的数据项数扩展的 ListBox,则属性路径应引用集合对象,而不是单个集合项。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. 数据绑定引擎会自动将用作数据源的集合与绑定目标的类型匹配,从而导致诸如使用 items 数组填充 ListBox 的行为。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.

直接对象上作为数据上下文的单个属性Single Property on the Immediate Object as Data Context

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

propertyName必须解析为当前 DataContext 中的属性的名称,以供 Path 使用。propertyName must resolve to be the name of a property that is in the current DataContext for a Path usage. 如果绑定更新源,则属性必须是可读取/写入的,并且源对象必须可变。If your binding updates the source, that property must be read/write and the source object must be mutable.

直接对象上作为数据上下文的单个索引器Single Indexer on the Immediate Object as Data Context

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

key 必须是字典或哈希表的类型化索引,或者是数组的整数索引。key must be either the typed index to a dictionary or hash table, or the integer index of an array. 此外,键值必须是可直接绑定到所应用属性的类型。Also, the value of the key must be a type that is directly bindable to the property where it is applied. 例如,可以通过这种方式使用包含字符串键和字符串值的哈希表绑定到 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. 或者,如果键指向集合或子索引,则可使用此语法绑定到目标集合属性。Or, if the key points to a collection or subindex, you could use this syntax to bind to a target collection property. 否则,需要通过 <Binding Path="[key].propertyName" .../> 等语法来引用特定属性。Otherwise, you need to reference a specific property, through a syntax such as <Binding Path="[key].propertyName" .../>.

如有必要,可以指定索引的类型。You can specify the type of the index if necessary. 有关索引属性路径的这一方面的详细信息,请参阅 Binding.PathFor details on this aspect of an indexed property path, see Binding.Path.

多个属性(间接属性目标设置)Multiple Property (Indirect Property Targeting)

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

propertyName 必须解析为作为当前 DataContext的属性的名称。propertyName must resolve to be the name of a property that is the current DataContext. 路径属性 propertyNamepropertyName2 可以是关系中的任意属性,其中 propertyName2 是存在于类型中的值为 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.

附加的或类型限定的单个属性Single Property, Attached or Otherwise Type-Qualified

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

圆括号指示 PropertyPath 中的此属性应使用部分限定构造。The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. 它可以使用 XML 命名空间来查找具有适当映射的类型。It can use an XML namespace to find the type with an appropriate mapping. ownerType 通过每个程序集中的 XmlnsDefinitionAttribute 声明搜索 XAMLXAML 处理器有权访问的类型。The ownerType searches types that a XAMLXAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. 大部分应用程序都具有映射到 http://schemas.microsoft.com/winfx/2006/xaml/presentation 命名空间的默认 XML 命名空间,因此通常仅有自定义类型或该命名空间之外的类型才需要前缀。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 必须解析为 ownerType 中存在的属性名称。propertyName must resolve to be the name of a property existing on the ownerType. 此语法一般用于以下任一情况:This syntax is generally used for one of the following cases:

  • 路径是在 XAMLXAML 中的样式或模板(该样式或模板没有指定的目标类型)中指定的。The path is specified in XAMLXAML that is in a style or template that does not have a specified Target Type. 除此之外,限定用法一般无效,因为在非样式、非模板情况下,属性存在于实例中,而不是类型中。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.

  • 属性为附加属性。The property is an attached property.

  • 要绑定到静态属性中。You are binding to a static property.

要用作情节提要目标,指定为 propertyName 的属性必须是 DependencyPropertyFor use as storyboard target, the property specified as propertyName must be a DependencyProperty.

源遍历(绑定到集合的层次结构)Source Traversal (Binding to Hierarchies of Collections)

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

此语法中的 / 用于在分层数据源对象中导航,并且支持使用连续的 / 字符分多个步骤导航层次结构。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. 源遍历说明了当前记录指针位置,该位置是通过将数据与其视图的 UI 同步而确定的。The source traversal accounts for the current record pointer position, which is determined by synchronizing the data with the UI of its view. 有关与分层数据源对象绑定的详细信息,以及数据绑定中当前记录指针的概念,请参阅对分层数据使用主-从模式数据绑定概述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.

备注

在表面上,此语法类似于 XPath。Superficially, this syntax resembles XPath. 用于绑定到 XML 数据源的真正的 XPath 表达式不用作 Path 值,应改为用于互斥的 XPath 属性。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.

集合视图Collection Views

若要引用一个已命名的集合视图,请使用哈希字符 (#) 为集合视图名称添加前缀。To reference a named collection view, prefix the collection view name with the hash character (#).

当前记录指针Current Record Pointer

若要引用集合视图的当前记录指针或引用主从数据绑定方案,请启用带正斜杠 (/) 的路径字符串。To reference the current record pointer for a collection view or master detail data binding scenario, start the path string with a forward slash (/). 从当前记录指针开始遍历任何超出正斜杠的路径。Any path past the forward slash is traversed starting from the current record pointer.

多个索引器Multiple Indexers

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

or

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

如果给定的对象支持多个索引器,则可以按顺序指定这些索引器,类似于数组引用语法。If a given object supports multiple indexers, those indexers can be specified in order, similar to an array referencing syntax. 上述对象可以是当前上下文,也可以是包含多个索引对象的属性的值。The object in question can be either the current context or the value of a property that contains a multiple index object.

默认情况下,通过使用基础对象的特性来类型化索引器值。By default, the indexer values are typed by using the characteristics of the underlying object. 如有必要,可以指定索引的类型。You can specify the type of the index if necessary. 有关键入索引器的详细信息,请参阅 Binding.PathFor details on typing the indexers, see Binding.Path.

混合语法Mixing Syntaxes

上述每条语法都可以独立使用。Each of the syntaxes shown above can be interspersed. 例如,下面的示例创建了一个属性路径,该属性指向 ColorGrid 属性(包含 SolidColorBrush 对象的像素网格数组)的特定 x、y 的颜色: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}" .../>

属性路径字符串的转义Escapes for Property Path Strings

对于某些业务对象,你可能会遇到这样的情况:属性路径字符串需要转义序列以进行正确分析。For certain business objects, you might encounter a case where the property path string requires an escape sequence in order to parse correctly. 因为大多数此类字符在常用于定义业务对象的语言方面具有类似的命名交互问题,因此转义需要非常少见。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.

  • 在索引器 ([ ]) 内部,脱字符号 (^) 用于对下一个字符进行转义。Inside indexers ([ ]), the caret character (^) escapes the next character.

  • 必须(使用 XML 实体)对 XML 语言定义专用的某些字符进行转义。You must escape (using XML entities) certain characters that are special to the XML language definition. 使用 & 对字符“&”进行转义。Use & to escape the character "&". 使用 > 对结束标记“>”进行转义。Use > to escape the end tag ">".

  • 必须(使用反斜杠 \)对特定于 WPF XAML 分析程序行为的字符进行转义,以处理标记扩展。You must escape (using backslash \) characters that are special to the WPF XAML parser behavior for processing a markup extension.

    • 反斜杠 (\) 本身是转义字符。Backslash (\) is the escape character itself.

    • 等号 (=) 将属性名与属性值分隔开。The equal sign (=) separates property name from property value.

    • 逗号 (,) 用于分隔属性。Comma (,) separates properties.

    • 右大括号 (}) 是标记扩展的结尾。The right curly brace (}) is the end of a markup extension.

备注

从技术上讲,这些转义符还适用于情节提要属性路径,但通常会遍历适用于现有 WPF 对象的对象模型,转义应该是不必要的。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.

动画目标的 PropertyPathPropertyPath for Animation Targets

动画的 target 属性必须是采用 Freezable 或基元类型的依赖项属性。The target property of an animation must be a dependency property that takes either a Freezable or a primitive type. 但是,类型中的目标属性和最终动画属性可以存在于不同的对象中。However, the targeted property on a type and the eventual animated property can exist on different objects. 对于动画,属性路径用于通过遍历属性值中的对象-属性关系,定义命名动画目标对象的属性和预期目标动画属性之间的连接。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.

动画的一般对象-属性注意事项General Object-Property Considerations for Animations

有关一般动画概念的详细信息,请参阅情节提要概述动画概述For more information on animation concepts in general, see Storyboards Overview and Animation Overview.

要进行动画处理的值类型或属性必须是 Freezable 类型或基元类型。The value type or the property being animated must be either a Freezable type or a primitive. 启动路径的属性必须解析为存在于指定 TargetName 类型上的依赖属性的名称。The property that starts the path must resolve to be the name of a dependency property that exists on the specified TargetName type.

为了支持克隆以对已冻结 Freezable 进行动画处理,TargetName 指定的对象必须是 FrameworkElementFrameworkContentElement 派生类。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.

目标对象上的单个属性Single Property on the Target Object

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

propertyName 必须解析为存在于指定 TargetName 类型上的依赖属性的名称。propertyName must resolve to be the name of a dependency property that exists on the specified TargetName type.

间接属性目标设定Indirect Property Targeting

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

propertyName 必须是指定 TargetName 类型上存在 Freezable 值类型或基元类型的属性。propertyName must be a property that is either a Freezable value type or a primitive, which exists on the specified TargetName type.

propertyName2 必须为依赖属性的名称,该属性存在于作为 propertyName 值的对象中。propertyName2 must be the name of a dependency property that exists on the object that is the value of propertyName. 换句话说,propertyName2 必须作为 propertyName PropertyType的类型的依赖项属性存在。In other words, propertyName2 must exist as a dependency property on the type that is the propertyName PropertyType.

因为应用了样式和模板,所以间接设定动画的目标是必要的。Indirect targeting of animations is necessary because of applied styles and templates. 若要以动画为目标,需要对目标对象具有 TargetName,且该名称是由x:NameName建立的。In order to target an animation, you need a TargetName on a target object, and that name is established by x:Name or Name. 虽然模板和样式元素也可以有名称,但这些名称仅在样式和模板的命名范围内有效。Although template and style elements also can have names, those names are only valid within the namescope of the style and template. (如果模板和样式与应用程序标记共享命名范围,则名称不唯一。(If templates and styles did share namescopes with application markup, names couldn't be unique. 样式和模板按字面方式在实例之间共享,并且将保持重复的名称。)因此,如果您想要对某个元素的单个属性进行动画处理,则需要从样式或模板开始,而不是从样式模板开始,然后以样式或模板可视化树为目标,以到达属性要进行动画处理。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.

例如,PanelBackground 属性是来自主题模板的完整 Brush (实际上是 SolidColorBrush)。For instance, the Background property of a Panel is a complete Brush (actually a SolidColorBrush) that came from a theme template. 若要完全对 Brush 进行动画处理,需要 BrushAnimation (可能每个 Brush 类型都有一个),并且没有此类类型。To animate a Brush completely, there would need to be a BrushAnimation (probably one for every Brush type) and there is no such type. 若要对画笔进行动画处理,请改为对特定 Brush 类型的属性进行动画处理。To animate a Brush, you instead animate properties of a particular Brush type. 需要从 SolidColorBrushColor,以便在其中应用 ColorAnimationYou need to get from SolidColorBrush to its Color to apply a ColorAnimation there. 本示例的属性路径是 Background.ColorThe property path for this example would be Background.Color.

附加屬性Attached Properties

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

圆括号指示 PropertyPath 中的此属性应使用部分限定构造。The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. 可以使用 XML 命名空间来查找类型。It can use an XML namespace to find the type. ownerType 通过每个程序集中的 XmlnsDefinitionAttribute 声明搜索 XAMLXAML 处理器有权访问的类型。The ownerType searches types that a XAMLXAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. 大部分应用程序都具有映射到 http://schemas.microsoft.com/winfx/2006/xaml/presentation 命名空间的默认 XML 命名空间,因此通常仅有自定义类型或该命名空间之外的类型才需要前缀。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 必须解析为 ownerType 中存在的属性名称。propertyName must resolve to be the name of a property existing on the ownerType. 指定为 propertyName 的属性必须是 DependencyPropertyThe property specified as propertyName must be a DependencyProperty. (所有 WPFWPF 附加属性都实现为依赖属性,因此该问题仅与自定义附加属性相关。)(All WPFWPF attached properties are implemented as dependency properties, so this issue is only of concern for custom attached properties.)

索引器Indexers

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

大多数依赖属性或 Freezable 类型不支持索引器。Most dependency properties or Freezable types do not support an indexer. 因此,动画路径中唯一使用索引器的地方是在用于启动命名目标上的链的属性与最终动画属性之间的中间位置。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. 在提供的语法中,为 propertyName2In the provided syntax, that is propertyName2. 例如,如果中间属性是 TransformGroup的集合(如 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.

代码中的 PropertyPathPropertyPath in Code

PropertyPath的代码用法(包括如何构造 PropertyPath)记录在有关 PropertyPath的参考主题中。Code usage for PropertyPath, including how to construct a PropertyPath, is documented in the reference topic for PropertyPath.

通常,PropertyPath 旨在使用两个不同的构造函数,一个用于绑定使用情况和最简单的动画用法,另一个用于复杂动画用法。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. PropertyPath(Object) 签名用于绑定用法,其中,对象是一个字符串。Use the PropertyPath(Object) signature for binding usages, where the object is a string. 为单步动画路径(其中对象是一个 DependencyProperty)使用 PropertyPath(Object) 签名。Use the PropertyPath(Object) signature for one-step animation paths, where the object is a DependencyProperty. 对复杂动画使用 PropertyPath(String, Object[]) 签名。Use the PropertyPath(String, Object[]) signature for complex animations. 后一种构造函数使用第一个参数的令牌字符串,以及在该令牌字符串中填充位置的对象的数组,以定义属性路径关系。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.

另请参阅See also