Polja obrazca: osnove
Nazaj: predstavitveni pregled
Vseh osem kategorij polj obrazca si deli isto pogodbo: iste $opts, isti izris in isti videz – razlikuje se le gradnik sam.
1. Pregled in namen
Stanje: [Live] – skupna pogodba, ki jo predpostavlja vseh osem strani kategorij, namesto da bi jo vsaka ponavljala posebej.
Opredeli skupno pogodbo $opts, ustvarjen izris in videz, ki naj si
ga deli vsaka od osmih kategorij polj obrazca
(Button, Calendar,
CheckBox, ComboBox, DateTime, Dropdown, ListEditor, ProgressBar).
2. Predpogoji
Nobenih onkraj obstoječe pogodbe Helper-API – ista konvencija ubega/izrisa.
3. Pojmi
En besednjak za »polje« v celotni knjižnici: naslonjen na že
[Live] shemo vrstic
propertyGrid()
(enaka imena za required/state/stateText).
Nativni elementi obrazca, brez lastnega motorja: kontrolnik je
vedno nativen HTML-element obrazca z ustreznim type/input mode
– nobeno polje te družine kategorij si ne gradi lastnega mehanizma za
tipkovnico in fokus (isto načelo kot pri dataGrid(), glejte
layout →
Mehanika postavitve). JavaScript sme dodati vedenje (pojavno okno
izbirnika datuma, iskalni filter v spustnem seznamu, …), nikoli
nadomestiti nativne semantike – to je rezervni način brez JS vsake
kategorije.
4. Prvi koraki
echo $widgets->checkbox([ 'name' => 'aktivno', 'label' => 'Dostop aktiven', 'value' => true, ]);
5. Uporaba
| Primer uporabe | Vzorec |
|---|---|
| Posamezno polje zunaj mreže (iskalna vrstica, filter orodne vrstice) | ena kategorijska metoda te skupine |
| Več polj kot obrazec ali inšpektor lastnosti | propertyGrid() s kategorijskim izrisom kot controlHtml na vrstico – z 'bare' => true kategorijska metoda priskrbi le kontrolnik, ne ovoja .wk-field (oznako/namig/stanje takrat prevzame vrstica mreže) |
6. API referenca: skupna pogodba $opts
| Ključ | Tip | Pomen |
|---|---|---|
name | string | ime polja obrazca (obvezno – vsako polje je nativen element obrazca) |
value | mixed | začetna vrednost, tipsko specifična po kategoriji |
label | string | vidna oznaka (ubežana prek hsc()) |
hint | string | izbirno pomožno besedilo pod kontrolnikom |
required | bool | rdeča zvezdica na oznaki; dodatno nastavi nativni atribut required na kontrolniku (drugače kot pri propertyGrid(), kjer klicatelj sam nastavi atribut – tu ni ločenega controlHtml, polje samo izriše kontrolnik) |
disabled | bool | nativni atribut disabled |
state | 'error'|'warning' | 3px poudarjen trak, enak videz kot vrstice propertyGrid() |
stateText | string | besedilo sporočila pod kontrolnikom pri aktivnem state |
ariaLabel | string | rezervna oznaka, kadar label ostane prazna (različice samo z ikono) |
id | string | izrecen ID kontrolnika; brez navedbe deterministično izpeljan iz name (wkf-<name> – stabilen med izrisi, za label[for]/aria-describedby) |
bare | bool | priskrbi le kontrolnik brez ovoja .wk-field – za vdelavo kot controlHtml v vrstice propertyGrid() |
stackBelow | int (px) | oznaka se prevrne nad kontrolnik pod to širino vsebnika (scripts/adaptive.js) – Adaptivity |
7. Parametri, možnosti in stanja: ustvarjen izris
<div class="wk-field" data-wk-field="<name>"> →
<label class="wk-field__label" for="<id>"> (+
<span class="wk-field__required"> pri required) →
kategorijsko specifičen kontrolnik (nativen <input>/<select>/
<textarea> – brez lastnega elementa brez nativnega
ustreznika) → izbirno <p class="wk-field__hint"> → izbirno
<p class="wk-field__statetext"> pri aktivnem state.
Videz: vsa polja sledijo metriki obrazcev Fluent
(_admin-forms.css, glej
FluentUI: skrbniško območje podrobno): oznaka majhna/
polkrepka/umirjena, višina/polmer/fokusni obroč kontrolnika enak
obstoječim administratorskim obrazcem, stanje napake prek
--wk-error, stanje opozorila prek --wk-warning
(žetoni pogodbe, enaki kot pri vrsticah propertyGrid()).
8. Popolni primeri
echo $widgets->dateTime([ 'name' => 'nacrtovano_od', 'label' => 'Načrtovano od', 'required' => true, 'hint' => 'Format: DD.MM.LLLL HH:MM', ]);
9. Omejitve in robni primeri
- Skupna pogodba velja kot minimalna pogodba; vsaka stran kategorije lahko doda dodatne, kategorijsko specifične ključe.
10. Dostopnost in združljivost
Celoten pregled: Accessibility (konsolidirano, tu ni podvojeno).
11. Odpravljanje težav
Se ne uporablja – brez opaznega primera napake onkraj skupne pogodbe.
12. Sorodne teme
- predstavitveni pregled – vsaka kategorija
- FluentUI: Vertical Grid (Property Grid) – predstavitveni pregled – shema vrstic, iz katere je ta pogodba privzeta
- Polja obrazca: Accessibility – celoten pregled ARIA/tipkovnice
Skupni atributi kontrolnikov
Ti ključi delujejo v vsakem polju družine, ker so v skupnem graditelju atributov:
| Ključ | Tip | Učinek |
|---|---|---|
readonly | bool | readonly + aria-readonly=„true“ |
placeholder | string | placeholder |
maxLength | int | maxlength (le pri vrednostih > 0) |
pattern | string | pattern |
autocomplete | string | autocomplete |
disabled in readonly nista zamenljiva. Brskalnik polja disabled ne pošlje,
polje readonly pa. Obrazec, ki želi izpeljano vrednost le prikazati in jo nespremenjeno zapisati
nazaj, jo z disabled neopazno izgubi – obdelava na strežniku jo vidi kot izpraznjeno.
Zato sta vizualno različna: disabled je zatemnjen in očitno izven uporabe, readonly ima polno debelino pisave na obarvanem ozadju s črtkanim robom. Vrednost ostane berljiva in jo je mogoče označiti; le rob pove »tega ne spreminjate vi«.
Kako se izrišejo stanja
Barve stanj so izpeljane iz žetonov polja, ne poimenovane iz osnovne palete. Razlog je primer
iz prakse, ne okus: površina sme --wk-field-bg, --wk-field-fg in
--wk-field-border za vse v sebi določiti na novo – prijavna kartica to stori in polja
prestavi v svojo temno paleto. Stanje, ki poimenuje svetlo površino osnovne palete, bi tam dalo
svetleč pravokotnik.
| Stanje | Izris | Zakaj tako |
|---|---|---|
hover | ozadje, zmešano iz žetonov polja, delež --wk-state-hover-tint | mešanica se sama usmeri: v svetli shemi je pisava temna in površina se pomakne proti temnemu, v temni shemi obratno. Ena deklaracija tako pokrije vse tri sheme, namesto da bi jo ponavljali za vsako. |
active | ista mešanica, delež --wk-state-press-tint | približno dvakrat močnejša od hover. Obe se bereta neposredno zaporedoma (kazalec je med pritiskom vedno nad poljem), zato mora razlika obstati v primerjavi s hover, ne z mirovanjem. |
disabled | opacity | zatemni, ne da bi poznala barvo, in tako sama sledi vsaki paleti, shemi in koži. Ne potrebuje barvne funkcije, zato v nobenem brskalniku ne more neopazno odpovedati. |
readonly | črtkan rob in obarvano ozadje, zmešano iz žetonov polja | opacity ne pride v poštev, ker mora vrednost ostati povsem berljiva. Sporočilo nosi rob, ki prav tako ne stane nobene barve; če mešanica odpove, rob ostane. |
V svetli shemi: mirovanje #fdfcfa, hover #eeedeb, active #deddda. Kontrast
pisave ostane v vseh treh stanjih med
13,78:1 in 10,37:1, torej ves čas daleč nad 4,5:1 iz WCAG 2.2, merilo uspeha 1.4.3.
Pravilo hover v obrazcu z več polji drugo pod drugim sporoča, katero polje bi zadel klik.
Brez tega bi bili ozadje, pisava, barva roba in vrsta roba onemogočenega in samo berljivega polja enaki kot pri polju, ki ga je mogoče uporabljati; ostal bi le kazalec miške, ki ga uporabniki tipkovnice in zaslonov na dotik ne vidijo.
Napake to ne povzroči. Stran se izriše, sveženj se zgradi, polje deluje – le ne pove, v katerem stanju je, in to je videti kot oblikovalska odločitev. Zato se preverja mehansko: nobeno pravilo stanja v družini polj ne sme biti šibkejše od pravila za mirovanje, ki ga mora preglasiti.
aria-readonly se izrecno nastavi zraven: nativni atribut pripomočki upoštevajo le pri delu
vrst kontrolnikov – pri select in checkbox nima učinka.
pattern je zgolj udobje v brskalniku. Zavezujoče preverja strežnik; pattern je mogoče
zlahka obiti in nikoli ne sme biti edino preverjanje vrednosti, ki se shrani.
placeholder je namig o obliki, ne nadomestilo za oznako – izgine, ko začnete tipkati. Za
trajno pojasnilo uporabite hint.