Jak utworzyć kontrolkę użytkownika

W tym artykule pokazano, jak dodać kontrolkę użytkownika do projektu, a następnie dodać tę kontrolkę użytkownika do formularza. Utworzysz kontrolkę użytkownika wielokrotnego użytku, która jest wizualnie atrakcyjna i funkcjonalna. Nowa kontrolka grupuje kontrolkę TextBox z kontrolką Button . Gdy użytkownik wybierze przycisk, tekst w polu tekstowym zostanie wyczyszczony. Aby uzyskać więcej informacji na temat kontrolek użytkowników, zobacz Omówienie kontrolki użytkownika.

Zrozumienie konsumentów systemu kontroli użytkowników

W tym artykule termin konsument odnosi się do dowolnego kodu, który używa kontroli użytkownika. Obejmuje to:

• Formularze zawierające kontrolkę użytkownika.
• Inne kontrolki hostujące kontrolkę użytkownika.
• Aplikacje odwołujące się do biblioteki kontroli użytkownika.

Podczas tworzenia kontrolki użytkownika tworzysz składnik wielokrotnego użytku. Użytkownik jest tym, kto używa tego składnika, umieszczając go w formularzu, ustawiając jego właściwości lub odpowiadając na jego zdarzenia. Użytkownik nie musi wiedzieć o kontrolkach wewnętrznych (takich jak TextBox i Button), które składają się na kontrolkę użytkownika — współdziałają tylko z właściwościami i zdarzeniami, które chcesz uwidocznić.

Podstawowy wzorzec kodu dla kontrolek użytkownika

Przed dodaniem szczegółowej implementacji warto zrozumieć minimalny realny wzorzec kodu dla kontrolki użytkownika. Podstawowa kontrola użytkownika wymaga:

• Przekazywanie zdarzeń — przekazywanie zdarzeń z kontrolek wewnętrznych do odbiorcy.
• Ekspozycja na właściwości — umożliwia użytkownikowi dostęp do właściwości kontroli wewnętrznej.
• Zachowanie logiczne — obsługiwanie interakcji między wewnętrznymi kontrolkami.

Poniższy kod demonstruje te wzorce. Nie potrzebujesz całego tego kodu do podstawowej kontroli użytkownika, ale te wzorce ułatwiają tworzenie profesjonalnego, wielokrotnego użytku składnika, który dobrze integruje się z aplikacjami projektanta i konsumentów.

Dodawanie nowej kontrolki użytkownika

Po otwarciu projektu Windows Forms w programie Visual Studio użyj szablonów programu Visual Studio, aby utworzyć kontrolkę użytkownika:

1. W programie Visual Studio znajdź okno Eksplorator rozwiązań . Kliknij projekt prawym przyciskiem myszy i wybierz polecenie Dodaj>kontrolkę użytkownika (Formularze systemu Windows).

   

2. Ustaw nazwę kontrolki na ClearableTextBox i naciśnij przycisk Dodaj.

   

Po utworzeniu kontrolki użytkownika program Visual Studio otworzy projektanta:

Projektowanie czytelnego pola tekstowego

Kontrolka użytkownika składa się z kontrolek składowych, które są kontrolkami, które tworzysz na powierzchni projektowej, przy projektowaniu formularza. Wykonaj następujące kroki, aby dodać i skonfigurować kontrolkę użytkownika i jego kontrolki składowe:

1. Po otwarciu narzędzia projektowego, powierzchnia projektowa dla kontrolki użytkownika powinna być wybranym obiektem. Jeśli tak nie jest, kliknij na powierzchnię projektową, aby ją wybrać. Ustaw następujące właściwości w oknie Właściwości :

   Majątek	Wartość
   Minimalny rozmiar	84, 53
   Rozmiar	191, 53

2. Dodaj kontrolkę Label . Określ następujące właściwości:

   Majątek	Wartość
   Nazwa	lblTitle
   Lokalizacja	3, 5

3. Dodaj kontrolkę TextBox . Określ następujące właściwości:

   Majątek	Wartość
   Nazwa	txtValue
   kotwica	Top, Left, Right
   Lokalizacja	3, 23
   Rozmiar	148, 23

4. Dodaj kontrolkę Button . Określ następujące właściwości:

   Majątek	Wartość
   Nazwa	btnClear
   kotwica	Top, Right
   Lokalizacja	157, 23
   Rozmiar	31, 23
   Tekst	↻

   Kontrolka powinna wyglądać podobnie do poniższej ilustracji:

   

5. Naciśnij F7 , aby otworzyć edytor kodu dla ClearableTextBox klasy.

