KRET LANGUAGE ACADEMY · DOKUMENTACJA ZE ŹRÓDEŁ
Widok, styl i motyw
Czego się nauczysz
- Prześledź źródła i wyjaśnij opisany kontrakt.
- W HelloView przypisz pliki do struktury, stylu i motywu. Odszukaj deklarację tekstu w widoku i jej wynik na zapisanym podglądzie.
Wymagania wstępne
- Ukończ Podstawy i wcześniejszy poziom tej ścieżki.
Wyjaśnienie krok po kroku
KretUI opisuje strukturę widoku, KretStyle wygląd, a KTheme tokeny i warianty. To trzy role jednego stosu interfejsu, nie trzy niezależne uprawnienia. Zapisany obraz podglądu pokazuje wynik określonego źródła i wersji, nie reaguje na edycję w witrynie.
Praca z kodem źródłowym
Pierwszy widok KretUI
Widok `view` z tytułem, stanem (`state`), tekstem z podstawieniem `{licznik}` i przyciskiem, który zmienia stan lokalnie (`set`). Bez logiki KretS — interfejs nie ma żadnych uprawnień. Renderer SDK rysuje prawdziwą klatkę PNG (`--self-test`).
module Main
fn Start() {
}
fn Shutdown() {
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
module MainDeklaracja modułu KretS; porównaj nazwę z nazwą pliku.fn Start() {Sygnatura funkcji: nazwa, argumenty i ewentualny typ wyniku.}Zamknięcie struktury otwartej we wcześniejszych liniach.fn Shutdown() {Sygnatura funkcji: nazwa, argumenty i ewentualny typ wyniku.}Zamknięcie struktury otwartej we wcześniejszych liniach.
Oczekiwany wynik: Lista widoków zawiera `Hello`; self-test kończy się kodem 0 i zapisuje klatkę z tekstem „Dziękuję!…”.
Typowy błąd: Komponent spoza listy renderera (`tooltip`, `menu`, `contextMenu`, `chart`) → `KCS-KUI-0107` (NOT_SUPPORTED w KretUI 1.0).
Instrukcja, wersje i zapisane wyniki →Materiały źródłowe do tego tematu
Przeczytaj powiązane rozdziały. Kod i kontrakty zachowano z importu; historia źródeł jest dostępna przy każdym rozdziale.
KretUI — wprowadzenie
KretUI — wprowadzenie
Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretui-1.0 · kstyle-1.0 · ktheme-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.Czym jest
KretUI opisuje strukturę i interakcje interfejsu (widoki, stan, bindingi, akcje do komend KretS). KretStyle opisuje wygląd (selektory, kaskada, stany, media), KTheme — motyw (tokeny, warianty dark/highContrast, kontrola kontrastu WCAG). Renderer SDK (Avalonia) działa we własnym procesie, logika w procesie pluginu. Interfejs nie nadaje uprawnień i nie przechowuje sekretów.
Dla początkujących
Piszesz, co ma być na ekranie: kolumny, wiersze, teksty, pola, przyciski, listy. Stan widoku (state) trzyma wartości, a przycisk może wywołać akcję — komendę w KretS — i zapisać wynik w stanie. Wygląd ustawiasz osobno w .kstyle, kolory i rozmiary w .ktheme.
Dla zaawansowanych programistów
Akcja = zadeklarowana komenda (on nazwa(...) -> T) z args, result, busy, error; kompilacja sprawdza sygnaturę i blok handlers manifestu. Warunki when/enabled to wyrażenia bez skutków ubocznych (env.*, form.valid, empty, count). Kontrolka wyłączona/niewidoczna/jednokierunkowa nie zmieni stanu (decyduje UiRuntime). pattern kompilowany silnikiem bez nawrotów. Sesja kretui-session/1 (EXPERIMENTAL) dla IDE: przeładowanie, przenoszenie stanu, logika tylko w procesie pluginu; od BRK-12 jeden proces logiki na plugin i katalog danych (STUDIO-R01). Rozszerzenia formularzy results, onBlur, shortcut (łatka 9) — PROPOSED_LOCAL (G-07).
Jakie problemy rozwiązuje
Deklaratywny, bezpieczny interfejs pluginów oddzielony od logiki i uprawnień; dostępność (opisy, kontrast) sprawdzana przy kompilacji; motywy i tryb wysokiego kontrastu.
Kiedy używać
- dashboard, panel ustawień, formularze
- listy i tabele danych z KretDB (przez KretS)
- okna dialogowe i zakładki
- motywy jasny/ciemny/wysoki kontrast
Kiedy nie używać
tooltip,menu,contextMenu,chart(NOT_SUPPORTED,KCS-KUI-0107)- gesty, canvas, animacje, wiele okien/monitorów, kiosk, widżety, profile dashboardów (PLANNED, KretUI 1.x)
- logika w stylu/motywie (błąd „nieznana właściwość”)
- piaskownica renderera — renderer działa z prawami użytkownika
Współpraca z innymi technologiami
KretS (komendy on …), KretL (handlers), KretDB (dane przez KretS), KretStudio (podgląd interaktywny, LSP), Core (plugin ui open, UiProcess).
Obecny status
FROZEN_SUPPORTED_SUBSET — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0.
Dalej: ARCHITECTURE.md · SYNTAX_REFERENCE.md · ../Tutorials/BASIC/TUTORIAL_PL.md
KretUI — referencja składni
KretUI — referencja składni
Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretui-1.0 · kstyle-1.0 · ktheme-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.Opisane są wyłącznie konstrukcje potwierdzone implementacją SDK (i, gdzie zaznaczono, testami tej rundy).
view / state
Widok i jego stan.
view Counter {
title "Licznik: {count}"
width 480
state {
count Int64 0
}
column { … }
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
view Counter {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.title "Licznik: {count}"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.width 480Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.state {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.count Int64 0Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.column { … }Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | title, width, height; zmienne stanu z typem i wartością |
| Wynik | — |
| Wymagania | — |
| Ograniczenia | stan prezentacji ograniczony (łatka 8: 32 pola) |
| Możliwe błędy | KCS-KUI-01xx |
| Wprowadzono | 1.0 |
action / open
Akcja = komenda KretS; open uruchamia akcję przy otwarciu widoku.
action add "notes.add" {
args draft
result items
busy busy
error error
}
open load
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
action add "notes.add" {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.args draftOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.result itemsOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.busy busyOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.error errorOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.open loadOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
| Cecha | Wartość |
|---|---|
| Parametry / typy | args (stan albo literały), result, busy (Bool), error (String) |
| Wynik | wynik komendy → zmienna stanu |
| Wymagania | komenda w handlers manifestu, zgodna sygnatura |
| Ograniczenia | nazwy funkcji ochronnych odrzucane |
| Możliwe błędy | KCS-KUI-* |
| Wprowadzono | 1.0 |
text / input / button
Tekst, pole (walidacja required minLength maxLength pattern type), przycisk (action, set).
input name {
label "Imię"
required true
maxLength 40
}
button "Zapisz" {
action save
enabled "form.valid and not busy"
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
input name {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.label "Imię"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.required trueOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.maxLength 40Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.button "Zapisz" {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.action saveOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.enabled "form.valid and not busy"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | type text|number|email|password |
| Wynik | — |
| Wymagania | — |
| Ograniczenia | brak label/description → ostrzeżenie dostępności KCS-KUI-0108 |
| Możliwe błędy | KCS-KUI-0108 |
| Wprowadzono | 1.0 |
list / table / checkbox / slider / dialog / tabs
Komponenty VERIFIED: list (StringList), table (Rows), checkbox, slider, dialog, tabs+tab, row, column. IMPLEMENTED: switch, progress, image, icon, separator, badge, status, grid, stack, scroll, card, panel.
list items {
label "Notatki"
selected selected
}
dialog confirm {
title "Usunąć?"
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
list items {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.label "Notatki"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.selected selectedOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.dialog confirm {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.title "Usunąć?"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | wg komponentu |
| Wynik | — |
| Wymagania | — |
| Ograniczenia | tabela ≤ 1000 wierszy, bez przewijania własnego |
| Możliwe błędy | KCS-KUI-0107 |
| Wprowadzono | 1.0 |
bind / when / enabled / set
Bindingi oneWay/twoWay/oneTime, warunki widoczności/aktywności, lokalna zmiana stanu.
text "Brak" {
when "empty(items)"
}
button "Otwórz" {
set open true
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
text "Brak" {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.when "empty(items)"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.button "Otwórz" {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.set open trueOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | wyrażenia bez skutków ubocznych |
| Wynik | — |
| Wymagania | — |
| Ograniczenia | set przy akcji wykonuje się po jej powodzeniu |
| Możliwe błędy | KCS-KUI-* |
| Wprowadzono | 1.0 |
KretStyle: style / state / media
Selektory typ .klasa #id typ.klasa *, kaskada wg szczegółowości, stany hover pressed focused disabled loading error success selected, media size|touch|highContrast|reduceMotion.
kstyle "1.0"
style "button.primary, #submit" {
background accent
state hover {
background accentHover
}
}
media size compact {
style "column" {
gap 4px
}
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
kstyle "1.0"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.style "button.primary, #submit" {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.background accentOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.state hover {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.background accentHoverOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.}Zamknięcie struktury otwartej we wcześniejszych liniach.media size compact {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.style "column" {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.gap 4pxOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | właściwości: kolory, długości, padding/margin, opacity, fontWeight, textAlign, align, justify, fontFamily |
| Wynik | — |
| Wymagania | — |
| Ograniczenia | animacje, przejścia, cienie, gradienty — NOT_SUPPORTED |
| Możliwe błędy | KCS-KUI-02xx |
| Wprowadzono | 1.0 |
KTheme: theme / tokens / variant / contrast
Tokeny (kolor, długość, liczba, tekst, alias), warianty nadpisujące tokeny, wymagany kontrast WCAG sprawdzany przy kompilacji.
ktheme "1.0"
theme Notes {
tokens {
surface "#FBFBFD"
text "#1A1C22"
}
variant dark {
surface "#17181C"
text "#ECEDF1"
}
contrast text surface 7
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
ktheme "1.0"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.theme Notes {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.tokens {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.surface "#FBFBFD"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.text "#1A1C22"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.variant dark {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.surface "#17181C"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.text "#ECEDF1"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.contrast text surface 7Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | — |
| Wynik | — |
| Wymagania | warianty mają ten sam zestaw nazw |
| Ograniczenia | za mały kontrast = błąd KCS-KUI-0305 (sprawdzone w tej rundzie); extends między plikami — NOT_SUPPORTED |
| Możliwe błędy | KCS-KUI-0305, KCS-KUI-03xx |
| Wprowadzono | 1.0 |
KretUI — samouczek BASIC
KretUI — samouczek BASIC
Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretui-1.0 · kstyle-1.0 · ktheme-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.Cel: pierwszy plik, podstawowa struktura, najprostszy działający przykład, najczęstszy błąd, sposób uruchomienia.
Narzędzia: kret = <SDK>\Compiler\kret.exe (SDK 1.0.0-rc.3+kret.local.3), kretui-host = <SDK>\UiHost\kretui-host.exe. {DATA}/{OUT} = nowe, puste katalogi.
1. Pierwszy widok KretUI (KRETUI-B01-HelloView)
Projekt: ../../Examples/BASIC_HelloView/ · klasyfikacja RUNNABLE_LOCAL · Playground LOCAL_EXECUTE
Kroki (katalog roboczy: katalog przykładu):
kret check . --json— w wyniku:"succeeded": truekretui-host . --list-views— w wyniku:Hellokretui-host . --self-test {OUT}/frame --data {DATA} --policy host-policy.json --click 0/3
Wynik tej rundy: PASS — zob. EXPECTED_OUTPUT.txt.
Ćwiczenie i sprawdzenie wiedzy
W HelloView przypisz pliki do struktury, stylu i motywu. Odszukaj deklarację tekstu w widoku i jej wynik na zapisanym podglądzie.
Szkic nie jest wysyłany na serwer i znika po opuszczeniu lekcji. Przed wyjściem możesz go skopiować.Podpowiedzi
- KretUI opisuje strukturę i interakcje interfejsu (widoki, stan, bindingi, akcje do komend KretS). KretStyle opisuje wygląd (selektory, kaskada, stany, `media`), KTheme — motyw (tokeny, warianty `dark`/`highContrast`, kontrola kontrastu WCAG). Renderer SDK (Avalonia) działa we własnym procesie, logika w procesie pluginu. Interfejs nie nadaje uprawnień i nie przechowuje sekretów.
- Odczytaj ograniczenia i oczekiwane błędy z dostarczonego samouczka; check i run są oddzielnymi krokami.
Omówienie rozwiązania
Odpowiedź oprzyj na pokazanym kodzie i rozdziale źródłowym. KretUI opisuje strukturę widoku, KretStyle wygląd, a KTheme tokeny i warianty. To trzy role jednego stosu interfejsu, nie trzy niezależne uprawnienia. Zapisany obraz podglądu pokazuje wynik określonego źródła i wersji, nie reaguje na edycję w witrynie.
Podsumowanie i następny krok
KretUI opisuje strukturę widoku, KretStyle wygląd, a KTheme tokeny i warianty. To trzy role jednego stosu interfejsu, nie trzy niezależne uprawnienia. Zapisany obraz podglądu pokazuje wynik określonego źródła i wersji, nie reaguje na edycję w witrynie.
Zaloguj się na konto użytkownika, aby zapisywać postęp i zakładki. Konta obsługi mogą czytać bez zapisu postępu. Logowanie →