Polja obrazca: osnove

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-načinom — nobeno polje te družine kategorij ne obnavlja lastnega motorja tipkovnice/fokusa (isto načelo kot pri dataGrid(), glej 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