DependencyProperty 類別

定義

命名空間:

Microsoft.UI.Xaml

表示向相依性屬性系統註冊的相依性屬性。 相依性屬性支援值運算式、資料系結、動畫和屬性變更通知。 如需 DependencyProperty 值如何做為相依性屬性識別碼的詳細資訊，請參閱 相依性屬性概觀。

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

範例

此範例示範基本用法，其中 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); }
    }
}

此處未顯示 Visual C++ 元件延伸模組 (C++/CX) 範例，因為它必須以與 Microsoft .NET 範例完全不同的方式加以考慮，而且牽涉到數個不同的程式碼檔案。 請參閱 自訂相依性屬性中的範例。

備註

相依性屬性概念會在相 依性屬性概觀主題中詳細說明。

的 DependencyProperty 實例通常會在檔中參考為相依性屬性識別碼。 識別碼提供方法來參考已註冊至特定 DependencyObject 擁有者類型的相依性屬性。 當擁有者類型註冊屬性時，擁有者類型會將 DependencyProperty 實例公開為識別碼，這是擁有者類別的靜態成員。

擁有者 DependencyObject 會提供相依性屬性的屬性存放區。 在程式碼中使用相依性屬性時，您可以使用 DependencyProperty 識別碼作為呼叫屬性系統方法的輸入，例如 SetValue。 不過，在大部分情況下，取得或設定相依性屬性會比較簡單，方法是取得或設定 包裝函式;此概念會在 相依性屬性概觀中說明。

DependencyProperty 支援 XAML 屬性語法的原生轉換來填滿值，當 Setter 指定其 屬性值 時會使用。 此轉換會針對輸入字串使用 ownerTypeName**.**propertyName 表單。

注意

也可用來依名稱指定屬性的相關語法，而且特定資料需要動畫 API 是 屬性路徑語法。 屬性路徑可用來參考具有屬性的類別結構，以及該屬性的值。 如需詳細資訊，請參閱 Property-path 語法。

提示

如果您是使用 Microsoft .NET 語言進行程式設計， (C# 或 Microsoft Visual Basic) ， TypeName 類型會專案為 System.Type。 使用 C# 進行程式設計時，通常會使用 typeof 運算子來取得 類型的 System.Type 參考。 在 Microsoft Visual Basic 中，使用 GetType 。 如果您使用 Visual C++ 元件延伸模組 (C++/CX) ) ，您必須在其中建立 TypeName 協助程式結構，您可以使用 typeid 元件延伸模組。

Windows 執行階段會在DependencyObject上實作具有 DependencyProperty 識別碼和屬性儲存體的 XAML 附加屬性語言功能。 如需詳細資訊，請參閱附加屬性概觀。

自訂相依性屬性

如果您想要自訂類型上的屬性支援值運算式、資料系結或動畫，您應該遵循下列指導方針，使用相依性屬性來備份屬性：

• 使用 Register 方法註冊相依性屬性，這會傳回 DependencyProperty 。 這是您的相依性屬性識別碼。 您應該將此物件公開為類別中可存取的靜態唯讀屬性。 依照慣例，此 DependencyProperty 識別碼欄位的名稱應該以 「Property」 結尾。
• 在註冊期間，您可以為 屬性提供 PropertyMetadata ，以進一步定義屬性的行為。
• 提供 get 屬性的 和 set 存取子：這些是屬性包裝函式，而且會簡化所有呼叫端對屬性的存取。

相依性屬性名稱的 XAML 參考

一些通常會在 XAML 標記中設定的屬性會使用 DependencyProperty 作為其值。 例如，您在 XAML 中設定 Setter.Property 。 若要在 XAML 中設定這類屬性，您可以將相依性屬性的名稱指定為屬性值。

針對Setter.Property，您參考相依性屬性名稱的來源類型已由Setter存在之 Style的TargetType範圍。 對於 TargetType 物件的相依性屬性，您可以使用相依性屬性的簡單名稱來指定 Setter.Property 值。 例如，如果您有以Slider為目標的Style，而且您想要設定 Orientation 屬性的樣式，則 Property屬性值只能是 「Orientation」。 只要相依性屬性來自目標型別更深入繼承中的類別，簡單名稱也能運作。 例如，若要在Slider的Style 中設定Visibility 屬性的樣式，「Visibility」 的Property屬性值將會正常運作。 在此情況下 ，Visibility 是由 UIElement所定義，但繼承至 Slider。

您也可以使用 Setter.Property 來參考附加的屬性名稱。 針對屬性值，請使用 AttachedPropertyOwner.AttachedPropertyName格式，就像您在 XAML 中使用該附加屬性設定為屬性一樣。 例如，以下是Setter，其會在Style中設定附加屬性AutomationProperties.ItemType：<Setter Property="AutomationProperties.ItemType" Value="Navigation Button"/>

注意

相依性屬性的名稱不是靜態屬性識別碼的名稱 DependencyProperty 。 這是屬性註冊的名稱字串，以及 Microsoft IntelliSense 和參考檔公開時，Windows 執行階段程式設計中該屬性的典型使用名稱。 換句話說，您不希望在 XAML 中為 Setter.Property 指定的字串以 「Property」 結尾 (，但相依性屬性實際上確實包含尾碼 「Property」 ) 。

在程式碼中使用 DependencyProperty (相依性屬性識別碼)

有數種方法是使用值做為輸入參數之Windows 執行階段屬性系統的 DependencyProperty 公用程式方法。 其中包括：

• DependencyObject.ClearValue
• DependencyObject.GetAnimationBaseValue
• DependencyObject.GetValue
• DependencyObject.ReadLocalValue
• DependencyObject.SetValue
• DependencyPropertyChangedEventArgs.Property
• Setter (DependencyProperty，Object) 建構函式

屬性

UnsetValue

指定屬性系統所使用的靜態值，而不是 null 表示屬性存在，但未由屬性系統或任何應用程式程式碼設定其值。

方法

GetMetadata(TypeName)	擷取相依性屬性的屬性中繼資料值，如註冊至類型。 您要從 中指定資訊做為類型參考的類型。
Register(String, TypeName, TypeName, PropertyMetadata)	使用屬性的指定屬性名稱、屬性類型、擁有者類型和屬性中繼資料註冊相依性屬性。 定義或初始化將擁有已註冊相依性屬性的 DependencyObject 衍生類別時，請使用這個方法。
RegisterAttached(String, TypeName, TypeName, PropertyMetadata)	使用屬性的指定屬性名稱、屬性類型、擁有者類型和屬性中繼資料註冊附加的相依性屬性。

另請參閱

• 自訂相依性屬性
• 相依性屬性概觀
• 自訂附加屬性
• XAML 使用者和自訂控制項範例