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

Po co się tego uczymy?

Kontrolki to podstawowe elementy interfejsu — przyciski, pola tekstowe, obrazy. Ta lekcja dogłębnie omawia pięć najczęściej używanych kontrolek MAUI razem z PEŁNYM zestawem ich właściwości — nie tylko "rzuca hasłem", żebyś wiedział dokładnie, jakie opcje ma każda z nich, zanim zobaczysz ją w zadaniu egzaminacyjnym.

Teoria

Label — wyświetlanie statycznego tekstu

Właściwość	Opis
`Text`	Treść etykiety — co ma być wyświetlane.
`FontSize`	Rozmiar czcionki — szybka kontrola hierarchii nagłówków.
`TextColor`	Kolor tekstu — kontrast i dostępność.
`LineBreakMode`	Sposób łamania tekstu (np. `WordWrap`) — zapobiega "wychodzeniu" tekstu poza ekran.
`MaxLines`	Maksymalna liczba wierszy — przycina długie opisy.
`HorizontalOptions` / `VerticalOptions`	Wyrównanie w layoucie — porządkuje układ bez dodatkowych kontenerów.

Entry — pole tekstowe jednowierszowe

Do krótkich danych: login, e-mail, hasło, liczby.

Właściwość	Opis
`Placeholder`	Szary tekst-podpowiedź, gdy pole jest puste — prowadzi użytkownika.
`Text`	Aktualna zawartość pola — stąd później odczytujesz wpisane dane.
`IsPassword`	Ukrywa wpisywane znaki — używaj w polach z hasłem.
`Keyboard`	Dobiera typ klawiatury (np. `Email`, `Numeric`) — przyspiesza wpisywanie i zmniejsza liczbę błędów.
`MaxLength`	Ogranicza maksymalną długość wpisywanego tekstu.
`ClearButtonVisibility`	Pokazuje przycisk "X" do czyszczenia pola — lepsza ergonomia na urządzeniu dotykowym.
`IsReadOnly`	Blokuje edycję przy zachowaniu wyglądu — przydatne przy podglądzie danych.

Editor — pole tekstowe wielowierszowe

Do dłuższych treści: komentarze, opisy, notatki.

Właściwość	Opis
`Text`	Wpisany tekst — do odczytu/zapisu treści.
`Placeholder`	Podpowiedź zwiększająca zrozumiałość pola.
`AutoSize`	Ustawione na `TextChanges` automatycznie dopasowuje wysokość pola do ilości tekstu.
`HeightRequest`	Minimalna wysokość startowa, zanim AutoSize zacznie działać.
`IsReadOnly`	Blokuje edycję — np. w trybie przeglądania.
`Keyboard`	Np. `Chat`, `Text` — dobiera układ klawiatury do rodzaju treści.

Button — przycisk

Właściwość	Opis
`Text`	Podpis na przycisku — komunikat akcji.
`BackgroundColor` / `TextColor`	Kolory przycisku — kontrast i branding.
`ImageSource`	Ikona wewnątrz przycisku — szybsza percepcja akcji.
`ContentLayout`	Pozycja ikony względem tekstu (np. `Left,8`) — estetyka i ergonomia.
`CornerRadius`	Zaokrąglenie rogów — nowoczesny wygląd zgodny ze stylem mobile.
`Clicked`	Zdarzenie wywoływane po kliknięciu — pełne omówienie w osobnej lekcji o zdarzeniach.

Image — wyświetlanie grafiki

Właściwość	Opis
`Source`	Plik lokalny (z `Resources/Images`), URL albo zasób — podstawowe źródło obrazu.
`Aspect`	`AspectFit`/`Fill`/`AspectFill` — kontrola przycięcia względem zachowania proporcji.
`WidthRequest` / `HeightRequest`	Sugerowane wymiary — stabilny, przewidywalny układ.
`Opacity`	Przezroczystość — np. przydatne pod nałożony tekst na banerze.

Schemat

Piec podstawowych kontrolek - do czego kazda sluzy:

