Przewodnik: tworzenie kontrolki złożonej za pomocą języka C#

Artykuł
10/19/2023

Kontrolki złożone umożliwiają tworzenie i ponowne używanie niestandardowych interfejsów graficznych. Kontrolka złożona jest zasadniczo składnikiem z reprezentacją wizualną. W związku z tym może składać się z co najmniej jednej kontrolki, składników lub bloków kodu systemu Windows Forms, które mogą rozszerzać funkcjonalność przez weryfikowanie danych wejściowych użytkownika, modyfikowanie właściwości wyświetlania lub wykonywanie innych zadań wymaganych przez autora. Kontrolki złożone można umieszczać w formularzach systemu Windows w taki sam sposób, jak w przypadku innych kontrolek. W pierwszej części tego przewodnika utworzysz prostą kontrolkę złożoną o nazwie ctlClock. W drugiej części przewodnika rozszerzasz funkcjonalność dziedziczenia ctlClock .

Tworzenie projektu

Podczas tworzenia nowego projektu należy określić jego nazwę, aby ustawić przestrzeń nazw katalogu głównego, nazwę zestawu i nazwę projektu oraz upewnić się, że domyślny składnik będzie znajdować się w prawidłowej przestrzeni nazw.

Aby utworzyć bibliotekę formantów ctlClockLib i kontrolkę ctlClock

W programie Visual Studio utwórz nowy projekt biblioteki kontrolek formularzy systemu Windows i nadaj mu nazwę ctlClockLib.

Nazwa projektu , ctlClockLibjest również domyślnie przypisywana do głównej przestrzeni nazw. Główna przestrzeń nazw służy do kwalifikowania nazw składników w zestawie. Jeśli na przykład dwa zestawy zawierają składniki o nazwie ctlClock, możesz określić składnik ctlClock przy użyciu polecenia ctlClockLib.ctlClock.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy plik UserControl1.cs, a następnie kliknij polecenie Zmień nazwę. Zmień nazwę pliku na ctlClock.cs. Kliknij przycisk Tak po wyświetleniu monitu o zmianę nazwy wszystkich odwołań do elementu kodu "UserControl1".

Uwaga

Domyślnie kontrolka złożona dziedziczy z UserControl klasy udostępnionej przez system. Klasa UserControl zapewnia funkcjonalność wymaganą przez wszystkie kontrolki złożone i implementuje standardowe metody i właściwości.
W menu Plik kliknij pozycję Zapisz wszystko, aby zapisać projekt.

Dodawanie kontrolek i składników systemu Windows do kontrolki złożonej

Interfejs wizualny jest istotną częścią kontrolki złożonej. Ten interfejs wizualny jest implementowany przez dodanie co najmniej jednej kontrolki systemu Windows do powierzchni projektanta. W poniższej demonstracji uwzględnisz kontrolki systemu Windows w kontrolce złożonej i napiszesz kod w celu zaimplementowania funkcji.

Aby dodać etykietę i czasomierz do kontrolki złożonej

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy plik ctlClock.cs, a następnie kliknij polecenie Wyświetl Projektant.
W przyborniku rozwiń węzeł Wspólne kontrolki, a następnie kliknij dwukrotnie pozycję Etykieta.

Kontrolka Label o nazwie label1 jest dodawana do kontrolki na powierzchni projektanta.
W projektancie kliknij pozycję label1. W okno Właściwości ustaw następujące właściwości.

Właściwości Zmień na

Nazwa/nazwisko lblDisplay

Tekst (blank space)

Textalign MiddleCenter

Font.Size 14
W przyborniku rozwiń węzeł Składniki, a następnie kliknij dwukrotnie pozycję Czasomierz.

Ponieważ element Timer jest składnikiem, nie ma wizualnej reprezentacji w czasie wykonywania. W związku z tym nie jest wyświetlany z kontrolkami na powierzchni projektanta, ale raczej w Projektant Component (taca w dolnej części powierzchni projektanta).
W Projektant składników kliknij pozycję timer1, a następnie ustaw Interval właściwość na 1000 i Enabled właściwość na true.

