PropertyPath XAML 語法

發行項
09/27/2024

PropertyPath 物件支援複雜的內嵌 XAML 語法，以設定以 PropertyPath 類型作為其值的各種屬性。本主題記載應用於綁定和動畫語法的 PropertyPath 語法。

PropertyPath 的用途

PropertyPath 是一個通用物件，用於數個 Windows Presentation Foundation （WPF）功能。儘管使用一般 PropertyPath 來傳達屬性路徑資訊，但 PropertyPath 作為類型使用的每個功能區域使用方式會有所不同。因此，依功能來說明語法會比較實際。

主要來說，WPF 會使用 PropertyPath 來描述物件模型路徑來周遊對象數據源的屬性，以及描述目標動畫的目標路徑。

某些樣式和範本屬性，例如 Setter.Property 會採用表面上類似於 PropertyPath的限定屬性名稱。但這不是真正的 PropertyPath;相反地，它是高品質的 擁有的屬性 WPF XAML 處理器所啟用的字串格式使用方式，結合 DependencyProperty的類型轉換器。

資料繫結中物件的 PropertyPath

數據綁定是 WPF 功能，您可以綁定任一相依性屬性的目標值。不過，這類資料繫結的來源不需要是相依性屬性；它可以是適用的資料提供者所能辨識的任何屬性類型。屬性路徑特別用於 ObjectDataProvider，用於從 Common Language Runtime （CLR）物件及其屬性取得綁定來源。

請注意，對 XML 的數據綁定不會使用 PropertyPath，因為它不會在 Binding 中使用 Path。相反地，您會使用 XPath ，並將有效的 XPath 語法指定到數據的 XML 檔物件模型（DOM）中。 XPath 也會指定為字串，但此處未記載;請參閱使用 XMLDataProvider 和 XPath 查詢綁定至 XML 數據。

若要了解資料繫結中的屬性路徑，關鍵在於您可以將繫結的目標設為個別的屬性值，也可以改為繫結至要取得清單或集合的目標屬性。如果您是綁定集合，例如綁定 ListBox 會根據集合中的數據項數量而展開，則屬性路徑應該參考集合物件，而不是個別的集合專案。數據綁定引擎會自動比對做為數據源的集合與綁定目標的型別，形成像是將項目陣列填入 ListBox 之類的行為。

直接物件上做為資料內容的單一屬性

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

propertyName 必須解析為目前 DataContext 中 Path 使用方式的屬性名稱。如果您的繫結會更新來源，則該屬性必須是讀取/寫入屬性，且來源物件必須是可變動的。

直接物件上做為資料內容的單一索引子

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

key 必須是對字典或雜湊表之具類型的索引，或是陣列的整數索引。此外，索引鍵值的類型必須是可直接繫結至要套用它的屬性。例如，包含字串索引鍵和字串值的哈希表可用來綁定至 TextBox的 Text。或者，如果索引鍵指向集合或子索引，您可以使用此語法來繫結至目標集合屬性。否則，您需要透過語法 (例如 <Binding Path="[key].propertyName" .../>) 來參考特定的屬性。

您可以視需要指定索引的類型。如需索引屬性路徑這個層面的詳細資訊，請參閱 Binding.Path。

多個屬性 (間接屬性目標設定)

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

propertyName 必須解析為目前 DataContext的屬性名稱。路徑屬性 propertyName 和 propertyName2 可以是存在於關聯性中的任何屬性，其中 propertyName2 是存在於值為 propertyName 之類型中的屬性。

單一屬性 (附加或類型限定)

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

括號表示應該使用部分限定性來建構 PropertyPath 中的這個屬性。它可以使用 XML 命名空間來尋找具有適當對應的類型。 ownerType 會透過每個元件中的 XmlnsDefinitionAttribute 宣告，搜尋 XAML 處理器可存取的類型。大部分的應用程式都有對應至 http://schemas.microsoft.com/winfx/2006/xaml/presentation 命名空間的預設 XML 命名空間，因此，前置詞通常只需用於自訂類型或該命名空間以外的類型。 propertyName 必須解析為存在於 ownerType 上的屬性名稱。此語法通常用於下列其中一種情況：

