Создание пользовательского элемента управления

2025-06-25

В этой статье описано, как добавить элемент управления пользователем в проект, а затем добавить этот элемент управления в форму. Вы создадите повторно используемый пользовательский элемент управления, который визуально привлекательным и функциональным. Новый элемент управления группит TextBox элемент управления с элементом Button управления. Когда пользователь выбирает кнопку, текст в текстовом поле очищается. Дополнительные сведения о пользовательских элементах управления см. в обзоре пользовательского элемента управления.

Общие сведения о потребителях элементов управления пользователем

В этой статье термин потребитель относится к любому коду, использующему ваш пользовательский элемент управления. Сюда входит следующее:

Формы, содержащие элемент управления пользователя.
Другие элементы управления , размещающие элемент управления пользователем.
Приложения , ссылающиеся на библиотеку элементов управления пользователем.

При создании пользовательского элемента управления вы создаете повторно используемый компонент. Потребитель использует этот компонент, помещая его в форму, устанавливая его свойства или отвечая на его события. Потребитель не должен знать о внутренних элементах управления (таких как TextBox и Button) которые составляют элемент управления пользователем, они взаимодействуют только со свойствами и событиями, которые вы выбираете для предоставления.

Базовый шаблон кода для пользовательских элементов управления

Перед добавлением подробной реализации полезно понять минимальный шаблон жизнеспособного кода для пользовательского элемента управления. В основе этого элемента управления требуется:

Переадресация событий — передача событий из внутренних элементов управления потребителю.
Экспозиция свойств . Разрешить потребителю получать доступ к свойствам внутреннего контроля.
Логическое поведение — обработка взаимодействий между внутренними элементами управления.

В следующем коде показаны эти шаблоны. Вам не нужен весь этот код для базового пользовательского элемента управления, но эти шаблоны помогают создать профессиональный, многократно используемый компонент, который хорошо интегрируется с конструктором и потребительскими приложениями.

Добавление нового пользовательского элемента управления

После открытия проекта Windows Forms в Visual Studio используйте шаблоны Visual Studio для создания пользовательского элемента управления:

В Visual Studio найдите окно обозревателя решений . Щелкните проект правой кнопкой мыши и выберите пункт "Добавить>элемент управления пользователем" (Windows Forms).
Задайте для элемента управления Имя элемента управления ClearableTextBox и нажмите клавишу Add.

После создания пользовательского элемента управления Visual Studio открывает конструктор:

Конструктор пользовательского элемента управления в Visual Studio для Windows Forms

Проектирование понятного текстового поля

Пользовательский элемент управления состоит из составных элементов управления, которые являются элементами управления, которые вы создавать наобласти конструктора, точно так же, как вы разрабатываете форму. Выполните следующие действия, чтобы добавить и настроить элемент управления пользователем и его составляющие элементы управления:

При открытии дизайнера область дизайна пользовательского элемента управления должна быть выбранным объектом. Если это не так, щелкните область конструктора, чтобы выбрать ее. Задайте следующие свойства в окне свойств :

Недвижимость Ценность

Минимальный размер 84, 53

Размер 191, 53
Label Добавьте элемент управления. Задайте следующие свойства:

Недвижимость Ценность

Имя lblTitle

Местоположение 3, 5
TextBox Добавьте элемент управления. Задайте следующие свойства:

Недвижимость Ценность

Имя txtValue

Привязка Top, Left, Right

Местоположение 3, 23

Размер 148, 23
Button Добавьте элемент управления. Задайте следующие свойства:

Недвижимость Ценность

Имя btnClear

Привязка Top, Right

Местоположение 157, 23

Размер 31, 23

Текст ↻

Элемент управления должен выглядеть следующим образом:
Нажмите клавишу F7 , чтобы открыть редактор кода для ClearableTextBox класса.
Внесите следующие изменения кода:
1. В начале файла кода импортируйте System.ComponentModel пространство имен.
2. Добавьте к классу атрибут 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
```
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)]
[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. Добавьте строковое свойство с именем Title, которое предоставляет Label.Text свойство потребителям пользовательского элемента управления:
```
[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
```
Вернитесь к 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 элемент управления появится на панели инструментов для использования.

Недвижимость	Ценность
Минимальный размер	`84, 53`
Размер	`191, 53`

Недвижимость	Ценность
Имя	`lblTitle`
Местоположение	`3, 5`

Недвижимость	Ценность
Имя	`txtValue`
Привязка	`Top, Left, Right`
Местоположение	`3, 23`
Размер	`148, 23`

Недвижимость	Ценность
Имя	`btnClear`
Привязка	`Top, Right`
Местоположение	`157, 23`
Размер	`31, 23`
Текст	`↻`

Следующий шаг — использование элемента управления в форме.

Пример приложения

Если вы создали новый проект в последнем разделе, у вас есть пустая форма Form с именем Form1, в противном случае создайте новую форму.

В окне обозревателя решений дважды щелкните форму, чтобы открыть конструктор. Область конструктора формы должна быть выбрана.
Задайте для свойства Size формы значение 432, 315.
Откройте окно панели элементов и дважды щелкните элемент управления ClearableTextBox. Этот элемент управления должен быть указан в разделе с именем проекта.
Снова дважды щелкните элемент управления ClearableTextBox , чтобы создать второй элемент управления.
Вернитесь к конструктору и разделите элементы управления, чтобы можно было видеть их оба.
Выберите один элемент управления и задайте следующие свойства:

Недвижимость Ценность

Имя ctlFirstName

Местоположение 12, 12

Размер 191, 53

Название First Name
Выберите другой элемент управления и задайте следующие свойства:

Недвижимость Ценность

Имя ctlLastName

Местоположение 12, 71

Размер 191, 53

Название Last Name
Вернитесь в окно панели элементов, добавьте элемент управления меткой в форму и задайте следующие свойства:

Недвижимость Ценность

Имя lblFullName

Местоположение 12, 252
Затем необходимо создать обработчики событий для двух пользовательских элементов управления. В конструкторе дважды щелкните ctlFirstName элемент управления. Это действие создает обработчик событий для TextChanged события и открывает редактор кода.
Переключите обратно в конструктор и дважды щелкните ctlLastName элемент управления, чтобы создать второй обработчик событий.
Переключитесь обратно на конструктор и дважды щелкните на строке заголовка формы. Это действие создает обработчик событий для Load события.

Недвижимость	Ценность
Имя	`ctlFirstName`
Местоположение	`12, 12`
Размер	`191, 53`
Название	`First Name`

Недвижимость	Ценность
Имя	`ctlLastName`
Местоположение	`12, 71`
Размер	`191, 53`
Название	`Last Name`

Недвижимость	Ценность
Имя	`lblFullName`
Местоположение	`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

Наконец, вызовите метод UpdateNameLabel из события Load формы:

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 с двумя текстовыми полями, созданными из пользовательских элементов управления, и меткой.

Попробуйте нажать кнопку ↻, чтобы сбросить одно из текстовых полей.