Właściwość Interval kontroluje częstotliwość, z jaką Timer tyka składnik. Za każdym razem, gdy timer1 znaczniki uruchamiają kod w timer1_Tick zdarzeniu. Interwał reprezentuje liczbę milisekund między znacznikami.
W Projektant składników kliknij dwukrotnie czasomierz1, aby przejść do timer1_Tick zdarzenia dla ctlClock.
Zmodyfikuj kod, tak aby był podobny do poniższego przykładu kodu. Pamiętaj, aby zmienić modyfikator dostępu z private na protected.
```
protected void timer1_Tick(object sender, System.EventArgs e)
{
    // Causes the label to display the current time.
    lblDisplay.Text = DateTime.Now.ToLongTimeString();
}
```
Ten kod spowoduje, że bieżący czas będzie wyświetlany w elemencie lblDisplay. Ponieważ interwał timer1 został ustawiony na , to zdarzenie będzie występować 1000co tysiąc milisekund, w związku z tym aktualizując bieżący czas co sekundę.
Zmodyfikuj metodę tak, aby można ją było zastąpić za pomocą słowa kluczowego virtual . Aby uzyskać więcej informacji, zobacz sekcję "Dziedziczenie z kontrolki użytkownika" poniżej.
```
protected virtual void timer1_Tick(object sender, System.EventArgs e)
```
W menu Plik kliknij pozycję Zapisz wszystko, aby zapisać projekt.

Właściwości	Zmień na
Nazwa/nazwisko	`lblDisplay`
Tekst	`(blank space)`
Textalign	`MiddleCenter`
Font.Size	`14`

Dodawanie właściwości do kontrolki złożonej

Kontrolka zegara hermetyzuje teraz kontrolkę Label i Timer składnik, z których każdy ma własny zestaw właściwości nieodłącznych. Chociaż poszczególne właściwości tych kontrolek nie będą dostępne dla kolejnych użytkowników kontrolki, można tworzyć i uwidaczniać właściwości niestandardowe, pisząc odpowiednie bloki kodu. W poniższej procedurze dodasz właściwości do kontrolki, które umożliwiają użytkownikowi zmianę koloru tła i tekstu.

Aby dodać właściwość do kontrolki złożonej

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy plik ctlClock.cs, a następnie kliknij polecenie Wyświetl kod.

