Kontrolki I — Label, Entry, Editor, Button, Image

Zobacz, zanim zaczniesz

Pięć kontrolek na czterech ekranach

Każdy ekran to podgląd z kodu XAML. Poniżej poznasz kontrolki jedna po drugiej, a każdą sprawdzisz w wyzwaniu.

Laboratorium · ćwiczenie w przeglądarce, do którego odsyłają rozgrzewki na końcu lekcji

Zacznij od zabawy

Ekran logowania z walidacją

Kliknij „Zaloguj” z pustymi polami, a potem wpisz login i hasło. W zakładce .xaml.cs zmień komunikat albo warunek walidacji i zobacz skutek.

Najpierw przewidź, potem sprawdź: W podglądzie porównaj puste dane z wpisanym loginem. Zwróć uwagę na zmianę tekstu i koloru komunikatu. To demonstracja formularza, nie prawdziwe logowanie do serwera.

To minimalny wzorzec walidacji w MAUI: string.IsNullOrWhiteSpace, komunikat w kolorze (czerwony lub zielony) i return przy błędzie. Model pomaga zobaczyć mechanizm; właściwą aplikację uruchomisz z plików poniżej.

Etap 1 z 5

Label: tekst, którego nie edytujesz

Label pokazuje tekst. Hierarchię budujesz rozmiarem (FontSize), pogrubieniem (FontAttributes) i kolorem. Długi opis przycinasz właściwościami MaxLines i LineBreakMode.

2 · Tekst

Label: statyczny tekst

Właściwość	Opis
`Text`	Treść etykiety.
`FontSize`	Rozmiar czcionki, szybka kontrola hierarchii nagłówków.
`TextColor`	Kolor tekstu, ważny dla kontrastu i dostępności.
`LineBreakMode`	Sposób łamania tekstu (np. `WordWrap`), aby tekst nie wychodził poza ekran.
`MaxLines`	Maksymalna liczba wierszy. Przycina długie opisy.
`HorizontalOptions` / `VerticalOptions`	Wyrównanie w układzie, bez dodatkowych kontenerów.

Napis ustawiasz w `Text`. W MAUI tak samo jest w `Button` i `Entry`.

Wyzwanie 1 · tekst

Tytuł i przycięty opis

Sprawdź, czy zapamiętałeś

Jedno szybkie pytanie

Etap 2 z 5

Entry: krótkie dane od użytkownika

Entry to pole jednowierszowe: login, e-mail, hasło, liczba. Dobra klawiatura i podpowiedź (Placeholder) zmniejszają liczbę pomyłek, a IsPassword chroni hasło przed oczami postronnych.

3 · Pole jednowierszowe

Entry: krótkie dane

Właściwość	Opis
`Placeholder`	Szara podpowiedź widoczna, gdy pole jest puste.
`Text`	Aktualna zawartość. Stąd odczytasz wpisane dane.
`IsPassword`	Ukrywa wpisywane znaki. Używaj w polach z hasłem.
`Keyboard`	Typ klawiatury: `Email`, `Numeric`, `Telephone`, `Text`. Przyspiesza wpisywanie i zmniejsza liczbę błędów.
`MaxLength`	Ogranicza długość wpisywanego tekstu.
`ClearButtonVisibility`	Przycisk „X” do czyszczenia pola, wygodny na ekranie dotykowym.
`IsReadOnly`	Blokuje edycję przy zachowaniu wyglądu.

Do krótkich danych: login, e-mail, hasło, liczby. Do dłuższych treści użyj `Editor`.

Wyzwanie 2 · pola

E-mail, hasło i telefon

Wyzwanie 3 · cudzy kod

Formularz kontaktowy kolegi

Sprawdź, czy zapamiętałeś

Dwa szybkie pytania

Etap 3 z 5

Editor: pole na dłuższy tekst

Komentarze, opisy i wiadomości to kilka zdań, więc Entry się do nich nie nadaje. Używasz Editor: ma wiele wierszy, a z AutoSize="TextChanges" rośnie razem z tekstem.

4 · Pole wielowierszowe

Editor: dłuższe treści