Label   -> wyswietla TYLKO tekst (bez edycji)
Entry   -> JEDNA linia wpisywanego tekstu (login, e-mail, haslo)
Editor  -> WIELE linii wpisywanego tekstu (komentarz, notatka)
Button  -> wyzwala AKCJE po dotknieciu
Image   -> wyswietla GRAFIKE (logo, zdjecie, ikona)

Przykład z życia

Formularz logowania w dowolnej aplikacji bankowej to dokładnie te kontrolki w akcji: Image z logo banku na górze, Label z instrukcją, dwa pola Entry (login i hasło z IsPassword="True"), i na końcu Button "Zaloguj się".

LogowaniePage.xaml

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="KontrolkiApp.LogowaniePage">

    <VerticalStackLayout Padding="24" Spacing="16">

        <Image 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>

LogowaniePage.xaml.cs

namespace KontrolkiApp;

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;
    }
}

Komentarz i wyjaśnienie kodu

Strona łączy wszystkie pięć kontrolek z tej lekcji: Image z logo, Label jako nagłówek, dwa pola Entry (jedno z klawiaturą Email, drugie z ukrytymi znakami hasła), Editor na opcjonalne uwagi (wielowierszowy, więc nadaje się na dłuższy tekst) i Button z zaokrąglonymi rogami wywołujący metodę logowania.

W code-behind metoda OnZalogujClicked sprawdza, czy oba wymagane pola są wypełnione (string.IsNullOrWhiteSpace) — jeśli nie, wyświetla czerwony komunikat błędu w EtykietaStatus, a jeśli tak, zielone powitanie. To bardzo częsty, minimalny wzorzec walidacji formularza w MAUI, do którego wrócimy szerzej w lekcji o modelach i walidacji.

Ćwiczenie samodzielne

Utwórz nową stronę ContentPage z powyższym kodem (możesz użyć dowolnego obrazka jako logo.png w Resources/Images, albo tymczasowo usunąć Image, jeśli nie masz pliku). Uruchom na emulatorze, sprawdź działanie walidacji — spróbuj kliknąć "Zaloguj" z pustymi polami, a potem z wypełnionymi.

Zadania do pracy własnej

Dodaj do formularza logowania trzecie pole Entry z numerem telefonu (Keyboard="Telephone").
Dodaj do przycisku "Zaloguj" ikonę (ImageSource) i ustaw ContentLayout, żeby ikona była po lewej stronie tekstu z odstępem 8 pikseli.
Zbuduj ekran 'Kontakt z nami': Image (logo firmy), Entry na imię i e-mail, Editor na treść wiadomości (min. HeightRequest 150 z AutoSize), Button 'Wyślij' który sprawdza czy WSZYSTKIE trzy pola są wypełnione (w tym Editor), a jeśli e-mail nie zawiera znaku '@' — pokazuje osobny komunikat błędu walidacji formatu.

Typowe błędy

Używanie Entry zamiast Editor do dłuższego tekstu — Entry jest jednowierszowe; próba wpisania dłuższego komentarza w Entry sprawia, że tekst przewija się w bok zamiast zawijać.

Zapominanie o IsPassword przy polu hasła — bez tej właściwości hasło wyświetla się jawnym tekstem, co jest zarówno błędem funkcjonalnym, jak i poważnym problemem bezpieczeństwa/prywatności.

Brak dopasowanej klawiatury (Keyboard) — pole na e-mail bez Keyboard="Email" pokaże zwykłą klawiaturę tekstową zamiast klawiatury z symbolem "@" — drobny, ale zauważalny minus UX.

Zbyt duży obrazek bez ograniczenia wymiarów — brak WidthRequest/HeightRequest na Image może sprawić, że duże zdjęcie zajmie cały ekran, spychając resztę formularza poza widok.

Nawiązanie do egzaminu zawodowego

To realizacja INF.04.6.2 — "programuje aplikacje mobilne... elementy UI (przyciski, formularze)". Label, Entry, Editor, Button i Image to absolutny fundament każdego ekranu z formularzem — pojawią się w niemal każdym kolejnym zadaniu tego działu.