Property-path 语法Property-path syntax

可以使用 PropertyPath 类和字符串语法来实例化 XAML 或代码中的 PropertyPath 值。You can use the PropertyPath class and the string syntax to instantiate a PropertyPath value either in XAML or in code. PropertyPath 值由数据绑定使用。PropertyPath values are used by data binding. 目标情节提要动画使用相似的语法。A similar syntax is used for targeting storyboarded animations. 对于这两种情形,都由属性路径来描述最终解析为单个属性的一个或多个对象-属性关系的遍历。For both scenarios, a property path describes a traversal of one or more object-property relationships that eventually resolve to a single property.

可将属性路径字符串直接设置为 XAML 中的属性。You can set a property path string directly to an attribute in XAML. 可使用相同的字符串语法在代码中构造设置 BindingPropertyPath,或者使用 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. Windows 运行时中有两个不同的使用属性路径的功能区域:数据绑定和动画目标。There are two distinct feature areas in the Windows Runtime that use a property path: data binding, and animation targeting. 动画目标不在 Windows 运行时实现中创建基础 Property-path 语法值,它将此信息保留为字符串,但对象-属性遍历的概念非常相似。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. 数据绑定和动画目标各自计算属性路径的方式略有不同,因此我们分别描述它们的属性路径语法。Data binding and animation targeting each evaluate a property path slightly differently, so we describe property path syntax separately for each.

数据绑定中的对象的属性路径Property path for objects in data binding

在 Windows 运行时中,可以绑定到任何依赖属性的目标值。In Windows Runtime, you can bind to the target value of any dependency property. 数据绑定的源属性值不必是依赖属性;它可以是业务对象(例如使用 Microsoft .NET 语言或 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++). 或者说,绑定值的源对象可以是已由应用定义的现有依赖对象。Or, the source object for the binding value can be an existing dependency object already defined by the app. 源可由简单的属性名引用,也可由业务对象的对象图中的对象-属性关系的遍历引用。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.

可以绑定到单个的属性值,也可以绑定到包含列表或集合的目标属性。You can bind to an individual property value, or you can bind to a target property that holds lists or collections. 如果源是集合,或者路径指定了集合属性,则数据绑定引擎将源的集合项与绑定目标匹配,从而导致一些行为,例如使用来自数据源集合的项的列表来填充 ListBox,而无需预期该集合中的特定项。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.

遍历对象图Traversing an object graph

指示对象图中对象-属性关系的遍历的语法元素是点 (.) 字符。The element of the syntax that denotes the traversal of an object-property relationship in an object graph is the dot (.) character. 属性路径字符串中的每个点指示对象(点左侧)与该对象的属性(点右侧)的分界。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). 字符串按从左到右的顺序计算,这样可以逐一遍历多个对象-属性关系。The string is evaluated left-to-right, which enables stepping through multiple object-property relationships. 我们来看一个示例:Let's look at an example:

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

以下是评估此路径的方法:Here's how this path is evaluated:

  1. 为名为“Customer”的属性搜索数据上下文对象(或由相同的 Binding 指定的 Source)。The data context object (or a Source specified by the same Binding) is searched for a property named "Customer".
  2. 为名为“Address”的属性搜索作为“Customer”属性的值的对象。The object that is the value of the "Customer" property is searched for a property named "Address".
  3. 为名为“StreetAddress1”的属性搜索作为“Address”属性的值的对象。The object that is the value of the "Address" property is searched for a property named "StreetAddress1".

在上述每一步中,值都视为对象。At each of these steps, the value is treated as an object. 仅当绑定应用于特定属性时,才检查结果的类型。The type of the result is checked only when the binding is applied to a specific property. 如果“Address”是一个未提供字符串的哪个部分是街道地址的字符串值,此示例就会失败。This example would fail if "Address" were just a string value that didn't expose what part of the string was the street address. 通常,绑定指向具有缜密的已知信息结构的业务对象的特定嵌套属性值。Typically, the binding is pointing to the specific nested property values of a business object that has a known and deliberate information structure.

数据绑定属性路径中的属性所遵守的规则Rules for the properties in a data-binding property path

  • 由属性路径引用的所有属性在源业务对象中都必须是公开的。All properties referenced by a property path must be public in the source business object.
  • 结束属性(路径中作为最后一个命名属性的属性)必须是公开的,而且必须是可变的 — 无法绑定到静态值。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.
  • 如果此路径用作双向绑定的 Path 信息,则结束属性必须是可读取/写入的。The end property must be read/write if this path is used as the Path information for a two-way binding.

索引器Indexers

