PropertyPath XAML 語法PropertyPath XAML Syntax

物件支援複雜的內嵌XAMLXAML語法, 用於設定以PropertyPath類型做為其值的各種屬性。 PropertyPathThe 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. 雖然使用一般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.

主要是PropertyPath用來描述物件模型路徑, 以便遍歷物件資料來源的屬性, 以及描述目標動畫的目標路徑。 WPFWPFPrimarily, 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. 但這不是 true 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.

XMLXML注意, 資料系結不會使用PropertyPath, 因為它不會Path使用中Binding的。Note that data binding to XMLXML does not use PropertyPath, because it does not use Path in the Binding. 相反地, 您XPath可以使用, 並在資料的XML 文件物件模型 (DOM)XML Document Object Model (DOM)中指定有效的 XPath 語法。Instead, you use XPath and specify valid XPath syntax into the XML 文件物件模型 (DOM)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. 資料系結引擎會自動將當做資料來源使用的集合與系結目標的型別進行比對, 因而產生像是以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.Path參閱。For 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每個元件中XAMLXAMLXmlnsDefinitionAttribute宣告, 搜尋處理器可以存取的類型。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 DependencyProperty鏡腳本目標使用, 指定為的屬性必須是。For 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.

注意

此語法外表上類似 XPathXPathSuperficially, this syntax resembles XPathXPath. 系結XPathXPath Path至資料來源的 true 運算式不會當做值使用, XPath應該改為用於互斥屬性。 XMLXMLA true XPathXPath expression for binding to an XMLXML 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.Path, 請參閱。For details on typing the indexers, see Binding.Path.

混合語法Mixing Syntaxes

上述語法可穿插使用。Each of the syntaxes shown above can be interspersed. 例如, 下列範例會在ColorGrid屬性的特定 x、y 上建立色彩的屬性路徑, 其中包含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}" .../>

屬性路徑字串的逸出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

動畫的目標屬性必須是接受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必須是實Freezable數值型別或基本類型的屬性, 其存在於指定TargetName的類型上。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.

例如, Background的屬性Panel是來自主題範本的完整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. 您必須從SolidColorBrush Color取得,才能在該處套用。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每個元件中XAMLXAMLXmlnsDefinitionAttribute宣告, 搜尋處理器可以存取的類型。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的屬性必須DependencyProperty是。The 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