自訂控制元件的設計時間屬性 （Windows Forms .NET）

  • 發行項

本文將教導您如何處理Visual Studio中 Windows Forms Visual Designer 中控件的屬性。

每個控制件都會從基類 System.Windows.Forms.Control繼承許多屬性，例如：

建立控制時，您可以定義新的屬性，並控制它們在設計工具中的顯示方式。

重要

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

定義屬性

任何具有 控件所定義 get 存取子的公用屬性，都會在 Visual Studio [屬性 ] 視窗中自動顯示。 如果屬性也定義 set 存取子，則可以在 [屬性] 視窗中變更屬性 。 不過，可以藉由套用 BrowsableAttribute，從 [屬性] 視窗明確顯示或隱藏屬性。 這個屬性會採用單一布爾值參數來指出它是否顯示。 如需屬性的詳細資訊，請參閱屬性 （C#） 或屬性概觀 （Visual Basic）。

[Browsable(false)]
public bool IsSelected { get; set; }

<Browsable(False)>
Public Property IsSelected As Boolean

[注意]無法隱含轉換成字串的複雜屬性需要類型轉換器。

串行化屬性

控件上設定的屬性會串行化為設計工具的程式代碼後置檔案。 當屬性的值設定為預設值以外的值時，就會發生這種情況。

當設計工具偵測到屬性的變更時，它會評估控件的所有屬性，並串行化其值不符合屬性預設值的任何屬性。 屬性的值會串行化為設計工具的程式代碼隱藏檔案。 預設值可協助設計工具判斷應該串行化哪些屬性值。

預設值

當屬性套用 DefaultValueAttribute 屬性或屬性的 類別包含屬性特定 Reset 和 ShouldSerialize 方法時，屬性會被視為具有預設值。 如需屬性的詳細資訊，請參閱屬性 （C#） 或屬性概觀 （Visual Basic）。

藉由設定預設值，您可以啟用下列專案：

  • 屬性會在 [屬性] 視窗中提供視覺指示，如果已從其預設值修改。
  • 使用者可以以滑鼠右鍵按下屬性，然後選擇 [重設 ] 將屬性還原為其預設值。
  • 設計工具會產生更有效率的程序代碼。

如果屬性使用簡單類型，例如基本類型，則可以將 套用 DefaultValueAttribute 至 屬性來設定預設值。 不過，具有此屬性的屬性不會自動以該指派的值開頭。 您必須將屬性的備份欄位設定為相同的預設值。 您可以在宣告或類別的建構函式上設定 屬性。

當屬性是複雜類型，或您想要控制設計工具的重設和串行化行為時，請在 類別上定義 Reset<PropertyName> 和 ShouldSerialize<PropertyName> 方法。 例如，如果控制項定義 Age 屬性，則方法會命名 ResetAge 為 和 ShouldSerializeAge。

重要

將 套用 DefaultValueAttribute 至 屬性，或同時提供 Reset<PropertyName> 和 ShouldSerialize<PropertyName> 方法。 請勿同時使用兩者。

屬性可以透過 [屬性] 視窗，以滑鼠右鍵按下屬性名稱，然後選取 [重設]，以「重設」預設值。

屬性方格中的 [重設] 操作功能表項。

啟用 [屬性>] 右鍵>[重設操作功能表] 選項的可用性：

  • 屬性已 DefaultValueAttribute 套用 屬性，而 屬性的值不符合屬性的值。
  • 屬性的 類別會 Reset<PropertyName> 定義不含 ShouldSerialize<PropertyName>的方法。
  • 屬性的 類別會 Reset<PropertyName> 定義方法，並 ShouldSerialize<PropertyName> 傳回 true。

DefaultValueAttribute

如果屬性的值不符合 所提供的DefaultValueAttribute值，則會將 屬性視為已變更，而且可以透過 [屬性] 視窗重設。

重要

此屬性不應該用於具有對應 Reset<PropertyName> 和 ShouldSerialize<PropertyName> 方法的屬性上。

