如何建立使用者控制項 (Windows Forms .NET)

發行項
09/26/2024

本文將教導您如何將使用者控制項新增至專案，然後將該使用者控制項新增至 form。您將建立既具有視覺吸引力又能運作，且可重複使用的使用者控制項。新的控制項會將 TextBox 控制項 (部分機器翻譯) 與 Button 控制項 (部分機器翻譯) 組成群組。當使用者選取該按鈕時，會清除文字輸入框中的文字。如需使用者控制項的詳細資訊，請參閱使用者控制項概觀 (部分機器翻譯)。

將使用者控制項新增至專案

在 Visual Studio 中開啟 Windows Forms 專案之後，請使用 Visual Studio 範本來建立使用者控制項：

在 Visual Studio 中，尋找 [專案總管] 視窗。以滑鼠右鍵按兩下專案，然後選擇 [新增]>[使用者控制項 (Windows Forms)]。
將控制項的 [名稱] 設定為 [ClearableTextBox]，然後按下 [新增]。

建立使用者控制項之後，Visual Studio 會開啟設計工具：

Visual Studio 中的使用者控制項設計工具 (適用於 Windows Forms)

設計可清除的文字輸入框

使用者控制項是由「組成控制項」所組成，這是您在設計介面上建立的控制項 (部分機器翻譯)，就像您設計表單的方式一樣。請遵循下列步驟來新增及設定使用者控制項及其組成控制項：

在設計工具開啟的情況下，使用者控制項設計介面應該是選取的物件。如果不是，請按一下設計介面加以選取。在 [屬性] 視窗中設定下列屬性：

屬性值

MinimumSize 84, 53

大小 191, 53
新增 Label 控制項。設定下列屬性：

屬性值

名稱 lblTitle

Location 3, 5
新增 TextBox 控制項。設定下列屬性：

屬性值

名稱 txtValue

錨點 Top, Left, Right

Location 3, 23

大小 148, 23
新增 Button 控制項。設定下列屬性：

屬性值

名稱 btnClear

錨點 Top, Right

Location 157, 23

大小 31, 23

Text ↻

控制項看起來應該像下列影像：
按 F7 以針對 ClearableTextBox 類別開啟程式碼編輯器。

屬性	值
MinimumSize	`84, 53`
大小	`191, 53`

屬性	值
名稱	`lblTitle`
Location	`3, 5`

屬性	值
名稱	`txtValue`
錨點	`Top, Left, Right`
Location	`3, 23`
大小	`148, 23`

屬性	值
名稱	`btnClear`
錨點	`Top, Right`
Location	`157, 23`
大小	`31, 23`
Text	`↻`

進行下列程式碼變更：