Właściwość	Opis
`Text`	Wpisany tekst.
`Placeholder`	Podpowiedź w pustym polu.
`AutoSize="TextChanges"`	Wysokość dopasowuje się do ilości tekstu.
`HeightRequest`	Minimalna wysokość startowa, zanim zadziała `AutoSize`.
`IsReadOnly`	Blokada edycji, np. w trybie przeglądania.
`Keyboard`	Np. `Chat` lub `Text`, układ klawiatury dopasowany do treści.

Komentarze, opisy, notatki, wiadomości: zawsze `Editor`, nie `Entry`.

Wyzwanie 4 · opinia

Pole na opinię

Etap 4 z 5

Button i Image: akcja i obraz

Button wywołuje akcję przez zdarzenie Clicked. Image pokazuje grafikę. Bez WidthRequest i HeightRequest duży obraz zajmie cały ekran i wypchnie resztę formularza, a Aspect decyduje, czy obraz zostanie przycięty, czy zmieści się w całości.

5 · Akcja i grafika

Button i Image

Kontrolka	Właściwość	Opis
`Button`	`Text`	Podpis na przycisku.
`Button`	`BackgroundColor` / `TextColor`	Kolory przycisku.
`Button`	`ImageSource`	Ikona wewnątrz przycisku.
`Button`	`ContentLayout`	Położenie ikony względem tekstu, np. `Left,8`.
`Button`	`CornerRadius`	Zaokrąglenie rogów.
`Button`	`Clicked`	Zdarzenie kliknięcia.
`Image`	`Source`	Plik z `Resources/Images`, adres URL lub zasób.
`Image`	`Aspect`	`AspectFit`, `Fill` lub `AspectFill`: przycięcie kontra proporcje.
`Image`	`WidthRequest` / `HeightRequest`	Sugerowane wymiary, stabilny układ.
`Image`	`Opacity`	Przezroczystość.

Obraz bez ograniczonych wymiarów może zająć cały ekran i wypchnąć resztę formularza poza widok.

Wyzwanie 5 · czytanie kodu

Który przycisk zobaczysz?

Sprawdź, czy zapamiętałeś

Dwa szybkie pytania

Etap 5 z 5

Przycisk coś robi: walidacja w C#

Przycisk wywołuje metodę z pliku .xaml.cs. W niej sprawdzasz, czy pole jest uzupełnione, i pokazujesz komunikat. Po błędzie kończysz metodę przez return;, żeby dalsza część się nie wykonała.

Wyzwanie 6 · logika

Ułóż metodę walidacji

Wyzwanie końcowe

Ekran logowania

Sprawdź, czy zapamiętałeś

Cztery pytania z całej lekcji

9 · Sprawdź się

Którą kontrolkę i właściwość?

Cztery sytuacje z formularzem.

Dla chętnych · po pierwszej stronie

Pracownia w Visual Studio: to samo w prawdziwym projekcie

Rozwiń dodatkowe warsztaty ↓

Wyzwania powyżej uczą w przeglądarce. Tu jest pełna instrukcja krok po kroku, jak zrobić to w Visual Studio i uruchomić na emulatorze, tak jak na egzaminie praktycznym. Otwórz, gdy będziesz gotowy do pracy z projektem.

1. Przygotuj miejsce pracy

W Visual Studio wybierz Utwórz nowy projekt → .NET MAUI App, nie MAUI Blazor Hybrid. Nazwij projekt MojaAplikacja, żeby namespace pasował do przykładów. Każdy temat możesz robić w osobnym katalogu, nawet gdy nazwa projektu się powtarza.
Wybierz .NET10 i najpierw uruchom niezmieniony szablon na Windows Machine. Gdy masz działające środowiskoAndroid, później wybierz własne urządzenie lub emulator.
Zatrzymaj debugowanie przed dodawaniem klas i zmianą sposobu startu. Zachowaj App.xaml, Resources i pliki platform z szablonu.

Co dodajesz, a co podmieniasz?

Stronę dodaj przez Projekt → Dodaj → Nowy element → .NET MAUI ContentPage (XAML). Powstaje para .xaml i .xaml.cs. Dla ContentView wybierz szablon ContentView; dla modeli i serwisów zwykłą klasę. Jeśli plik już istnieje, podmień wskazaną zawartość — nie twórz drugiej klasy o tej samej nazwie.

Plik	Rola w ćwiczeniu
LogowaniePage.xaml	Wygląd strony lub kontrolki
LogowaniePage.xaml.cs	Logika i obsługa danych
LogowaniePage.xaml.cs — dopisz metodę	Fragment w istniejącym pliku

