自訂控制元件的設計時間屬性 (Windows Forms .NET)
本文將教導您如何處理Visual Studio中 Windows Forms Visual Designer 中控件的屬性。
每個控制件都會從基類 System.Windows.Forms.Control繼承許多屬性,例如:
建立控制時,您可以定義新的屬性,並控制它們在設計工具中的顯示方式。
定義屬性
任何具有 控件所定義 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)以來的變更。