路徑是在 XAML 中指定，該路徑位於沒有指定目標類型的樣式或範本中。除此之外，限定用法通常是無效的，因為在非樣式和非範本的情況中，屬性會存在於執行個體上，而非類型上。
屬性是附加屬性。
您要繫結至靜態屬性。

若要當做分鏡文稿目標使用，指定為 propertyName 的屬性必須是 DependencyProperty。

來源周遊 (繫結至集合的階層)

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

此語法中的 / 是用來在階層式資料來源物件內進行巡覽，並支援含有連續 / 字元之階層的多個步驟。來源周遊負責目前的記錄指標位置，這是藉由將資料與其檢視的 UI 同步處理來判斷。如需與階層式資料來源物件繫結的詳細資訊，以及資料繫結中目前記錄指標的概念，請參閱使用含階層式資料的主從式模式或資料繫結概觀。

注意

從表面上看，此語法類似於 XPath。綁定至 XML 數據源的 True XPath 運算式不會當做 Path 值使用，而應該改為用於互斥 XPath 屬性。

集合檢視

若要參考具名的集合檢視，請在集合檢視名稱前面加上雜湊字元 (#)。

目前的記錄指標

若要參考集合檢視的目前記錄指標或是一對多資料繫結案例，請以正斜線 (/) 做為路徑字串的開頭。任何超過正斜線的路徑，都會從目前的記錄指標開始周遊。

多個索引子

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

或

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

如果特定物件支援多個索引子，就可依順序指定那些索引子，類似陣列參考語法。上述物件可以是目前的內容，或是包含多重索引物件的屬性值。

根據預設，索引子值是使用基礎物件的特性來輸入。您可以視需要指定索引的類型。如需輸入索引器的詳細資訊，請參閱 Binding.Path。

混合語法

上述語法可穿插使用。例如，下列範例會在包含 SolidColorBrush 物件的圖元方格陣列的 ColorGrid 屬性的特定 x，y 建立色彩的屬性路徑：

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

屬性路徑字串的逸出

對於某些商務物件，您可能會遇到屬性路徑字串需要逸出序列，才能正確剖析的情況。需要逸出的情況應該相當罕見，因為在通常用來定義商務物件的語言中，這其中許多字元都有類似的命名互動問題。

在索引子 ([ ]) 內，插入號字元 (^) 會逸出下一個字元。
您必須將專屬於 XML 語言定義的某些字元逸出 (使用 XML 實體)。使用 & 逸出 "&" 字元。使用 > 逸出結尾標記「>」。
您必須將專屬於用來處理標記延伸之 WPF XAML 剖析器行為的字元逸出 (使用反斜線 \)。
- 反斜線 (\) 本身是逸出字元。
- 等號 (=) 會分隔屬性名稱和屬性值。
- 逗號 (,) 會分隔屬性。
- 右大括號 (}) 是標記延伸的結尾。

注意

技術上來說，這些逸出也適用於分鏡腳本屬性路徑，但您通常會周遊現有 WPF 物件的物件模型，因此應該不需要逸出。

動畫目標的 PropertyPath

動畫的目標屬性必須是採用 Freezable 或基本類型的相依性屬性。不過，類型上的目標屬性和最終動畫屬性可存在於不同物件上。對動畫來說，屬性路徑是用來定義具名動畫目標物件的屬性與所需目標動畫屬性之間的關係，方法則是周遊屬性值中的物件-屬性關聯性。

動畫的一般物件-屬性考量

如需一般動畫概念的詳細資訊，請參閱分鏡腳本概觀和動畫概觀。

實值型別或正在產生動畫效果的屬性必須是 Freezable 類型或基本類型。啟動路徑的屬性必須解析為存在於指定之 TargetName 類型的相依性屬性名稱。