Zanim uruchomisz: trzy połączenia

x:Class="MojaAplikacja.NazwaStrony" w XAML musi zgadzać się z namespace MojaAplikacja i nazwą klasy C#. InitializeComponent() tworzy kontrolki opisane w XAML.

x:Name="PoleImie" daje kodowi C# dostęp przez PoleImie.Text. Z kolei Clicked="Zapisz_Clicked" wskazuje metodę o tej nazwie w pliku .xaml.cs. Sam napis przycisku w Text niczego nie podpina.

Gdy dodajesz XAML z obsługą zdarzeń, od razu uzupełnij też odpowiadający C#. Uruchamiaj dopiero po skończeniu oznaczonej pary plików; brakujący handler nie jest błędem środowiska.

2. Uruchom sam wygląd — jeszcze bez logiki

W świeżym projekcie zastąp MainPage.xaml poniższym ekranem. W MainPage.xaml.cs zachowaj konstruktor z InitializeComponent(); usuń szablonowy licznik i OnCounterClicked, bo nie ma ich już w XAML. Na tym etapie App i AppShell pozostają z szablonu. To pełny, tymczasowy XAML — później świadomie go podmienisz, nie dokleisz do drugiego ContentPage.

MainPage.xaml — etap tymczasowyxaml

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MojaAplikacja.MainPage">
    <VerticalStackLayout Padding="24" Spacing="14">
        <Label Text="Napisz do nas" FontSize="24" />
        <Entry Placeholder="Twój login" />
        <Editor Placeholder="Dłuższa wiadomość" HeightRequest="120" />
    </VerticalStackLayout>
</ContentPage>

Pierwsza próba Uruchom. Zobaczysz kontrolki, ale przyciski bez Clicked jeszcze nic nie robią. Sprawdź rozmiar i kolejność elementów. Zatrzymaj aplikację przed następnym etapem.

3. Wskaż stronę startową ćwiczenia

Po dodaniu docelowych stron podmień App.xaml.cs na poniższy. App.xaml zostaje z szablonu. Od tej chwili startuje LogowaniePage, a nie wcześniejszy tymczasowy MainPage z AppShell. Uzupełnij jej pliki w kolejnych etapach, zanim ponownie uruchomisz projekt.

App.xaml.cscsharp

namespace MojaAplikacja;

public partial class App : Application
{
    public App() => InitializeComponent();
    protected override Window CreateWindow(IActivationState? activationState)
        => new Window(new NavigationPage(new LogowaniePage()));
}

CreateWindow Tworzy okno aplikacji. NavigationPage jest kontenerem zwykłych stron i daje przycisk powrotu; nie łączymy go z Shell.
new LogowaniePage() Tworzy instancję docelowej strony. Aby testować drugi niezależny przykład, zatrzymaj program, zmień tylko ten typ i uruchom ponownie.

4. Połącz wygląd z działaniem

Teraz zbuduj docelowy przykład. Pełne pliki poniżej zastępują swoje wcześniejsze wersje. Przeczytaj opis nad kodem i objaśnienia pod nim; potem sprawdź przepływ danych, nie tylko brak czerwonych podkreśleń.

Gdy przykład ma kilka plików zależnych od siebie, najpierw dodaj wszystkie wskazane typy, a potem uruchom całość. Ustaw breakpoint w obsłudze głównego przycisku i prześledź jedną próbę.

Budowa krok po kroku

LogowaniePage.xaml

Dodaj LogowaniePage. Plik logo.png musi istnieć w Resources/Images jako MauiImage; na pierwszą próbę możesz użyć dotnet_bot.png z szablonu. Entry jest jednoliniowy, Editor służy dłuższemu tekstowi.

Wszystkie pięć kontrolek na jednej stronie.