在程式碼檔案頂端，匯入 System.ComponentModel 命名空間。
將 DefaultEvent 屬性加入該類別。這個屬性會設定當在設計工具中按兩下控制項時，取用者會產生哪個事件。取用者是宣告及使用此控制項的物件。如需有關屬性的詳細資訊，請參閱屬性 (C#) 或屬性概觀 (Visual Basic)。
```
using System.ComponentModel;

namespace UserControlProject
{
    [DefaultEvent(nameof(TextChanged))]
    public partial class ClearableTextBox : UserControl
```
```
Imports System.ComponentModel

<DefaultEvent("TextChanged")>
Public Class ClearableTextBox
```

新增事件處理常式，將 TextBox.TextChanged 事件 (英文) 轉送給取用者：

[Browsable(true)]
public new event EventHandler? TextChanged
{
    add => txtValue.TextChanged += value;
    remove => txtValue.TextChanged -= value;
}

<Browsable(True)>
Public Shadows Custom Event TextChanged As EventHandler
    AddHandler(value As EventHandler)
        AddHandler txtValue.TextChanged, value
    End AddHandler
    RemoveHandler(value As EventHandler)
        RemoveHandler txtValue.TextChanged, value
    End RemoveHandler
    RaiseEvent(sender As Object, e As EventArgs)

    End RaiseEvent
End Event

請注意，事件上已宣告 Browsable 屬性。當 Browsable 套用至事件或屬性時，其會控制在設計工具中選取控制項時，項目在 [屬性] 視窗中是否可見。在此案例中，true 會當做參數傳遞至屬性，指出事件應該可見。

新增名為 Text 且會將 TextBox.Text 屬性 (英文) 轉送給取用者的字串屬性：

[Browsable(true)]
public new string Text
{
    get => txtValue.Text;
    set => txtValue.Text = value;
}

<Browsable(True)>
Public Shadows Property Text() As String
    Get
        Return txtValue.Text
    End Get
    Set(value As String)
        txtValue.Text = value
    End Set
End Property

新增名為 Title 且會將 Label.Text 屬性 (英文) 轉送給取用者的字串屬性：

[Browsable(true)]
public string Title
{
    get => lblTitle.Text;
    set => lblTitle.Text = value;
}

<Browsable(True)>
Public Property Title() As String
    Get
        Return lblTitle.Text
    End Get
    Set(value As String)
        lblTitle.Text = value
    End Set
End Property

切換回 ClearableTextBox 設計工具，然後按兩下 btnClear 控制項以產生 Click 事件的處理常式。為處理常式新增下列程式碼，以清除 txtValue 文字輸入框：
```
private void btnClear_Click(object sender, EventArgs e) =>
    Text = "";
```
```
Private Sub btnClear_Click(sender As Object, e As EventArgs)
    txtValue.Text = ""
End Sub
```
最後，以滑鼠右鍵按一下 [方案總管] 視窗中的專案，然後選取 [組建] 以組建專案。不應該有任何錯誤，而且組建完成之後，ClearableTextBox 控制項會出現在工具箱中以供使用。

下一個步驟是在表單中使用控制項。

範例應用程式

如果您在上一節中建立新專案，則您會有名為 Form1 的空白表單，否則請建立新的表單。

在 [方案總管] 中，按兩下該表單以開啟設計工具。應該會選取該表單的設計介面。
將該表單的 Size 屬性設定為 432, 315。
開啟 [工具箱] 視窗，然後按兩下 [ClearableTextBox] 控制項。此控制項應該列在以專案名稱命名的區段底下。
再次按兩下 [ClearableTextBox] 控制項，以產生第二個控制項。
返回設計工具，並分開控制項，以便您可以看到兩個控制項。
選取一個控制項並設定下列屬性：

屬性值

名稱 ctlFirstName

Location 12, 12

大小 191, 53

標題 First Name
選取另一個控制項並設定下列屬性：

屬性值

名稱 ctlLastName

Location 12, 71

大小 191, 53

標題 Last Name
返回 [工具箱] 視窗，將 label 控制項新增至表單，並設定下列屬性：

屬性值

名稱 lblFullName

Location 12, 252
接下來，您必須為兩個使用者控制項產生事件處理常式。在設計工具中，按兩下 ctlFirstName 控制項。此動作會為 TextChanged 事件產生事件處理常式，並開啟程式碼編輯器。
切換回設計工具，然後按兩下 ctlLastName 控制項以產生第二個事件處理常式。
切換回設計工具，然後按兩下表單的標題列。這個動作會為 Load 事件產生事件處理常式。

屬性	值
名稱	`ctlFirstName`
Location	`12, 12`
大小	`191, 53`
標題	`First Name`

屬性	值
名稱	`ctlLastName`
Location	`12, 71`
大小	`191, 53`
標題	`Last Name`

屬性	值
名稱	`lblFullName`
Location	`12, 252`

在程式碼編輯器中，新增名為 UpdateNameLabel 的方法。此方法會合併這兩個名稱來建立訊息，並將訊息指派給 lblFullName 控制項。

private void UpdateNameLabel()
{
    if (string.IsNullOrWhiteSpace(ctlFirstName.Text) || string.IsNullOrWhiteSpace(ctlLastName.Text))
        lblFullName.Text = "Please fill out both the first name and the last name.";
    else
        lblFullName.Text = $"Hello {ctlFirstName.Text} {ctlLastName.Text}, I hope you're having a good day.";
}

Private Sub UpdateNameLabel()
    If String.IsNullOrWhiteSpace(ctlFirstName.Text) Or String.IsNullOrWhiteSpace(ctlLastName.Text) Then
        lblFullName.Text = "Please fill out both the first name and the last name."
    Else
        lblFullName.Text = $"Hello {ctlFirstName.Text} {ctlLastName.Text}, I hope you're having a good day."
    End If
End Sub

針對這兩個 TextChanged 事件處理常式，呼叫 UpdateNameLabel 方法：

private void ctlFirstName_TextChanged(object sender, EventArgs e) =>
    UpdateNameLabel();

private void ctlLastName_TextChanged(object sender, EventArgs e) =>
    UpdateNameLabel();

Private Sub ctlFirstName_TextChanged(sender As Object, e As EventArgs) Handles ctlFirstName.TextChanged
    UpdateNameLabel()
End Sub

Private Sub ctlLastName_TextChanged(sender As Object, e As EventArgs) Handles ctlLastName.TextChanged
    UpdateNameLabel()
End Sub

最後，從表單的 Load 事件呼叫 UpdateNameLabel 方法：

private void Form1_Load(object sender, EventArgs e) =>
    UpdateNameLabel();

Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
    UpdateNameLabel()
End Sub

執行專案並輸入名稱與姓氏：

系統會從使用者控制項建立具有兩個文字輸入框與一個標籤的 Windows Forms 應用程式。

請嘗試按 ↻button 以重設其中一個文字輸入框。

共用方式為

如何建立使用者控制項 (Windows Forms .NET)

將使用者控制項新增至專案

設計可清除的文字輸入框

範例應用程式

其他資源