6. Wprowadź następujące zmiany kodu:

   1. W górnej części pliku kodu zaimportuj System.ComponentModel przestrzeń nazw.

   2. DefaultEvent Dodaj atrybut do klasy. Ten atrybut ustawia zdarzenie generowane, gdy odbiorca (formularz lub aplikacja korzystająca z tej kontrolki) klika dwukrotnie kontrolkę w projektancie. Aby uzyskać więcej informacji na temat atrybutów, zobacz Atrybuty (C#) lub Omówienie atrybutów (Visual Basic).

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

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

   3. Dodaj procedurę obsługi zdarzeń, która przekazuje TextBox.TextChanged zdarzenie użytkownikom kontrolki użytkownika:

      [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
      

      Zwróć uwagę, że zdarzenie ma zadeklarowany Browsable atrybut . Po zastosowaniu Browsable do zdarzenia lub właściwości, kontroluje, czy pozycja jest widoczna w oknie Właściwości po wybraniu kontrolki w projektancie. W tym przypadku true jest przekazywany jako parametr do atrybutu, wskazując, że zdarzenie powinno być widoczne.

   4. Dodaj właściwość ciągu o nazwie Text, która uwidacznia TextBox.Text właściwość użytkownikom kontrolki użytkownika:

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

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

   5. Dodaj właściwość ciągu o nazwie Title, która uwidacznia Label.Text właściwość użytkownikom kontrolki użytkownika:

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

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

7. Wróć do projektanta ClearableTextBox i kliknij dwukrotnie kontrolkę btnClear , aby wygenerować procedurę obsługi dla Click zdarzenia. Dodaj następujący kod dla programu obsługi, który czyści txtValue pole tekstowe:

   private void btnClear_Click(object sender, EventArgs e) =>
       Text = "";
   

   Private Sub btnClear_Click(sender As Object, e As EventArgs)
       txtValue.Text = ""
   End Sub
   

8. Na koniec skompiluj projekt, klikając prawym przyciskiem myszy projekt w oknie Eksplorator rozwiązań i wybierając polecenie Kompiluj. Nie powinny występować żadne błędy, a po zakończeniu kompilacji kontrolka ClearableTextBox pojawia się w przyborniku do wykorzystania.

Następnym krokiem jest użycie kontrolki w formularzu.

Przykładowa aplikacja

Jeśli utworzono nowy projekt w ostatniej sekcji, masz pustą Form o nazwie Form1, w przeciwnym razie utwórz nowy formularz.

1. W oknie Eksplorator rozwiązań kliknij dwukrotnie formularz, aby otworzyć projektanta. Należy wybrać powierzchnię projektową formularza.

2. Ustaw właściwość Size formularza na wartość 432, 315.

3. Otwórz okno Przybornik i kliknij dwukrotnie kontrolkę ClearableTextBox. Ta kontrolka powinna być wyświetlana w sekcji o nazwie po projekcie.

4. Ponownie kliknij dwukrotnie kontrolkę ClearableTextBox , aby wygenerować drugą kontrolkę.

5. Wróć do projektanta i oddziel kontrolki, aby zobaczyć obie.

6. Wybierz jedną kontrolkę i ustaw następujące właściwości:

   Majątek	Wartość
   Nazwa	ctlFirstName
   Lokalizacja	12, 12
   Rozmiar	191, 53
   Nazwa	First Name

7. Wybierz drugą kontrolkę i ustaw następujące właściwości:

   Majątek	Wartość
   Nazwa	ctlLastName
   Lokalizacja	12, 71
   Rozmiar	191, 53
   Nazwa	Last Name

8. Wróć do okna przybornika , dodaj kontrolkę etykiety do formularza i ustaw następujące właściwości:

   Majątek	Wartość
   Nazwa	lblFullName
   Lokalizacja	12, 252

9. Następnie należy wygenerować programy obsługi zdarzeń dla dwóch kontrolek użytkownika. W projektancie kliknij dwukrotnie kontrolkę ctlFirstName . Ta akcja generuje program obsługi zdarzeń dla TextChanged zdarzenia i otwiera edytor kodu.

10. Wróć do projektanta i kliknij dwukrotnie kontrolkę ctlLastName, aby wygenerować drugą procedurę obsługi zdarzenia.

11. Wróć do projektanta i kliknij dwukrotnie pasek tytułu formularza. Ta akcja generuje program obsługi zdarzeń dla Load zdarzenia.

12. W edytorze kodu dodaj metodę o nazwie UpdateNameLabel. Ta metoda łączy obie nazwy w celu utworzenia komunikatu i przypisuje komunikat do kontrolki 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. W przypadku obu TextChanged programów obsługi zdarzeń wywołaj metodę 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. Na koniec wywołaj metodę UpdateNameLabel z zdarzenia Load formularza:

    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
    

Uruchom projekt i wprowadź imię i nazwisko:

Spróbuj nacisnąć przycisk ↻, aby zresetować jedno z pól tekstowych.