共用方式為

PropertyPath XAML 語法

  • 發行項

更新：2007 年 11 月

PropertyPath 物件支援複雜的內嵌 XAML 語法，以設定接受 PropertyPath 型別做為其值的各種屬性。本主題說明當做繫結和動畫語法使用時的 PropertyPath 語法。

這個主題包含下列章節。

  • PropertyPath 的用途
  • 資料繫結中物件的 PropertyPath
  • 動畫目標的 PropertyPath
  • 程式碼中的 PropertyPath
  • 相關主題

PropertyPath 的用途

PropertyPath 是在幾項 Windows Presentation Foundation (WPF) 功能中使用的通用物件。雖然通用 PropertyPath 是用來傳遞屬性路徑資訊，但其在使用 PropertyPath 做為型別的每項功能區域都有不同的用途。因此，依功能來說明語法會比較實際。

WPF 主要使用 PropertyPath 描述周遊物件資料來源屬性的物件模型路徑，以及描述目標動畫的目標路徑。

部分樣式和樣板屬性 (例如 Setter.Property) 接受表面上類似 PropertyPath 的完整屬性名稱。但這不是真正的 PropertyPath，而是完整的 owner.property 字串格式用法，由 XAML 處理器加上 DependencyProperty 的型別轉換子 (Type Converter) 的組合所啟用。

資料繫結中物件的 PropertyPath

資料繫結是 WPF 的一項功能，您可以藉此繫結至任何相依性屬性的目標值。不過，這類資料繫結的來源不一定要是相依性屬性，它可以是所用資料提供者能辨識的任何屬性型別 (Property Type)。屬性路徑專供 ObjectDataProvider 使用。後者可用於由 Common Language Runtime (CLR) 物件及其屬性取得繫結來源。

請注意，XML 的資料繫結不使用 PropertyPath，因為它在 Binding 中不使用 Path。相反地，您可以使用 XPath，並將有效的 XPath 語法指定到資料的 XML 文件物件模型 (DOM)。XPath 也可以指定為字串，但這不在本文的說明範圍內；請參閱 HOW TO：使用 XMLDataProvider 和 XPath 查詢繫結至 XML 資料。

要了解資料繫結中的屬性路徑，關鍵在於您可以將繫結的目標設為個別屬性值，也可以改為繫結至接受清單或集合的目標屬性。如果繫結集合，那麼屬性路徑就應參考集合，而非個別集合項目。資料繫結引擎會自動將來源的集合與目標比對，最後產生像是使用項目陣列填入 ListBox 的行為。

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

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

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

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

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

key 必須是字典或雜湊資料表的型別索引，或是陣列的整數索引。此外，索引鍵值的型別必須可直接繫結至套用它的屬性。例如，包含字串索引鍵和字串值的雜湊資料表就能以這種方式使用，來繫結至 TextBox 的文字。或者，如果索引鍵指向集合或子索引，您可以使用此語法來繫結至目標集合屬性。否則，您就必須透過像是 <Binding Path="[key].propertyName" .../> 這樣的語法來參考特定屬性。

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

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

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

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

單一屬性、來自於 XAML 載入名稱範圍、執行階段反映

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

此語法只適用於 CLR 屬性資料繫結的來源路徑，而且必須是屬性的逐步執行路徑。propertyName 必須解析為存在於 ownerType 上之屬性的名稱。ownerType 必須是可根據執行階段反映找到的某個型別。因此，在 ownerType 的前面加上 XML 命名空間前置詞是不合法的，因為這類前置詞對反映而言沒有意義，只對編譯時期 XAML 有意義。請參閱下一節。

單一屬性，透過樣式/樣板附加或等待內容

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

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

  • 路徑在樣式或樣板中的 XAML 指定，但該樣式或樣板沒有指定的目標型別。除此之外，限定用法一般無效，因為在非樣式和非樣板的情況中，屬性會存在於執行個體上，而非型別上。

  • 屬性是附加屬性。

  • 您繫結至靜態屬性。在此情況下，ownerType 就真的是型別。

若要當做腳本目標使用，指定為 propertyName 的屬性必須是 DependencyProperty。

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

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

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

注意事項：

表面上來看，此語法類似 XPath。但繫結至 XML 資料來源的真正 XPath 運算式不會當做 Path 值使用，而應該用於互斥 (Mutually Exclusive) 的 XPath 屬性。

多個索引子

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

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

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

混合語法

上述語法可穿插使用。例如，下列範例會建立屬性路徑指向位於 ColorGrid 屬性特定 x,y 的色彩，而該屬性包含 SolidColorBrush 物件的像素格線陣列：

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

動畫目標的 PropertyPath

動畫的目標屬性必須是接受 Freezable 或基本型別 (Primitive Type) 的相依性屬性。不過，型別上的目標屬性和最後的動畫屬性可存在於不同的物件上。對動畫來說，屬性路徑是用來定義具名動畫目標物件的屬性與所要目標動畫屬性之間的關係，它會周遊屬性值中的物件-屬性關聯性。

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

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

要顯示為動畫的實值型別或屬性必須是 Freezable 型別或基本型別。開始路徑的屬性必須解析為存在於所指定 TargetName 型別上的相依性屬性名稱。

為支援複製來將已凍結的 Freezable 顯示為動畫，TargetName 指定的物件必須是 FrameworkElement 或 FrameworkContentElement 衍生類別 (Derived Class)。

目標物件上的單一屬性

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

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

間接屬性目標設定

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

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

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

由於套用樣式和樣板，因此需要間接設定動畫的目標。要設定動畫的目標，您需要目標物件上的 TargetName，而且該名稱是以 x:Name 或 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 處理器可存取的型別。大多數應用程式的預設 XML 命名空間都對應至 https://schemas.microsoft.com/winfx/2006/xaml/presentation 命名空間，因此通常只有自訂型別或不在該命名空間的型別才需要前置詞。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) 簽章可用於其中物件是字串的繫結。PropertyPath(Object) 簽章也可用於其中物件是 DependencyProperty 的單一步驟動畫路徑。PropertyPath(String, array<Object[]) 簽章則可用於複雜動畫。後面這個建構函式會在第一個參數使用語彙基元字串，並使用物件陣列填滿語彙基元字串中的位置，以定義屬性路徑關聯性。

請參閱

概念

資料繫結概觀

腳本概觀

參考

PropertyPath