附加屬性

發行項
05/14/2024

.NET 多平臺應用程式 UI （.NET MAUI）附加屬性可讓物件為其本身類別未定義的屬性指派值。例如，子專案可以使用附加屬性，通知其父元素如何在使用者介面中呈現它們。配置 Grid 可藉由設定 Grid.Row 和附加屬性來指定子系的數據列和數據 Grid.Column 行。 Grid.Row 和 Grid.Column 是附加屬性，因為它們是在屬於的 Grid子系項目上設定，而不是在本身上 Grid 設定。

在下列案例中，可系結屬性應實作為附加屬性：

當需要有屬性設定機制可供定義類別以外的類別使用時。
當類別代表需要與其他類別輕鬆整合的服務時。

如需可系結屬性的詳細資訊，請參閱可系結屬性。

建立附加屬性

建立附加屬性的程式如下：

使用其中CreateAttached一個方法多載建立BindableProperty實例。
提供 static GetPropertyName 和 SetPropertyName 方法做為附加屬性的存取子。

建立屬性

建立附加屬性以用於其他型別時，建立屬性的類別不必衍生自 BindableObject。不過， 存取子的目標 屬性應該是或衍生自 BindableObject。如需目標屬性的詳細資訊，請參閱基本系結。

您可以藉由宣告 public static readonly 類型的 BindableProperty屬性來建立附加屬性。可系結屬性應該設定為其中一個方法多載的 BindableProperty.CreateAttached 傳回值。宣告應該位於擁有類別的主體內，但在任何成員定義之外。

重要

附加屬性的命名慣例是附加屬性標識碼必須符合方法中指定的 CreateAttached 屬性名稱，並附加「Property」。

下列程式代碼顯示附加屬性的範例：

public class MyControl
{
    public static readonly BindableProperty HasShadowProperty =
        BindableProperty.CreateAttached("HasShadow", typeof(bool), typeof(MyControl), false);
}

這會建立名為 HasShadowProperty的附加屬性，類型 bool為。屬性是由 MyControl 類別所擁有，且預設值為 false。在這裡情況下，擁有權表示屬性會使用格式 Type.Property在 XAML 中存取，例如 MyControl.HasShadow。

如需建立可系結屬性的詳細資訊，包括可在建立期間指定的參數，請參閱建立可系結屬性。

建立存取子

靜態 GetPropertyName 和 SetPropertyName 方法必須是附加屬性的存取子，否則屬性系統將無法使用附加屬性。 GetPropertyName 存取子應該符合下列簽章：

public static valueType GetPropertyName(BindableObject target)

GetPropertyName 存取子應該會傳回附加屬性對應BindableProperty欄位中所包含的值。呼叫方法、傳入要取得值的可系結屬性標識符，然後將產生的值轉換成所需的類型，即可達成 GetValue 此目的。

SetPropertyName 存取子應該符合下列簽章：

public static void SetPropertyName(BindableObject target, valueType value)

SetPropertyName 存取子應該設定附加屬性之對應BindableProperty欄位的值。呼叫方法、傳入要設定值的可系結屬性標識碼，以及要設定的值，即可達成 SetValue 此目的。

針對這兩個 存取子，目標 對象應該是或衍生自 BindableObject。如需目標對象的詳細資訊，請參閱基本系結。

下列程式代碼範例顯示附加屬性的 HasShadow 存取子：

public class MyControl
{
    public static bool GetHasShadow(BindableObject view)
    {
        return (bool)view.GetValue (HasShadowProperty);
    }

    public static void SetHasShadow(BindableObject view, bool value)
    {
        view.SetValue(HasShadowProperty, value);
    }  
}

取用附加屬性

建立附加屬性之後，就可以從 XAML 或程式碼取用它。在 XAML 中，這是藉由宣告具有前置詞的命名空間、指出 Common Language Runtime （CLR）命名空間名稱的命名空間宣告，以及選擇性地宣告元件名稱來達成此目的。如需詳細資訊，請參閱 XAML 命名空間。

下列範例示範包含附加屬性之自定義類型的 XAML 命名空間，其定義於與參考自定義類型的應用程式程式碼相同的元件內：

<ContentPage ... xmlns:local="clr-namespace:ShadowDemo" ...>
  ...
</ContentPage>

然後在特定控制項上設定附加屬性時使用命名空間宣告，如下列 XAML 所示：

<Label Text="Label with shadow" local:MyControl.HasShadow="true" />

對等的 C# 程式碼會顯示在以下程式碼範例中：

Label label = new Label { Text = "Label with shadow" };
MyControl.SetHasShadow (label, true);

使用具有樣式的附加屬性

附加屬性也可以透過樣式新增至控件。下列 XAML 程式代碼範例顯示使用附加屬性之控制件的HasShadow明確樣式Label：

<Style x:Key="ShadowStyle" TargetType="Label">
  <Style.Setters>
    <Setter Property="local:MyControl.HasShadow" Value="true" />
  </Style.Setters>
</Style>

使用 StaticResource 標記延伸將其 Style 屬性設為 Style 執行個體，Style 即可套用至 Label，如下列程式碼範例所示：

<Label Text="Label with shadow" Style="{StaticResource ShadowStyle}" />

如需樣式的詳細資訊，請參閱樣式。

進階案例

建立附加屬性時，有一些選擇性參數可以設定為啟用進階附加屬性案例。這包括偵測屬性變更、驗證屬性值，以及強制屬性值。如需詳細資訊，請參閱進階案例。

共用方式為