LogowaniePage.xamlxaml

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MojaAplikacja.LogowaniePage">
    <VerticalStackLayout Padding="24" Spacing="16">

        <Image x:Name="LogoImage" Source="logo.png"
               Aspect="AspectFit"
               WidthRequest="120"
               HeightRequest="120"
               HorizontalOptions="Center" />

        <Label Text="Zaloguj się do konta"
               FontSize="22"
               HorizontalOptions="Center" />

        <Entry x:Name="PoleLogin"
               Placeholder="Login lub e-mail"
               Keyboard="Email"
               ClearButtonVisibility="WhileEditing" />

        <Entry x:Name="PoleHaslo"
               Placeholder="Hasło"
               IsPassword="True" />

        <Editor x:Name="PoleUwagi"
                Placeholder="Uwagi (opcjonalnie)"
                AutoSize="TextChanges"
                HeightRequest="80" />

        <Button Text="Zaloguj"
                BackgroundColor="RoyalBlue"
                TextColor="White"
                CornerRadius="12"
                Clicked="OnZalogujClicked" />

        <Label x:Name="EtykietaStatus" HorizontalOptions="Center" />

    </VerticalStackLayout>
</ContentPage>

Image Source="logo.png" Aspect="AspectFit" Logo z Resources/Images z zachowaniem proporcji. Bez pliku obrazek się nie pokaże, więc w ćwiczeniu możesz go wstawić lub usunąć.
Entry Keyboard="Email" Na telefonie pojawi się klawiatura z @.
ClearButtonVisibility="WhileEditing" Przycisk „X” widoczny tylko podczas edycji.
Editor AutoSize="TextChanges" Pole rośnie wraz z tekstem.
Button CornerRadius="12" Zaokrąglone rogi, nowoczesny wygląd mobilny.

Budowa krok po kroku

LogowaniePage.xaml.cs

Prześledź: odczyt pól → Trim → odrzucenie pustych danych → komunikat. Kontrola nie łączy się z bazą ani serwerem.

Metoda sprawdza oba wymagane pola. Przy błędzie pokazuje czerwony komunikat i kończy działanie, a przy sukcesie zielone powitanie.

LogowaniePage.xaml.cscsharp

namespace MojaAplikacja;

public partial class LogowaniePage : ContentPage
{
    public LogowaniePage()
    {
        InitializeComponent();
    }

    private void OnZalogujClicked(object sender, EventArgs e)
    {
        string? login = PoleLogin.Text?.Trim();
        string? haslo = PoleHaslo.Text;

        if (string.IsNullOrWhiteSpace(login) || string.IsNullOrWhiteSpace(haslo))
        {
            EtykietaStatus.Text = "Uzupełnij login i hasło.";
            EtykietaStatus.TextColor = Colors.Red;
            return;
        }

        EtykietaStatus.Text = $"Witaj, {login}!";
        EtykietaStatus.TextColor = Colors.Green;
    }
}

PoleLogin.Text?.Trim() Operator ?. chroni przed null, a Trim() usuwa spacje z krańców.
string.IsNullOrWhiteSpace(login) Odrzuca pole puste lub z samymi spacjami.
EtykietaStatus.TextColor = Colors.Red Kolor komunikatu zależy od wyniku walidacji.
return; Kończy metodę po błędzie, więc kod powitania się nie wykona.

Zatrzymaj się przed kolejnym wariantem

Nie zastępuj jeszcze działającej wersji. Wykonaj tę próbę i dopiero potem przejdź do dodatku.

Puste pola dają komunikat o brakujących danych. Sam ciąg spacji też jest pustą wartością po Trim.
Zapisz działającą wersję projektu. Kolejny wariant ma własne pliki lub zastępuje jawnie wskazany plik; nie mieszaj dwóch implementacji tej samej klasy.

Dopiero teraz: drugi wariant lub rozszerzenie

To następny etap tej lekcji, nie warunek pierwszego uruchomienia. Porównaj jego rolę z działającą bazą. Jeśli brakuje czasu, wróć do niego po sprawdzeniu podstawowej wersji.

Dodatek do działającej wersji

Zmień obraz po kliknięciu

Dodatek po działającym formularzu. Dopisz tę metodę wewnątrz klasy LogowaniePage oraz Button z Clicked="OnZmienObrazClicked" w jej stosie. Dodaj logo_drugie.png do Resources/Images. Sam handler bez przycisku nie uruchomi się.

Dodaj obok obrazu przycisk z Clicked="OnZmienObrazClicked". W Resources/Images umieść własne logo.png i logo_drugie.png z akcją MauiImage; małe litery i podkreślenie. Nazwa w kodzie musi odpowiadać zasobowi. Dla SVG podajesz w Source wynikowe rozszerzenie .png. To przypisanie właściwości, nie wybór zdjęcia z dysku.