Zostanie otwarty Edytor kodu dla kontrolki.
Znajdź instrukcję public partial class ctlClock . Poniżej nawiasu klamrowego otwierającego ({)wpisz następujący kod.
```
private Color colFColor;
private Color colBColor;
```
Te instrukcje tworzą zmienne prywatne, które będą używane do przechowywania wartości właściwości, które mają zostać utworzone.

Wprowadź lub wklej następujący kod pod deklaracjami zmiennych z kroku 2.

// Declares the name and type of the property.
public Color ClockBackColor
{
    // Retrieves the value of the private variable colBColor.
    get
    {
        return colBColor;
    }
    // Stores the selected value in the private variable colBColor, and
    // updates the background color of the label control lblDisplay.
    set
    {
        colBColor = value;
        lblDisplay.BackColor = colBColor;
    }
}
// Provides a similar set of instructions for the foreground color.
public Color ClockForeColor
{
    get
    {
        return colFColor;
    }
    set
    {
        colFColor = value;
        lblDisplay.ForeColor = colFColor;
    }
}

Powyższy kod udostępnia dwie właściwości ClockForeColor niestandardowe i ClockBackColor, dla kolejnych użytkowników tej kontrolki. Instrukcje get i set zapewniają przechowywanie i pobieranie wartości właściwości, a także kod w celu zaimplementowania funkcji odpowiednich dla właściwości.

W menu Plik kliknij pozycję Zapisz wszystko, aby zapisać projekt.

Testowanie kontrolki

Kontrolki nie są aplikacjami autonomicznymi; muszą być hostowane w kontenerze. Przetestuj zachowanie kontrolki w czasie wykonywania i przećwiczyć jego właściwości za pomocą kontenera testowego UserControl. Aby uzyskać więcej informacji, zobacz How to: Test the Run-Time Behavior of a UserControl (Instrukcje: testowanie zachowania w czasie wykonywania elementu UserControl).

Aby przetestować kontrolkę

Naciśnij klawisz F5, aby skompilować projekt i uruchomić kontrolkę w kontenerze testowym UserControl.
W siatce właściwości kontenera testowego ClockBackColor znajdź właściwość, a następnie wybierz właściwość, aby wyświetlić paletę kolorów.
Wybierz kolor, klikając go.

Kolor tła kontrolki zmienia się na wybrany kolor.
Użyj podobnej sekwencji zdarzeń, aby sprawdzić, czy ClockForeColor właściwość działa zgodnie z oczekiwaniami.

W tej sekcji i w poprzednich sekcjach przedstawiono sposób łączenia składników i kontrolek systemu Windows z kodem i pakowaniem w celu zapewnienia niestandardowych funkcji w postaci złożonej kontrolki. Wiesz już, jak uwidaczniać właściwości w kontrolce złożonej i jak przetestować kontrolkę po jej zakończeniu. W następnej sekcji dowiesz się, jak utworzyć odziedziczoną kontrolkę złożoną przy użyciu ctlClock jako podstawy.

Dziedziczenie z kontrolki złożonej

W poprzednich sekcjach przedstawiono sposób łączenia kontrolek, składników i kodu systemu Windows w kontrolki złożone wielokrotnego użytku. Kontrolkę złożoną można teraz użyć jako podstawy, na której można skompilować inne kontrolki. Proces wyprowadzania klasy z klasy bazowej jest nazywany dziedziczeniem. W tej sekcji utworzysz złożoną kontrolkę o nazwie ctlAlarmClock. Ta kontrolka będzie pochodzić z kontrolki nadrzędnej . ctlClock Dowiesz się, jak rozszerzyć funkcjonalność ctlClock , przesłaniając metody nadrzędne i dodając nowe metody i właściwości.

Pierwszym krokiem tworzenia dziedziczonej kontrolki jest wyprowadzenie jej z elementu nadrzędnego. Ta akcja tworzy nową kontrolkę, która ma wszystkie właściwości, metody i graficzne cechy kontrolki nadrzędnej, ale może również działać jako podstawa dodawania nowych lub zmodyfikowanych funkcji.

Aby utworzyć dziedziczony formant

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy pozycję ctlClockLib, wskaż polecenie Dodaj, a następnie kliknij pozycję Kontrola użytkownika.

Zostanie otwarte okno dialogowe Dodawanie nowego elementu .
Wybierz szablon Dziedziczona kontrola użytkownika.
W polu Nazwa wpisz ctlAlarmClock.cs, a następnie kliknij przycisk Dodaj.

Zostanie wyświetlone okno dialogowe Selektor dziedziczenia.
W obszarze Nazwa składnika kliknij dwukrotnie pozycję ctlClock.
W Eksplorator rozwiązań przejrzyj bieżące projekty.

Uwaga

Plik o nazwie ctlAlarmClock.cs został dodany do bieżącego projektu.

Dodawanie właściwości alarmu

Właściwości są dodawane do dziedziczonej kontrolki w taki sam sposób, jak są dodawane do kontrolki złożonej. Teraz użyjesz składni deklaracji właściwości, aby dodać dwie właściwości do kontrolki: AlarmTime, która będzie przechowywać wartość daty i godziny, w której alarm ma zostać wyłączony, i AlarmSet, co będzie wskazywać, czy alarm jest ustawiony.

Aby dodać właściwości do kontrolki złożonej

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy pozycję ctlAlarmClock, a następnie kliknij polecenie Wyświetl kod.

Znajdź instrukcję public class . Pamiętaj, że kontrolka dziedziczy z elementu ctlClockLib.ctlClock. Pod nawiasem klamrowym otwierającym ({) instrukcja wpisz następujący kod.

private DateTime dteAlarmTime;
private bool blnAlarmSet;
// These properties will be declared as public to allow future
// developers to access them.
public DateTime AlarmTime
{
    get
    {
        return dteAlarmTime;
    }
    set
    {
        dteAlarmTime = value;
    }
}
public bool AlarmSet
{
    get
    {
        return blnAlarmSet;
    }
    set
    {
        blnAlarmSet = value;
    }
}

Dodaj do interfejsu graficznego kontrolki

Dziedziczona kontrolka ma interfejs wizualny, który jest identyczny z kontrolką, z którą dziedziczy. Posiada te same składowe kontrolki co jego kontrolka nadrzędna, ale właściwości kontrolek składowych nie będą dostępne, chyba że zostały one specjalnie ujawnione. Możesz dodać do interfejsu graficznego dziedziczonej kontrolki złożonej w taki sam sposób, jak dodawać do dowolnej kontrolki złożonej. Aby kontynuować dodawanie do interfejsu wizualnego zegara alarmowego, należy dodać kontrolkę etykiety, która będzie migać, gdy alarm brzmi.

Aby dodać kontrolkę etykiety

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy pozycję ctlAlarmClock, a następnie kliknij polecenie Wyświetl Projektant.

Projektant zostanie ctlAlarmClock otwarty w oknie głównym.
Kliknij część wyświetlaną kontrolki i wyświetl okno Właściwości.

Uwaga

Podczas wyświetlania wszystkich właściwości są one wygaszone. Oznacza to, że te właściwości są natywne i nie można ich modyfikować lblDisplay ani uzyskiwać do nich dostępu w okno Właściwości. Domyślnie kontrolki zawarte w kontrolce złożonej to private, a ich właściwości nie są dostępne w żaden sposób.

Uwaga

Jeśli chcesz, aby kolejni użytkownicy kontrolki złożonej mieli dostęp do swoich wewnętrznych kontrolek, zadeklaruj je jako public lub protected. Pozwoli to ustawić i zmodyfikować właściwości kontrolek zawartych w kontrolce złożonej przy użyciu odpowiedniego kodu.
Dodaj kontrolkę Label do kontrolki złożonej.
Za pomocą myszy przeciągnij kontrolkę Label bezpośrednio pod polem wyświetlania. W okno Właściwości ustaw następujące właściwości.

Właściwości Ustawienie

Nazwa/nazwisko lblAlarm

Tekst Alarm!

Textalign MiddleCenter

Visible false

Właściwości	Ustawienie
Nazwa/nazwisko	`lblAlarm`
Tekst	Alarm!
Textalign	`MiddleCenter`
Visible	`false`

Dodawanie funkcji alarmu

W poprzednich procedurach dodano właściwości i kontrolkę, która umożliwi korzystanie z funkcji alarmu w kontrolce złożonej. W tej procedurze dodasz kod, aby porównać bieżący czas z czasem alarmu i, jeśli są one takie same, aby migać alarm. Przesłaniając metodę timer1_TickctlClock i dodając do niej dodatkowy kod, rozszerzysz ctlAlarmClock możliwości, zachowując jednocześnie wszystkie nieodłączne funkcje programu ctlClock.

Aby zastąpić metodę timer1_Tick ctlClock

W Edytorze kodu znajdź instrukcję private bool blnAlarmSet; . Bezpośrednio pod nim dodaj następującą instrukcję.
```
private bool blnColorTicker;
```

W Edytorze kodu znajdź zamykający nawias klamrowy (}) na końcu klasy. Tuż przed nawiasem klamrowym dodaj następujący kod.

protected override void timer1_Tick(object sender, System.EventArgs e)
{
    // Calls the Timer1_Tick method of ctlClock.
    base.timer1_Tick(sender, e);
    // Checks to see if the alarm is set.
    if (AlarmSet == false)
        return;
    else
        // If the date, hour, and minute of the alarm time are the same as
        // the current time, flash an alarm.
    {
        if (AlarmTime.Date == DateTime.Now.Date && AlarmTime.Hour ==
            DateTime.Now.Hour && AlarmTime.Minute == DateTime.Now.Minute)
        {
            // Sets lblAlarmVisible to true, and changes the background color based on
            // the value of blnColorTicker. The background color of the label
            // will flash once per tick of the clock.
            lblAlarm.Visible = true;
            if (blnColorTicker == false)
            {
                lblAlarm.BackColor = Color.Red;
                blnColorTicker = true;
            }
            else
            {
                lblAlarm.BackColor = Color.Blue;
                blnColorTicker = false;
            }
        }
        else
        {
            // Once the alarm has sounded for a minute, the label is made
            // invisible again.
            lblAlarm.Visible = false;
        }
    }
}

Dodanie tego kodu wykonuje kilka zadań. Instrukcja override kieruje kontrolkę do użycia tej metody zamiast metody dziedziczonej z kontrolki podstawowej. Gdy ta metoda jest wywoływana, wywołuje metodę, którą zastępuje, wywołując instrukcję base.timer1_Tick , zapewniając, że wszystkie funkcje włączone w oryginalnej kontrolce są odtwarzane w tej kontrolce. Następnie uruchamia dodatkowy kod w celu włączenia funkcji alarmu. Gdy wystąpi alarm, pojawi się kontrolka migająca etykieta.

Sterowanie zegarem alarmu jest prawie kompletne. Jedyną rzeczą, która pozostaje, jest zaimplementowanie sposobu, aby go wyłączyć. W tym celu dodasz kod do lblAlarm_Click metody .

Aby zaimplementować metodę zamykania

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy plik ctlAlarmClock.cs, a następnie kliknij polecenie Wyświetl Projektant.

Zostanie otwarty projektant.
Dodaj przycisk do kontrolki. Ustaw właściwości przycisku w następujący sposób.

Właściwości Wartość

Nazwa/nazwisko btnAlarmOff

Tekst Wyłącz alarm
W projektancie kliknij dwukrotnie pozycję btnAlarmOff.

Edytor kodu otwiera wierszprivate void btnAlarmOff_Click.

Właściwości	Wartość
Nazwa/nazwisko	`btnAlarmOff`
Tekst	Wyłącz alarm

Zmodyfikuj tę metodę tak, aby przypominała następujący kod.

private void btnAlarmOff_Click(object sender, System.EventArgs e)
{
    // Turns off the alarm.
    AlarmSet = false;
    // Hides the flashing label.
    lblAlarm.Visible = false;
}

W menu Plik kliknij pozycję Zapisz wszystko, aby zapisać projekt.

Używanie dziedziczonej kontrolki w formularzu

Możesz przetestować odziedziczone sterowanie w taki sam sposób, jak przetestowano kontrolkę klasy bazowej: naciśnij klawisz F5, ctlClockaby skompilować projekt i uruchomić kontrolkę w kontenerze testowym UserControl. Aby uzyskać więcej informacji, zobacz How to: Test the Run-Time Behavior of a UserControl (Instrukcje: testowanie zachowania w czasie wykonywania elementu UserControl).

Aby użyć kontrolki, musisz hostować ją w formularzu. Podobnie jak w przypadku standardowej kontrolki złożonej, dziedziczona kontrolka złożona nie może być autonomiczna i musi być hostowana w formularzu lub innym kontenerze. Ponieważ ctlAlarmClock ma większą głębię funkcjonalności, do przetestowania jest wymagany dodatkowy kod. W tej procedurze napiszesz prosty program do testowania funkcjonalności programu ctlAlarmClock. Napiszesz kod, aby ustawić i wyświetlić AlarmTime właściwość ctlAlarmClock, i przetestujesz jego funkcje nieodłączne.

Aby skompilować i dodać kontrolkę do formularza testowego

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy pozycję ctlClockLib, a następnie kliknij polecenie Skompiluj.
Dodaj nowy projekt aplikacji Windows Forms do rozwiązania i nadaj mu nazwę Test.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł Odwołania dla projektu testowego. Kliknij przycisk Dodaj odwołanie , aby wyświetlić okno dialogowe Dodawanie odwołania . Kliknij kartę z etykietą Projekty. Projekt ctlClockLib zostanie wyświetlony w obszarze Nazwa projektu. Kliknij dwukrotnie projekt, aby dodać odwołanie do projektu testowego.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy pozycję Test, a następnie kliknij polecenie Skompiluj.
W przyborniku rozwiń węzeł składniki ctlClockLib.
Kliknij dwukrotnie plik ctlAlarmClock , aby dodać kopię ctlAlarmClock do formularza.
W przyborniku znajdź i kliknij dwukrotnie pozycję DateTimePicker, aby dodać kontrolkę DateTimePicker do formularza, a następnie dodaj kontrolkęLabel, klikając dwukrotnie pozycję Etykieta.
Użyj myszy, aby umieścić kontrolki w wygodnym miejscu w formularzu.
Ustaw właściwości tych kontrolek w następujący sposób.

Kontrolka Właściwości Wartość

label1 Tekst (blank space)

Nazwa/nazwisko lblTest

dateTimePicker1 Nazwa/nazwisko dtpTest

Format Time
W projektancie kliknij dwukrotnie plik dtpTest.

Zostanie otwarty Edytor kodu w pliku private void dtpTest_ValueChanged.

Kontrolka	Właściwości	Wartość
`label1`	Tekst	`(blank space)`
	Nazwa/nazwisko	`lblTest`
`dateTimePicker1`	Nazwa/nazwisko	`dtpTest`
	Format	Time

Zmodyfikuj kod, tak aby był podobny do poniższego.

private void dtpTest_ValueChanged(object sender, System.EventArgs e)
{
    ctlAlarmClock1.AlarmTime = dtpTest.Value;
    ctlAlarmClock1.AlarmSet = true;
    lblTest.Text = "Alarm Time is " +
        ctlAlarmClock1.AlarmTime.ToShortTimeString();
}

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy pozycję Test, a następnie kliknij polecenie Ustaw jako projekt startowy.
W menu Debugowanie kliknij polecenie Rozpocznij debugowanie.

Zostanie uruchomiony program testowy. Należy pamiętać, że bieżący czas jest aktualizowany w kontrolce ctlAlarmClock i że czas rozpoczęcia jest wyświetlany w kontrolce DateTimePicker .
Kliknij lokalizację DateTimePicker , w której są wyświetlane minuty godziny.
Za pomocą klawiatury ustaw wartość minut, która jest minuta większa niż bieżąca godzina wyświetlana przez ctlAlarmClock.

Czas ustawienia alarmu jest wyświetlany w pliku lblTest. Poczekaj na wyświetlony czas osiągnięcia czasu ustawienia alarmu. Gdy wyświetlany czas osiągnie czas, do którego ustawiono alarm, będzie migać lblAlarm .
Wyłącz alarm, klikając pozycję btnAlarmOff. Teraz możesz zresetować alarm.

W tym artykule opisano szereg kluczowych pojęć. Wiesz już, jak utworzyć złożoną kontrolkę, łącząc kontrolki i składniki z kontenerem złożonej kontrolki. Wiesz już, jak dodawać właściwości do kontrolki i pisać kod w celu zaimplementowania funkcji niestandardowych. W ostatniej sekcji przedstawiono rozszerzanie funkcjonalności danej złożonej kontrolki przez dziedziczenie i zmianę funkcjonalności metod hostów przez zastąpienie tych metod.

Udostępnij za pośrednictwem