如何建立使用者控制件 （Windows Forms .NET）

本文將教導您如何將使用者控件新增至專案，然後將該使用者控件新增至表單。 您將建立可重複使用的使用者控件，既具有視覺吸引力，又能運作。 新的控制項會使用 TextBoxButton 控制項來群元件。 當使用者選取按鈕時，會清除文字文字。 如需使用者控件的詳細資訊，請參閱 使用者控件概觀。

重要

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

將使用者控件新增至專案

在 Visual Studio 中開啟 Windows Form項目之後，請使用 Visual Studio 範本來建立使用者控件：

1. 在 Visual Studio 中，尋找 [ 項目總管 ] 視窗。 以滑鼠右鍵按兩下項目，然後選擇 [新增>使用者控件] [Windows Forms]。

   

2. 將控件的 [名稱] 設定為 [可TextBox清除]，然後按 [新增]。

   

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

設計可清除的文字框

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

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

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

2. Label新增控制件。 設定下列屬性：

   屬性	值
   名稱	lblTitle
   Location	3, 5

3. TextBox新增控制件。 設定下列屬性：

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

4. Button新增控制件。 設定下列屬性：

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

   控制器看起來應該像下圖：

   

5. 按 F7 開啟 類別的程式 ClearableTextBox 代碼編輯器。

6. 進行下列程式代碼變更：

   1. 在程式代碼檔案頂端，匯入 System.ComponentModel 命名空間。

   2. 將 DefaultEvent 屬性加入該類別。 這個屬性會設定當在設計工具中按兩下控制項時，取用者所產生的事件。 取用者是宣告及使用此控件的物件。

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

      Imports System.ComponentModel
      
      <DefaultEvent("TextChanged")>
      Public Class ClearableTextBox
      

   3. 新增事件處理程式，將事件轉送 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 會當做參數傳遞至 屬性，指出事件應該可見。

   4. 新增名為 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
      

   5. 新增名為 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
      

7. 切換回設計工具， 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
   

8. 最後，以滑鼠右鍵按兩下 [方案總管] 視窗中的項目，然後選取 [建置]，以建置專案。 不應該有任何錯誤，而且建置完成之後， ClearableTextBox 控件會出現在工具箱中以供使用。

下一個步驟是使用表單中的控件。

範例應用程式

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

1. 在 [方案總管] 視窗中，按兩下表單以開啟設計工具。 應該選取表單的設計介面。

2. 將表單的 Size 屬性設定為 432, 315。

3. 開啟 [ 工具箱] 視窗，然後按兩下 [可清除]TextBox 控制件。 此控件應該列在以專案命名的區段底下。

4. 同樣地，按兩下 [可TextBox 清除] 控制項以產生第二個控制件。

5. 返回設計工具，並分隔控件，以便您可以看到這兩個控件。

6. 選取一個控制項並設定下列屬性：

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

7. 選取其他控制項並設定下列屬性：

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

8. 回到 [ 工具箱] 視窗，將標籤新增至窗體，並設定下列屬性：

   屬性	值
   名稱	lblFullName
   Location	12, 252

9. 接下來，您必須產生兩個使用者控件的事件處理程式。 在設計工具中，按兩下 ctlFirstName 控件。 此動作會產生事件的事件處理程式 TextChanged ，並開啟程式代碼編輯器。

10. 切換回設計工具，然後按兩下 ctlLastName 控制項以產生第二個事件處理程式。

11. 切換回設計工具，然後按兩下表單的標題列。 此動作會產生事件的事件處理程式 Load 。

12. 在程式代碼編輯器中，新增名為 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
    

13. 針對這兩 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
    

14. 最後，從表單的 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
    

執行項目並輸入名稱與姓氏：

請嘗試按下 ↻ 按鈕來重設其中一個文字框。