為了支援複製已凍結的 Freezable 動畫， TargetName 所指定的對象必須是 FrameworkElement 或 FrameworkContentElement 衍生類別。

目標物件上的單一屬性

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

propertyName 必須解析為存在於指定之 TargetName 型別上的相依性屬性名稱。

間接屬性目標

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

propertyName 必須是 Freezable 實值型別或基本型別的屬性，存在於指定的 TargetName 型別上。

propertyName2 必須是存在於值為 propertyName 之物件上的相依性屬性名稱。換句話說， propertyName2 必須以 propertyName PropertyType類型上的相依性屬性存在。

由於已套用樣式和範本，因此需要間接設定動畫的目標。若要以動畫為目標，您需要目標物件的 TargetName ，而且該名稱是由 x：名稱或 Name所建立。雖然範本和樣式元素也可以有名稱，但那些名稱只在樣式和範本的名稱範圍內有效 (如果範本和樣式會與應用程式標記共用名稱範圍，則名稱不能是唯一的。樣式和範本實際上會在執行個體之間共用，因此會永久保存重複的名稱)。所以，如果您希望顯示為動畫之元素的個別屬性是來自樣式或範本，您就必須從不是來自樣式範本的具名元素執行個體開始，然後將目標設為樣式或範本視覺化樹狀結構中，以到達您要顯示為動畫的屬性。

例如， Panel 的 Background 屬性是來自主題範本的完整 Brush （實際為 SolidColorBrush）。若要讓 Brush 完全產生動畫效果，必須有 BrushAnimation（可能每個 Brush 類型都有一個），而且沒有這類類型。若要建立 Brush 的動畫，您可以改為以動畫顯示特定 Brush 類型的屬性。您需要從 SolidColorBrush 到其 Color ，以在那裡套用 ColorAnimation。此範例的屬性路徑就是 Background.Color。

附加屬性

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

括號表示應該使用部分限定性來建構 PropertyPath 中的這個屬性。它可使用 XML 命名空間來尋找此類型。 ownerType 會透過每個元件中的 XmlnsDefinitionAttribute 宣告，搜尋 XAML 處理器可存取的類型。大部分的應用程式都有對應至 http://schemas.microsoft.com/winfx/2006/xaml/presentation 命名空間的預設 XML 命名空間，因此，前置詞通常只需用於自訂類型或該命名空間以外的類型。 propertyName 必須解析為存在於 ownerType 上的屬性名稱。指定為 propertyName 的屬性必須是 DependencyProperty。（所有 WPF 附加屬性都會實作為相依性屬性，因此這個問題只關於自定義附加屬性）

索引子

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

大部分的相依性屬性或 Freezable 類型都不支援索引器。因此，若要在動畫路徑中使用索引子，就只能在具名目標上開始鏈結的屬性與最終動畫屬性之間的中繼位置上使用。在所提供的語法中，就是 propertyName2。例如，如果中繼屬性是 TransformGroup之類的集合，在屬性路徑中，例如 RenderTransform.Children[1].Angle，則可能需要索引器使用方式。

程式碼中的 PropertyPath

PropertyPath的程式代碼使用方式，包括如何建構 PropertyPath，記載於 PropertyPath的參考主題中。

一般而言， PropertyPath 的設計目的是使用兩個不同的建構函式，一個用於綁定使用方式和最簡單的動畫使用方式，另一個用於複雜的動畫使用方式。當物件為字串，使用 PropertyPath(Object) 簽章進行綁定使用方式。當物件為DependencyProperty，針對單步驟動畫路徑使用 PropertyPath(Object) 簽章。針對複雜的動畫使用 PropertyPath(String, Object[]) 簽章。後面這個建構函式會針對第一個參數使用語彙基元字串，並使用物件陣列來填滿語彙基元字串中的位置，以定義屬性路徑關聯性。

共用方式為