下列程式代碼會宣告兩個屬性、預設值為的 North 列舉，以及預設值為10的整數。

[DefaultValue(typeof(Directions), "North")]
public Directions PointerDirection { get; set; } = Directions.North;

[DefaultValue(10)]
public int DistanceInFeet { get; set; } = 10;

<DefaultValue(GetType(Directions), "North")>
Public Property PointerDirection As Directions = Directions.North

<DefaultValue(10)>
Public Property DistanceInFeet As Integer = 10

Reset 和 ShouldSerialize

如先前所述， Reset<PropertyName> 和 ShouldSerialize<PropertyName> 方法不僅提供機會來引導屬性的重設行為，還能在判斷值是否已變更，而且應該串行化為設計工具的程序代碼後置檔案。 這兩種方法一起運作，您不應該定義一個沒有另一個方法。

重要

Reset<PropertyName>不應該為具有DefaultValueAttribute的屬性建立和 ShouldSerialize<PropertyName> 方法。

定義時 Reset<PropertyName> ，[ 屬性 ] 視窗會顯示該屬性的 [ 重設 ] 操作功能表選項。 選取 [重設] 時，Reset<PropertyName>會叫用 方法。 方法所ShouldSerialize<PropertyName>傳回的內容會啟用或停用 [重設] 操作功能表選項。 傳回 true時ShouldSerialize<PropertyName>，表示屬性已從預設值變更，而且應該串行化為程序代碼後置檔案，並啟用 [重設] 操作功能表選項。 傳回時 false ，會停用 [ 重 設] 操作功能表選項，而程式代碼後置已移除屬性集程序代碼。

提示

這兩種方法都可以和 應該使用私人範圍來定義，這樣它們就不會構成控件的公用 API。

下列代碼段會宣告名為 Direction的屬性。 此屬性的設計工具行為是由 ResetDirection 和 ShouldSerializeDirection 方法所控制。

public Directions Direction { get; set; } = Directions.None;

private void ResetDirection() =>
    Direction = Directions.None;

private bool ShouldSerializeDirection() =>
    Direction != Directions.None;

Public Property Direction As Directions = Directions.None

Private Sub ResetDirection()
    Direction = Directions.None
End Sub

Private Function ShouldSerializeDirection() As Boolean
    Return Direction <> Directions.None
End Function

類型轉換器

雖然類型轉換器通常會將某個類型轉換成另一個類型，但它們也會提供屬性方格和其他設計時間控件的字串對值轉換。 字串對值轉換可讓複雜屬性在這些設計時間控件中表示。

大部分的內建數據類型（數位、列舉和其他類型）都有預設類型轉換器，可提供字串對值轉換，並執行驗證檢查。 默認類型轉換器位於 命名空間中 System.ComponentModel ，並以轉換的類型命名。 轉換器類型名稱使用下列格式： {type name}Converter。 例如、 StringConverterTimeSpanConverter與 Int32Converter。

類型轉換器在設計時間與 [ 屬性 ] 視窗廣泛使用。 型別轉換器可以使用 套用至屬性或型別 TypeConverterAttribute。

[ 屬性 ] 視窗會使用轉換器，在 屬性上宣告 時 TypeConverterAttribute ，將 屬性顯示為字元串值。 TypeConverterAttribute在型別上宣告 時，[屬性] 視窗會在該型別的每個屬性上使用轉換器。 類型轉換器也有助於串行化設計工具程式代碼後置檔案中的屬性值。

類型編輯器

當屬性的類型為內建或已知類型時，[ 屬性 ] 視窗會自動使用屬性的類型編輯器。 例如，布爾值會編輯為具有 True 和 False 值的下拉式方塊， DateTime 而類型會使用行事歷下拉式清單。

重要

自 .NET Framework 之後，自定義類型編輯器已變更。 如需詳細資訊，請參閱 設計工具自 .NET Framework（Windows Forms .NET）以來的變更。