数据绑定的属性路径可以包括对编制了索引的属性的引用。A property path for data-binding can include references to indexed properties. 这样便可绑定到已排序的列表/矢量,或绑定到字典/地图。This enables binding to ordered lists/vectors, or to dictionaries/maps. 使用方括号 " [ ] " 字符来表示索引属性。Use square brackets "[]" characters to indicate an indexed property. 位于这些括号中的内容可以是整数(对于排序列表),也可以是不加引号的字符串(对于字典)。The contents of these brackets can be either an integer (for ordered list) or an unquoted string (for dictionaries). 还可以绑定到键为整数的字典。You can also bind to a dictionary where the key is an integer. 可以在同一路径中使用不同的编制了索引的属性,使用点分隔对象-属性。You can use different indexed properties in the same path with a dot separating the object-property.

例如,考虑一个业务对象,它有一个“Teams”的列表(排序列表),每个队有一本名为“Players”的字典,每个队员使用姓氏作为键。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. 第二个团队中的特定播放机的示例属性路径为: "团队 [ 1" ] 。运动员 [ Smith ] "。An example property path to a specific player on the second team is: "Teams[1].Players[Smith]". (使用 1 来指示“Teams”中的第二个项,因为该列表的索引是从零开始编制的。)(You use 1 to indicate the second item in "Teams" because the list is zero-indexed.)

注意   对 c + + 数据源的索引支持受到限制;深入查看数据绑定Note  Indexing support for C++ data sources is limited; see Data binding in depth.

附加属性Attached properties

属性路径可以包括对附加属性的引用。Property paths can include references to attached properties. 因为附加属性的识别名称中已包括点,所以你必须将任何附加属性名称括在括号内,以便不会将点视为对象-属性的分隔符。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. 例如,用于指定你希望使用 Canvas.ZIndex 作为绑定路径的字符串为“(Canvas.ZIndex)”。For example, the string to specify that you want to use Canvas.ZIndex as a binding path is "(Canvas.ZIndex)". 有关附加属性的详细信息,请参阅附加属性概述For more info on attached properties see Attached properties overview.

合并属性路径语法Combining property path syntax

可将属性路径语法的不同元素合并到一个字符串中。You can combine various elements of property path syntax in a single string. 例如,如果你的数据源具有编制了索引的附加属性,则你可以定义引用该属性的属性路径。For example, you can define a property path that references an indexed attached property, if your data source had such a property.

调试绑定属性路径Debugging a binding property path

因为属性路径由绑定引擎解释,并依赖于可能仅在运行时间才会呈现的信息,所以对于不能依靠开发工具中传统的设计时或编译时支持的绑定,你必须经常调试属性路径。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. 在许多情况下,无法解析属性路径的运行时结果是空值,但并不报错,因为这是绑定解决方案的由设计决定的回滚行为。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. 幸运的是,Microsoft Visual Studio 提供了调试输出模式,该模式可将指定绑定源解析失败的属性路径部分隔离。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. 有关使用此开发工具功能的详细信息,请参阅“深入了解数据绑定”的“调试”部分For more info on using this development tool feature, see "Debugging" section of Data binding in depth.

动画目标的属性路径Property path for animation targeting

动画依赖于选择在动画运行时便应用情节提要值的依赖属性作为目标。Animations rely on targeting a dependency property where storyboarded values are applied when the animation runs. 为了标识存在待进行动画处理的属性的对象,动画按名称(x:Name 属性)选择元素作为目标。To identify the object where the property to be animated exists, the animation targets an element by name (x:Name attribute). 通常需要定义以标识为 Storyboard.TargetName 的对象开始、以应该应用动画的特殊依赖属性值结束的属性路径。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. 属性路径用作 Storyboard.TargetProperty 的值。That property path is used as the value for Storyboard.TargetProperty.

有关如何在 XAML 中定义动画的详细信息,请参阅情节提要动画For more info on the how to define animations in XAML, see Storyboarded animations.

简单目标处理Simple targeting

如果要对在作为目标的对象本身上存在的属性进行动画处理,且该属性的类型可以具有直接应用到属性(而不是应用到属性值的子属性)的动画,则只命名要进行动画处理的属性,无需进行进一步限定。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. 例如,如果要将 RectangleShape 子类作为目标,并将经过动画处理的 Color 应用于 Fill 属性,则属性路径可以是“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".

间接属性目标处理Indirect property targeting

