Framework 屬性中繼資料 （WPF .NET）

  • 發行項

您可以在 Windows Presentation Foundation （WPF） 架構層級設定相依性屬性的架構屬性中繼資料選項。 WPF 架構層級指定適用于 WPF 簡報 API 和可執行檔處理轉譯和資料系結時。 簡報 API 和可執行檔會查詢 FrameworkPropertyMetadata 相依性屬性的 。

重要

.NET 7 和 .NET 6 的桌面指南檔正在建置中。

必要條件

本文假設您具備相依性屬性的基本知識，而且您已閱讀 相依性屬性概觀 。 若要遵循本文中的範例，如果您熟悉可延伸的應用程式標記語言（XAML），並知道如何撰寫 WPF 應用程式，它很有説明。

Framework 屬性中繼資料類別

FrameworkPropertyMetadata 屬於下列類別：

  • 影響元素配置，特別是 、 AffectsMeasure 和 AffectsRender 中繼資料旗標的 AffectsArrange 中繼資料。 如果您的相依性屬性實作會影響視覺層面，而且您正在實作 MeasureOverride 或 ArrangeOverride 在您的類別中，您可能會設定這些旗標。 和 MeasureOverrideArrangeOverride 方法會將實作特定行為和轉譯資訊提供給版面配置系統。 當 AffectsArrange 、 AffectsMeasure 或 AffectsRender 設定 true 為 相依性屬性的中繼資料及其有效值變更時，WPF 屬性系統會起始要求，使元素的視覺效果失效以觸發重繪。

  • 影響專案父元素配置，特別是 AffectsParentArrange 和 AffectsParentMeasure 中繼資料旗標的中繼資料。 設定這些旗標的 WPF 相依性屬性範例為 FixedPage.Left 和 Paragraph.KeepWithNext 。

  • 屬性值繼承中繼資料，特別是 Inherits 和 OverridesInheritanceBehavior 中繼資料旗標。 依預設，相依性屬性不會繼承值。 OverridesInheritanceBehavior 允許繼承路徑也會移至視覺化樹狀結構，這是某些控制群組合案例的必要專案。 如需詳細資訊，請參閱 屬性值繼承 。

    注意

    屬性值內容中的「繼承」一詞專屬於相依性屬性，而且不會透過衍生型別直接關聯 Managed 程式碼類型和成員繼承。 在相依性屬性的內容中，這表示子專案可以從父元素繼承相依性屬性值。

  • 資料系結中繼資料，特別是 BindsTwoWayByDefault 和 IsNotDataBindable 中繼資料旗標。 根據預設，WPF 架構中的相依性屬性支援單向系結。 請考慮將雙向系結設定為報表狀態 和 可由使用者動作修改之屬性的預設值，例如 IsSelected 。 此外，請考慮在控制項的使用者預期屬性實作時，將雙向系結設定為預設值，例如 TextBox.Text 。 BindsTwoWayByDefault 只會影響預設系結模式。 若要編輯系結的資料流程方向，請設定 Binding.Mode 。 當資料系結沒有使用案例時，您可以使用 IsNotDataBindable 來停用資料系結。 如需資料系結的詳細資訊，請參閱 資料系結概觀 。

  • 日誌中繼資料，特別是 Journal 中繼資料旗標。 旗標的 Journal 預設值僅適用于 true 某些相依性屬性，例如 SelectedIndex 。 使用者輸入控制項應該設定屬性的 Journal 旗標，其值會保存需要儲存的使用者選取專案。 旗 Journal 標是由支援日誌的應用程式或服務讀取，包括 WPF 日誌服務。 如需儲存流覽步驟的資訊，請參閱 流覽概觀 。

FrameworkPropertyMetadata 衍生自 UIPropertyMetadata ，並實作這裡討論的旗標。 除非特別設定， FrameworkPropertyMetadata 否則旗標的預設值為 false 。

讀取 FrameworkPropertyMetadata

