語言

DependencyProperty 類別

定義

命名空間:
Microsoft.UI.Xaml
編輯

代表一個在依賴屬性系統中註冊的相依屬性。 相依屬性提供值表達式、資料綁定、動畫及屬性變更通知的支援。 欲了解更多 DependencyProperty 值如何作為相依屬性的識別碼，請參閱 Dependency properties 概述。

public ref class DependencyProperty sealed
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class DependencyProperty final
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class DependencyProperty
Public NotInheritable Class DependencyProperty
繼承
Object Platform::Object IInspectable DependencyProperty
屬性
ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

範例

此範例展示了一個基本用法，即 a DependencyProperty 被建立為類別的公開靜態成員。 這是透過呼叫 Register ，並將回傳值儲存為類別成員來完成。 更多範例請參見 自訂相依屬性。

public class Fish : Control
{
    public static readonly DependencyProperty SpeciesProperty =
    DependencyProperty.Register(
    "Species",
    typeof(String),
    typeof(Fish), null
    );
    public string Species
    {
        get { return (string)GetValue(SpeciesProperty); }
        set { SetValue(SpeciesProperty, (string)value); }
    }
}

備註

依賴性質概念在「 依賴性質概覽」主題中有詳細介紹。

的 DependencyProperty 實例常在文件中被引用為相依屬性識別碼。 識別碼提供了一種方式，可以指稱註冊給特定 DependencyObject 擁有者類型的相依屬性。 當擁有者類型註冊該屬性時，所有者類型會 DependencyProperty 將實例暴露為識別碼，該識別碼是所有者類別的靜態成員。

擁有者 DependencyObject 提供相依屬性的屬性儲存。 在程式碼中處理相依屬性時，你可以用 DependencyProperty 識別碼作為呼叫屬性系統方法（如 SetValue）的輸入。 然而，在大多數情況下，取得或設定相依屬性會透過取得或設定 包裝器來簡單;這個概念在依賴 性質概述中有說明。

DependencyProperty 支援原生轉換至 XAML 屬性語法以填入值，當 Setter 指定其 屬性 值時會使用此方法。 此轉換使用 ownerTypeName。輸入字串的 propertyName 形式。

Note

一個相關語法也可用於指定屬性名稱，且某些資料與動畫 API 要求，稱為 屬性路徑語法。 屬性路徑可以用來參考具有屬性的類別結構及其屬性的值。 如需詳細資訊，請參閱 屬性路徑語法。

Tip

如果你使用Microsoft .NET語言（C#）來編程，TypeName 類型會以 System.Type 形式投影。 使用 C# 程式設計時，常用 typeof 運算子取得 System.Type 的參考。

如果你用的是 C++/WinRT ，可以用 winrt::xaml_typename<T>() 輔助函式來建立 TypeName 物件。 更多細節及程式碼範例請參見 winrt：：xaml_typename 函式範本 。

Windows 執行階段 實作了 XAML 附加屬性語言功能，並透過DependencyProperty識別碼與屬性儲存在 DependencyObject 上。 如需詳細資訊，請參閱 附加屬性概觀。

自訂相依性屬性

如果你希望自訂型態的屬性能支援值運算式、資料綁定或動畫，你應該依照以下指引，為屬性提供相依屬性：

  • 使用 Register 方法註冊相依屬性，該方法會回傳一個 DependencyProperty。 這是你的相依物業識別碼。 你應該在類別中將這個物件暴露為可存取的靜態唯讀屬性。 依慣例，此 DependencyProperty 識別碼欄位名稱應以「Property」結尾。
  • 註冊時，你可以提供該物業的 PropertyMetadata ，進一步定義該物件的行為。
  • 物業的配件getset與配件：這些是物業包裝，能讓所有來電者更容易進入您的房產。

XAML 對相依屬性名稱的引用

一些通常在 XAML 標記中設定的屬性會作為 DependencyProperty 其值。 舉例來說，你在 XAML 裡設定 Setter.Property 。 要在 XAML 中設定此類屬性，需指定相依屬性的名稱作為屬性值。

對於 Setter.Property，你參考的相依屬性名稱的類型，已經由該 Setter 存在的 Style（TargetType）範圍所設定。 對於 TargetType 物件的相依屬性，你可以用相依屬性的簡單名稱來指定 Setter.Property 值。 舉例來說，如果你有一個針對滑桿的 Style，想要為 Orientation 屬性做樣式，Property 屬性的值可以直接是「Orientation」。 只要依賴性質來自目標型別更深層繼承的類別，簡單名稱也可行。 例如，若要在滑桿的樣式中為 Visibility 屬性做樣式，屬性值為「Visibility」即可使用。 在這種情況下， 可見性 是由 UIElement 定義，但繼承了 Slider。

你也可以使用 Setter.Property 來參考附加的屬性名稱。 屬性值請使用 表單 AttachedPropertyOwner.AttachedPropertyName，就像在 XAML 中設定該附加屬性為屬性一樣。 舉例來說，這裡有一個設定器，將附加屬性 AutomationProperties.ItemType 設定為 Style：<Setter Property="AutomationProperties.ItemType" Value="Navigation Button"/>

Note

相依屬性的名稱並非靜態屬性識別碼的名稱 DependencyProperty 。 它是該屬性註冊的名稱字串，也是該屬性在 Windows 執行階段 程式設計中，Microsoft IntelliSense 和參考文件中通常使用的名稱。 換句話說，你不希望你在 XAML 中指定給 Setter.Property 的字串以「Property」結尾（除非少數少數情況下，依賴屬性確實包含「Property」這個字尾）。

在程式碼中使用 DependencyProperty （依賴屬性識別碼）

有幾種 Windows 執行階段 屬性系統的實用方法，會將DependencyProperty值作為輸入參數。 這些包括：

屬性

名稱 Description
UnsetValue

指定一個靜態值，供屬性系統使用，而非 null 表示屬性存在，但其值並非由屬性系統或任何應用程式程式碼設定。

方法

名稱 Description
GetMetadata(TypeName)

取得相依屬性的屬性元資料值，並註冊到某個類型。 你可以指定你想要的資訊類型作為類型參考。
Register(String, TypeName, TypeName, PropertyMetadata)

註冊一個相依屬性，並包含指定的屬性名稱、屬性類型、擁有者類型及屬性元資料。 在定義或初始化一個擁有註冊相依屬性的 DependencyObject 衍生類別時，請使用此方法。
RegisterAttached(String, TypeName, TypeName, PropertyMetadata)

註冊附加的相依屬性，並包含指定的屬性名稱、屬性類型、所有者類型及屬性元資料。

適用於

另請參閱