Erstellen eines Benutzersteuerelements (Windows Forms .NET)

Artikel
03/05/2024

In diesem Artikel erfahren Sie, wie Sie Ihrem Projekt ein Benutzersteuerelement hinzufügen und dieses anschließend einem Formular hinzufügen. Sie erstellen ein wiederverwendbares Benutzersteuerelement, das sowohl visuell ansprechend als auch funktional ist. Das neue Steuerelement gruppiert ein TextBox-Steuerelement mit einem Button-Steuerelement. Wenn die Schaltfläche ausgewählt wird, wird der Text im Textfeld gelöscht. Weitere Informationen zu Benutzersteuerelementen finden Sie in der Übersicht über Benutzersteuerelemente.

Wichtig

Der Desktopleitfaden zu .NET 7 und .NET 6 ist in Bearbeitung.

Hinzufügen eines Benutzersteuerelements zu einem Projekt

Öffnen Sie Ihr Windows Forms-Projekt in Visual Studio, und verwenden Sie dann die Visual Studio-Vorlagen, um ein Benutzersteuerelement zu erstellen:

Suchen Sie in Visual Studio nach dem Fenster Projektmappen-Explorer. Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Hinzufügen>Benutzersteuerelement (Windows Forms) aus.
Legen Sie unter Name den Namen des Steuerelements auf ClearableTextBox fest, und wählen Sie Hinzufügen aus.

Nachdem das Benutzersteuerelement erstellt wurde, öffnet Visual Studio den Designer:

Der Benutzersteuerelement-Designer in Visual Studio für Windows Forms

Entwerfen des löschbaren Textfelds

Das Benutzersteuerelement besteht aus konstituierenden Steuerelementen. Das sind die Steuerelemente, die Sie auf der Entwurfsoberfläche erstellen – genau wie beim Entwerfen eines Formulars. Führen Sie die folgenden Schritte aus, um das Benutzersteuerelement und die zugehörigen konstituierenden Steuerelemente hinzuzufügen und zu konfigurieren:

Wenn der Designer geöffnet ist, sollte die Entwurfsoberfläche des Benutzersteuerelements das ausgewählte Objekt sein. Falls nicht, klicken Sie auf die Entwurfsoberfläche, um sie auszuwählen. Legen Sie im Fenster Eigenschaften die folgenden Eigenschaften fest:

Eigenschaft Wert

MinimumSize 84, 53

Größe 191, 53
Fügen Sie ein Label-Steuerelement hinzu. Legen Sie die folgenden Eigenschaften fest:

Eigenschaften Wert

Name lblTitle

Standort 3, 5
Fügen Sie ein TextBox-Steuerelement hinzu. Legen Sie die folgenden Eigenschaften fest:

Eigenschaften Wert

Name txtValue

Anchor Top, Left, Right

Standort 3, 23

Größe 148, 23
Fügen Sie ein Button-Steuerelement hinzu. Legen Sie die folgenden Eigenschaften fest:

Eigenschaften Wert

Name btnClear

Anchor Top, Right

Standort 157, 23

Größe 31, 23

Text ↻

Das Steuerelement sollte wie auf der folgenden Abbildung aussehen:
Drücken Sie F7, um den Code-Editor für die ClearableTextBox-Klasse zu öffnen.

Eigenschaft	Wert
MinimumSize	`84, 53`
Größe	`191, 53`

Eigenschaften	Wert
Name	`lblTitle`
Standort	`3, 5`

Eigenschaften	Wert
Name	`txtValue`
Anchor	`Top, Left, Right`
Standort	`3, 23`
Größe	`148, 23`

Eigenschaften	Wert
Name	`btnClear`
Anchor	`Top, Right`
Standort	`157, 23`
Größe	`31, 23`
Text	`↻`

Führen Sie die folgenden Codeänderungen durch:

Importieren Sie am Anfang der Codedatei den System.ComponentModel-Namespace.
Fügen Sie der Klasse das DefaultEvent -Attribut hinzu. Dieses Attribut legt fest, welches Ereignis vom Consumer generiert wird, wenn im Designer auf das Steuerelement doppelgeklickt wird. Der Consumer ist das Objekt, das dieses Steuerelement deklariert und verwendet.
```
using System.ComponentModel;

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

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

Fügen Sie einen Ereignishandler hinzu, der das TextBox.TextChanged-Ereignis an den Consumer weiterleitet:

[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

Beachten Sie, dass für das Ereignis das Browsable-Attribut deklariert wird. Durch Anwenden von Browsable auf ein Ereignis oder auf eine Eigenschaft wird gesteuert, ob das Element im Fenster Eigenschaften sichtbar ist, wenn das Steuerelement im Designer ausgewählt wird. In diesem Fall wird true als Parameter an das Attribut übergeben, um anzugeben, dass das Ereignis sichtbar sein soll.

Fügen Sie eine Zeichenfolgeneigenschaft namens Text hinzu, um die TextBox.Text-Eigenschaft an den Consumer weiterzuleiten:

[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

Fügen Sie eine Zeichenfolgeneigenschaft namens Title hinzu, um die Label.Text-Eigenschaft an den Consumer weiterzuleiten:

[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

Kehren Sie zum ClearableTextBox-Designer zurück, und doppelklicken Sie auf das btnClear-Steuerelement, um einen Handler für das Click-Ereignis zu generieren. Fügen Sie den folgenden Code für den Handler hinzu, damit das txtValue-Textfeld gelöscht wird:
```
private void btnClear_Click(object sender, EventArgs e) =>
    Text = "";