若要擷取相依性屬性的 DependencyProperty 中繼資料，請在識別碼上呼叫 GetMetadata 。 呼叫會 GetMetadata 傳 PropertyMetadata 回 物件。 如果您需要查詢轉換成 PropertyMetadata 的 FrameworkPropertyMetadata 架構中繼資料值。

指定 FrameworkPropertyMetadata

當您註冊相依性屬性時，您可以選擇建立和指派中繼資料給它。 您指派的中繼資料物件可以是 PropertyMetadata 或其其中一個衍生類別，例如 FrameworkPropertyMetadata 。 選擇 FrameworkPropertyMetadata 依賴 WPF 簡報 API 和可執行檔進行轉譯和資料系結的相依性屬性。 更進階的選項是衍生自 FrameworkPropertyMetadata ，以建立具有更多旗標的自訂元資料包告類別。 或者，您可以 UIPropertyMetadata 用於影響 UI 轉譯的非架構屬性。

雖然中繼資料選項通常會在新的相依性屬性註冊期間設定，但您可以在 或 AddOwner 呼叫中 OverrideMetadata 重新指定它們。 覆寫中繼資料時，請一律以屬性註冊期間所使用的相同元資料類型覆寫。

所 FrameworkPropertyMetadata 公開的屬性特性有時稱為 旗標 。 如果您要建立 FrameworkPropertyMetadata 實例，有兩種方式可以填入旗標值：

  1. 在列舉型別的 FrameworkPropertyMetadataOptions 實例上設定旗標。 FrameworkPropertyMetadataOptions 可讓您以位 OR 組合指定中繼資料旗標。 然後，使用具有 FrameworkPropertyMetadataOptions 參數的建構函式具現化 FrameworkPropertyMetadata ，並傳入您的 FrameworkPropertyMetadataOptions 實例。 若要在傳遞 FrameworkPropertyMetadataOptions 至 FrameworkPropertyMetadata 建構函式之後變更中繼資料旗標，請變更新 FrameworkPropertyMetadata 實例上的對應屬性。 例如，如果您設定 FrameworkPropertyMetadataOptions.NotDataBindable 旗標，您可以將 設定 FrameworkPropertyMetadata.IsNotDataBindable 為 false 來復原。

  2. 使用沒有參數的 FrameworkPropertyMetadataOptions 建構函式具現化 FrameworkPropertyMetadata ，然後在 上 FrameworkPropertyMetadata 設定適用的 Boolean 旗標。 在將實例與相依性屬性產生關聯 FrameworkPropertyMetadata 之前設定旗標值，否則您會取得 InvalidOperationException 。

中繼資料覆寫行為

當您覆寫架構屬性中繼資料時，已變更的中繼資料值會取代或與原始值合併：

  • PropertyChangedCallback針對 ，預設合併邏輯會保留資料表中的先前 PropertyChangedCallback 值，而且所有都會在屬性變更時叫用。 回呼順序取決於類別深度，其中階層中基類所註冊的回呼會先執行。 繼承的回呼只會執行一次，而且是由新增至中繼資料的類別所擁有。

  • DefaultValue針對 ，新的值會取代現有的預設值。 如果您未在覆寫中繼資料中指定 DefaultValue ，而且現有的 FrameworkPropertyMetadata 已 Inherits 設定旗標，則預設值會來自中繼資料中指定的最接近上階 DefaultValue 。

  • CoerceValueCallback針對 ，新的值將會取代現有的 CoerceValueCallback 值。 如果您未在覆寫中繼資料中指定 CoerceValueCallback ，則值會來自指定 CoerceValueCallback 之繼承鏈結中最接近的上階。

  • 針對 FrameworkPropertyMetadata 非繼承的旗標，您可以使用 值覆寫預設值 falsetrue 。 不過，您只能覆寫 true 具有 、 Journal 、 OverridesInheritanceBehavior 和 SubPropertiesDoNotAffectRender 值的值 Inherits 。 false

注意

預設合併邏輯是由 Merge 方法實作。 您可以在繼承相依性屬性的衍生類別中指定自訂合併邏輯，方法是在該類別中覆寫 Merge 。

另請參閱