LogowaniePage.xaml.cs — dopisz metodęcsharp

private void OnZmienObrazClicked(object sender, EventArgs e)
{
    LogoImage.Source = "logo_drugie.png";
}

LogoImage.Source = "logo_drugie.png"; Zdarzenie zmienia źródło istniejącego Image. Wcześniej obraz miał nazwę z x:Name.

5. Odbiór: czy naprawdę działa?

Wykonaj próby w swojej aplikacji, nie tylko w modelu na stronie. Zaznaczaj dopiero po sprawdzeniu wyniku. Funkcje urządzenia wymagają testu na właściwej platformie.

Puste pola dają komunikat o brakujących danych. Sam ciąg spacji też jest pustą wartością po Trim.
Po wpisaniu danych pojawia się komunikat demonstracyjny; nie oznacza on sprawdzenia konta w bazie.
Dopiero w dodatku dodaj drugie zdjęcie i przycisk zmiany. Sprawdź nazwę pliku i akcję MauiImage.

8 · Czego unikać

Cztery błędy z kontrolkami

`Entry` do długiego tekstu

Tak nie

<Entry Placeholder="Twoja wiadomość" />

Tekst przewija się w bok zamiast zawijać się do kolejnych linii.

Tak

<Editor Placeholder="Twoja wiadomość" AutoSize="TextChanges" />

Entry jest jednowierszowe, a Editor wielowierszowe.

Brak `IsPassword` w polu hasła

Tak nie

<Entry Placeholder="Hasło" />

Hasło wyświetla się jawnym tekstem: błąd funkcjonalny i poważny problem prywatności.

Tak

<Entry Placeholder="Hasło" IsPassword="True" />

IsPassword zastępuje znaki kropkami.

Brak dopasowanej klawiatury

Tak nie

<Entry Placeholder="E-mail" />

Zwykła klawiatura bez znaku @, zauważalny minus UX.

Tak

<Entry Placeholder="E-mail" Keyboard="Email" />

Klawiatura dopasowana do danych przyspiesza wpisywanie i zmniejsza liczbę błędów.

Obraz bez ograniczenia wymiarów

Tak nie

<Image Source="duze_zdjecie.png" />

Duże zdjęcie zajmuje cały ekran i spycha resztę formularza.

Tak

<Image Source="duze_zdjecie.png" WidthRequest="120" HeightRequest="120" Aspect="AspectFit" />

WidthRequest i HeightRequest stabilizują układ.

Ćwiczenie z pomocą · samodzielna praca

6. Mała zmiana, którą zrobisz samodzielnie

Dodaj przycisk Wyczyść, który opróżnia login, hasło i komunikat.

Oczekiwany rezultat

Dodaj przycisk Wyczyść, który opróżnia login, hasło i komunikat.
Dotychczasowe działanie ma pozostać poprawne.

Potrzebujesz pomocy? Rozwiązuj krok po kroku.

Krok 1 — pokaż podpowiedź

Dodaj Button z nowym Clicked="OnWyczyscClicked".

Krok 2 — pokaż podpowiedź

W odpowiadającej metodzie ustaw Text trzech nazwanych kontrolek na pusty napis.

Krok 3 — pokaż podpowiedź

Nie twórz drugiej klasy LogowaniePage; dopisz metodę wewnątrz istniejącej.

Otwórz tylko tyle podpowiedzi, ile potrzebujesz. Po każdym kroku wróć do zadania i sprawdź wynik.

Podsumowanie

Co warto zapamiętać

Label pokazuje tekst (Text, FontSize, TextColor). Entry to jedna linia, Editor wiele.
W Entry: Placeholder, IsPassword, Keyboard, MaxLength, ClearButtonVisibility.
Button: Text, kolory, ImageSource, ContentLayout, CornerRadius, zdarzenie Clicked.
Image: Source, Aspect, WidthRequest i HeightRequest, Opacity.
Walidację zaczynasz od string.IsNullOrWhiteSpace, a po błędzie wychodzisz przez return.

Dalej na swoim koncie

Rozgrzewki, quiz i zadania są w biurku ucznia.

Teoria jest otwarta dla wszystkich. Żeby rozwiązywać zadania, zapisywać szkice i widzieć swój postęp, zaloguj się.

Zaloguj się →