可对作为目标对象的子属性的属性进行动画处理。You can animate a property that is a sub-property of the target object. 也就是说,如果存在的目标对象属性本身是一个对象,且该对象具有属性,则必须定义一个属性路径来解释如何逐一遍历该对象-属性关系。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. 无论何时,只要你指定希望对子属性进行动画处理的对象,就需要将属性名括在括号内,并以 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. 例如,要指定你需要目标对象的 RenderTransform 属性的对象值,你就要指定“(UIElement.RenderTransform)”作为属性路径中的第一步。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. 这还不是一个完整的路径,因为没有可以直接应用到 Transform 值的动画。This isn't yet a complete path, because there are no animations that can apply to a Transform value directly. 因此,对于此示例,现在将该属性路径完整化,以使结束属性作为可由 Double 值“(UIElement.RenderTransform).(CompositeTransform.TranslateX)”进行动画处理的 Transform 子类的属性。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)"

指定集合中的特定子项Specifying a particular child in a collection

若要指定集合属性中的子项,可以使用数值索引器。To specify a child item in a collection property, you can use a numeric indexer. [ ] 在整数索引值两边使用方括号 "" 字符。Use square brackets "[]" characters around the integer index value. 可以只引用排序列表,不引用字典。You can reference only ordered lists, not dictionaries. 因为集合不是可进行动画处理的值,所以使用索引器时绝不能将索引器作为属性路径中的结束属性。Because a collection isn't a value that can be animated, an indexer usage can never be the end property in a property path.

例如,若要指定要对应用于控件的背景属性的LinearGradientBrush中的第一种颜色停止颜色进行动画处理,则这是属性路径: " (GradientStops) (.) [ system.windows.media.gradientstop>. ] (。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)". 注意如何实现不将索引器作为路径中的最后一步,尤其要注意最后一步必须引用集合中项 0 的 GradientStop.Color 属性来对它应用 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.

对附加属性进行动画处理Animating an attached property

虽然并不是常见情形,但可以对附加属性进行动画处理,前提是附加属性具有与动画类型匹配的属性值。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. 因为附加属性的识别名称中已包括点,所以你必须将任何附加属性名称括在括号内,以便不会将点视为对象-属性的分隔符。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. 例如,用于指定你希望对某个对象上的 LinearGradientBrush 附加属性进行动画处理的字符串使用属性路径“(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)".

注意   在此示例中, Grid的值为Int32属性类型。Note  For this example, the value of Grid.Row is an Int32 property type. 因此无法使用 Double 动画对其进行动画处理,so you can't animate it with a Double animation. 而应该定义一个具有 DiscreteObjectKeyFrame 组件的 ObjectAnimationUsingKeyFrames,其中 ObjectKeyFrame.Value 设置为整数(如“0”或“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".

动画目标属性路径中的属性所遵守的规则Rules for the properties in an animation targeting property path

  • 属性路径的假定起始点是由 Storyboard.TargetName 标识的对象。The assumed starting point of the property path is the object identified by a Storyboard.TargetName.
  • 随属性路径引用的所有对象和属性都必须是公开的。All objects and properties referenced along the property path must be public.
  • 结束属性(路径中作为最后一个命名属性的属性)必须是公开的、可读写的,而且必须是依赖属性。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.
  • 结束属性必须具有可由几大动画类型(Color 动画、Double 动画、Point 动画、ObjectAnimationUsingKeyFrames)中的一类进行动画处理的属性类型。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).

PropertyPath 类The PropertyPath class

PropertyPath 类是用于绑定方案的 Binding.Path 的基础属性类型。The PropertyPath class is the underlying property type of Binding.Path for the binding scenario.

大多数情况下,你可以在 XAML 中应用 PropertyPath,而根本不使用任何代码。Most of the time, you can apply a PropertyPath in XAML without using any code at all. 但在某些情况下,你可能希望使用代码定义一个 PropertyPath 对象并在运行时将其分配给某个属性。But in some cases you may want to define a PropertyPath object using code and assign it to a property at run-time.

PropertyPath 有一个 PropertyPath(String) 构造函数,没有默认构造函数。PropertyPath has a PropertyPath(String) constructor, and doesn't have a default constructor. 你传递给此构造函数的字符串是一个使用我们前面介绍的属性路径语法定义的字符串。The string you pass to this constructor is a string that's defined using the property path syntax as we explained earlier. 这也是你用于将 Path 分配为 XAML 属性的同一字符串。This is also the same string you'd use to assign Path as a XAML attribute. PropertyPath 类的另一个(也是唯一一个)API 是 Path 属性,该属性是只读的。The only other API of the PropertyPath class is the Path property, which is read-only. 你可以将此属性用作另一个 PropertyPath 实例的构造字符串。You could use this property as the construction string for another PropertyPath instance.