```
```
Private Sub btnClear_Click(sender As Object, e As EventArgs)
    txtValue.Text = ""
End Sub
```
Erstellen Sie abschließend das Projekt, indem Sie im Fenster Projektmappen-Explorer mit der rechten Maustaste auf das Projekt klicken und Erstellen auswählen. Es sollten keine Fehler auftreten. Nach Abschluss der Erstellung wird das ClearableTextBox-Steuerelement in der Toolbox angezeigt und kann verwendet werden.

Im nächsten Schritt wird das Steuerelement in einem Formular verwendet.

Beispielanwendung

Wenn Sie im letzten Abschnitt ein neues Projekt erstellt haben, verfügen Sie über ein leeres Form-Element mit dem Namen Form1. Falls nicht, erstellen Sie ein neues Formular.

Doppelklicken Sie im Fenster Projektmappen-Explorer auf das Formular, um den Designer zu öffnen. Die Entwurfsoberfläche des Formulars sollte ausgewählt sein.
Legen Sie die Size-Eigenschaft des Formulars auf 432, 315 fest.
Öffnen Sie das Fenster Toolbox, und doppelklicken Sie auf das Steuerelement ClearableTextBox. Dieses Steuerelement sollte unter einem nach Ihrem Projekt benannten Abschnitt aufgeführt sein.
Doppelklicken Sie erneut auf das Steuerelement ClearableTextBox, um ein zweites Steuerelement zu generieren.
Kehren Sie zum Designer zurück, und trennen Sie die Steuerelemente, sodass Sie beide sehen können.
Wählen Sie eines der Steuerelemente aus, und legen Sie die folgenden Eigenschaften fest:

Eigenschaft Wert

Name ctlFirstName

Standort 12, 12

Größe 191, 53

Titel First Name
Wählen Sie das andere Steuerelement aus, und legen Sie die folgenden Eigenschaften fest:

Eigenschaft Wert

Name ctlLastName

Standort 12, 71

Größe 191, 53

Titel Last Name
Fügen Sie dem Formular im Fenster Toolbox ein Label-Steuerelement hinzu, und legen Sie die folgenden Eigenschaften fest:

Eigenschaft Wert

Name lblFullName

Standort 12, 252
Als Nächstes müssen die Ereignishandler für die beiden Benutzersteuerelemente generiert werden. Doppelklicken Sie im Designer auf das ctlFirstName-Steuerelement. Dadurch wird der Ereignishandler für das TextChanged-Ereignis generiert und der Code-Editor geöffnet.
Kehren Sie zum Designer zurück, und doppelklicken Sie auf das ctlLastName-Steuerelement, um den zweiten Ereignishandler zu generieren.
Kehren Sie zum Designer zurück, und doppelklicken Sie auf die Titelleiste des Formulars. Dadurch wird ein Ereignishandler für das Load-Ereignis generiert.

Eigenschaft	Wert
Name	`ctlFirstName`
Standort	`12, 12`
Größe	`191, 53`
Titel	`First Name`

Eigenschaft	Wert
Name	`ctlLastName`
Standort	`12, 71`
Größe	`191, 53`
Titel	`Last Name`

Eigenschaft	Wert
Name	`lblFullName`
Standort	`12, 252`

Fügen Sie im Code-Editor eine Methode mit dem Namen UpdateNameLabel hinzu. Diese Methode kombiniert beide Namen für die Erstellung einer Nachricht und weist die Nachricht dem lblFullName-Steuerelement zu.

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

Rufen Sie für beide TextChanged-Ereignishandler die UpdateNameLabel-Methode auf:

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

Rufen Sie abschließend die UpdateNameLabel-Methode über das Load-Ereignis des Formulars auf:

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

Führen Sie das Projekt aus, und geben Sie einen Vornamen und einen Nachnamen ein:

Eine Windows Forms-App mit zwei Textfeldern, die aus Benutzersteuerelementen erstellt wurden, und eine Bezeichnung.

Wählen Sie die Schaltfläche ↻ aus, um eines der Textfelder zurückzusetzen.

Erstellen eines Benutzersteuerelements (Windows Forms .NET)

Hinzufügen eines Benutzersteuerelements zu einem Projekt

Entwerfen des löschbaren Textfelds

Beispielanwendung

Feedback

Feedback

Zusätzliche Ressourcen