Komponente
Sestava
Komponente združenega UI so zasnovane za sestavljanje, ne za posamično uporabo. Izbirni seznam se odpre v pogovornem oknu, obrazec se preveri v stranskem podoknu, meni pa je v vrstici tabele. Ta stran pojasnjuje mehanizme, zaradi katerih ti stiki delujejo: kako so sestavljene sestavljene družine, kako sprožilci posredujejo lastnosti gumbov, kaj v ozadju počne API Interactivity in kako model plasti ohranja skladnost zloženih površin.
Sestavljene družine
Sestavljena komponenta je korenski blok skupaj s podrejenimi bloki. Korenski blok upravlja stanje, vsak podrejeni blok pa svoj položaj v družini določi z parent in usesContext v svojem block.json:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Korenski bloki ponujajo območje InnerBlocks s seznamom allowedBlocks in začetnim template, zato vstavljanje pogovornega okna v urejevalnik samodejno pripravi njegov sprožilec, ozadje in pojavno okno. Družina se obnaša enako, ne glede na to, ali jo sestavite v urejevalniku, na strani iz datoteke ali z oznakami:
<bs:bsui-select name="role" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
</bs:bsui-select-popup>
</bs:bsui-select>
Pojavna okna in plošče so prava območja InnerBlocks, ne mesta za vstavljanje s posebno sintakso. bsui/dialog-popup sprejme ugnezdene bloke enako kot skupinski blok, zato lahko vanj običajno sestavite obrazec, izbirnik ali drugo pogovorno okno.
Podatki ali sestavljeni podrejeni elementi
Nekatere družine sprejmejo vsebino kot podatke namesto podrejenih elementov. Izbirnik sam izriše svoj sprožilec in seznam, ko mu podate polje options JSON, kar je primerno za možnosti iz PHP:
bs_render_block([
'name' => 'bsui/select',
'data' => [
'name' => 'role',
'placeholder' => 'Pick a role',
'options' => wp_json_encode([
['value' => 'viewer', 'label' => 'Viewer'],
['value' => 'editor', 'label' => 'Editor'],
]),
],
]);
Obe obliki ustvarita enako pogodbo označevalnega jezika in enako vedenje med izvajanjem. Uporabite podrejene elemente, kadar je struktura določena vnaprej, options pa, kadar je izračunana.
Posredovanje sprožilcev
Prekrivne komponente se odprejo z gumbom, ta gumb pa mora biti sistemski gumb. Namesto da bi vsak sprožilec znova implementiral svoj gumb, sprožilni bloki komponent bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible in bsui/tooltip vključijo bsui/button prek polja blok:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure razširi polja gumba na sprožilec s predpono trigger_. Na voljo so vse lastnosti gumba: trigger_label, trigger_variant, trigger_size, trigger_icon, trigger_iconPosition, trigger_href, trigger_disabled.
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
V predlogi sprožilca je $a['trigger'] v celoti izrisan gumb, zato njegova slogovna predloga in prihodnje izboljšave ostanejo povezane z njim. Med izvajanjem skupni pomočnik posreduje povezave ARIA ovojnika (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) notranjemu gumbu in jih prek MutationObserver ohranja usklajene, zato podporna tehnologija vidi enotno kontrolno polje.
Interaktivnost API v ozadju
Vsaka interaktivna družina je shramba WordPress Interactivity API, poimenovana po svojem korenskem bloku: bsui/dialog, bsui/select, bsui/form, bsui/tabs in tako naprej. Iz tega sledijo tri posledice.
Stanje se določi na strežniški strani. Predloga korenskega bloka izpiše začetno stanje kot data-wp-context, neposredno iz atributov bloka:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Prvi prikaz je pravilen HTML, brez utripanja ob hidrataciji na odjemalski strani; pojavna okna se začnejo hidden, enaka označevalna koda pa deluje tudi na platnu urejevalnika, saj kontekst ni odvisen od postopka za stanje, ki bi se izvajal samo na uporabniškem vmesniku.
Vedenje povezujejo direktive, ne vaš JavaScript. Predloge deklarativno povežejo označevalno kodo s shrambami. Sprožilec izbirnika brez PHP vsebuje samo direktive:
<button
data-wp-interactive="bsui/select"
data-wp-on--click="actions.toggle"
data-wp-on--keydown="actions.handleTriggerKeyDown"
data-wp-bind--aria-expanded="state.ariaExpanded"
data-wp-text="state.displayValue"
data-bsui-select-trigger
aria-haspopup="listbox"
>
data-wp-on usmerja dogodke k dejanjem, data-wp-bind ohranja atribute usklajene z izpeljanim stanjem, data-wp-text izriše stanje kot besedilo, data-wp-on-document--click pa korenskim elementom omogoča zapiranje ob kliku zunaj. Pri sestavljanju komponent ni treba pisati obravnavalnika dogodkov; shramba je priložena bloku kot vgrajeni modul.
Shrambe lahko povežete z vmesnimi točkami. Kontrolniki obrazcev sprejemajo izraze direktiv kot atribute, sintaksa z imenskim prostorom iz API interaktivnosti pa jih usmeri na poljubno shrambo. onChange usmeri obravnavo sprememb na eno od vaših dejanj, checked poveže stanje kontrolnika z vašim stanjem, bindText pa izriše oznako kot element data-wp-text, povezan s poljubno potjo stanja:
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText je na voljo pri elementih bsui/label, bsui/checkbox, bsui/switch, bsui/toggle in bsui/radio-group. Pri potrditvenih poljih, preklopnikih in izbirnih poljih se prenese v skupni osnovni element oznake, zato besedilo, vezano na stanje, ohrani natančno tipografijo sistemskih oznak. Izbirniki in drugi vnosi poleg tega iz svojega korenskega elementa oddajo dogodek change, ki se širi po hierarhiji in v detail prenaša novo vrednost, za širše integracije.
Nadzorovane vrednosti
Za kontrolnik, ki sam upravlja svojo vrednost, pustite value ali checked nenastavljen. Za začetni izbor uporabite defaultValue, defaultChecked ali Toggle defaultPressed. Samostojni Toggle obravnava vnose s kazalno napravo in tipkovnico brez shrambe odjemalca.
Če želite polje upravljati iz lastne shrambe, navedite tako njegovo vezavo kot tudi dejanje onChange, ki posodobi vezano vrednost. value je pot direktive, ne dobesedna privzeta vrednost. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating in Time Picker podpirajo value.
Checkbox, Switch in Toggle namesto tega uporabljajo checked.
Poti opredelite z imenskim prostorom lastnika, na primer my/settings::context.quantity ali my/settings::state.quantity. Sestavljeni kontrolniki imajo svoj imenski prostor; neoznačena pot se nanaša na ta kontrolnik, ne samodejno na nadrejeno shrambo. Sestavljene vezave vrednosti podpirajo pikčaste poti do konteksta ali stanja, vključno s številskimi ključi polj, ne pa izrazov JavaScript ali klicev funkcij.
Tukaj je celotna vezava Number Field v bloku po meri z omogočeno podporo Interactivity API:
<div
data-wp-interactive="my/settings"
data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
<bs:bsui-number-field
nameAlt="quantity"
defaultValue="2"
value="my/settings::context.quantity"
onChange="my/settings::actions.setQuantity"
/>
<output data-wp-text="context.quantity"></output>
</div>
import { getContext, store } from '@wordpress/interactivity';
store('my/settings', {
actions: {
setQuantity(event) {
// Compound controls publish their normalized value in a custom change event.
if (event.detail?.value !== undefined) {
getContext().quantity = event.detail.value;
}
},
},
});
Nastavite ustrezno privzeto vrednost za začetno vrednost, izrisano na strežniku. Po hidraciji spremembe nadrejenega elementa posodobijo vsak vezani primerek, tudi kadar so vrednosti nič, false ali prazen niz. Skriti obrazčni vnosi Checkbox in Switch prav tako sledijo svoji vezavi checked. Vrednosti Time Picker so v 24-urnem formatu HH:MM ali pa prazen niz.
Pri obravnavalnikih izvornih elementov Input, Textarea in Password Input preberite event.target.value; sestavljeni kontrolniki vrednosti objavijo event.detail.value.
Omejitve za Number Field niso obvezne: če min in max nista navedena, polje nima omejitev; izrecno določena ničla pa je veljavna omejitev.
Select, Date Input, Phone Input in OTP Input objavijo spremembe prek onChange, vendar ne izpostavijo te nadzorovane vezave value. Za začetne vrednosti uporabite njihove dokumentirane privzete lastnosti.
Sestavljanje z lastnimi bloki
Sestavljanje ni omejeno na strani. Oznake blokov se samodejno izrišejo znotraj predlog blokov, zato lahko projektni blok neposredno ustvari komponente bsui in jih ovije v lastno strukturo:
<div useBlockProps class="settings-panel">
<bs:bsui-switch label="Public profile" name="public" />
<bs:bsui-space size="4" />
<bs:bsui-button label="Save" variant="default" />
</div>
Enako deluje tudi iz PHP z bs_block(), vključno z gnezdenjem prek ključa content, kot je opisano v razdelku o programskem izrisovanju. V obeh primerih se slogovna predloga in shramba komponente naložita skupaj z njo, vaš blok pa ostane tanek sloj, ki razporeja sistemske dele.
Za razporeditev komponent drugo ob drugi je bsui/stack splošna vrstica ali stolpec flex: direction, gap na lestvici razmikov, align, justify in preklopnik wrap. Podrejeni elementi privzeto ohranijo svojo naravno velikost; preklopnik grow jih raztegne, da si enakomerno razdelijo dolžino sklada. Tako noga strani poskrbi, da si dva gumba razdelita njeno širino, namesto da bi se stiskala na enem koncu.
Skupine polj in kartice
bsui/field-group izriše nabor polj. Privzeta različica združi povezana polja, ne da bi dodala ozadje. Za umirjen zunanji okvir uporabite variant="card", nato pa polja postavite v bsui/field-group-content, da dobite vstavljeno površino vsebine. Naslov in opis pustite zunaj tega bloka vsebine:
<bs:bsui-field-group variant="card">
<bs:bsui-field-group-title text="Account settings" />
<bs:bsui-field-group-description text="Manage your account preferences." />
<bs:bsui-field-group-content>
<bs:bsui-field>
<bs:bsui-field-label text="Display name" />
<bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
</bs:bsui-field>
<bs:bsui-field>
<bs:bsui-field-label text="Email" />
<bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
</bs:bsui-field>
</bs:bsui-field-group-content>
</bs:bsui-field-group>
disabled="true" v skupini uporablja izvorno vedenje elementa fieldset za onemogočanje kontrolnikov obrazca. Slog kartice ne spremeni privzete različice.
Ločila v orodni vrstici
Postavite bsui/toolbar-separator med elemente orodne vrstice. Upošteva orientation nadrejene orodne vrstice: vodoravna orodna vrstica dobi navpično ločilo čez celotno višino, navpična orodna vrstica pa vodoravno ločilo čez celotno širino. Ločila segajo do notranjih robov obrobe orodne vrstice, ne da bi spremenila višino kontrolnikov. Vodoravna orodna vrstica se pomika, ko njena vsebina preseže razpoložljivo širino.
Model plasti
Prav pri zloženih površinah knjižnice komponent pogosto odpovedo. Priložene komponente upoštevajo nekaj preprostih pravil, namenjenih ustvarjalcem resničnih uporabniških vmesnikov.
Modali se prenesejo v telo dokumenta
Ko se odpre pogovorno okno, opozorilno pogovorno okno ali stranski predal, se njegovo pojavno okno in ozadje premakneta v document.body, komentar kot nadomestni element pa označi pot nazaj, ko se zapre. Prenos modala ga osvobodi overflow, transformacij ali konteksta zlaganja katerega koli nadrejenega elementa. Ob odprtju se zaklene tudi drsenje po strani: zaklep šteje sklice med vsemi prekrivnimi komponentami in upošteva širino drsnega traku, da se stran ne premakne. Ozadje je na ravni z-index: 50, pojavno okno pa na 51; fokus se premakne vanj, tipka Tab ostane ujeta znotraj, ob zaprtju pa se fokus vrne na sprožilec.
Modali se zlagajo. Ko dialog odprete znotraj drugega dialoga, se doda na skupni sklad: ozadje prikazuje samo najbolj zunanji dialog, dialogi za najvišjim pa se pomanjšajo in kukajo izza njega. Sklad določa vrednost lastnosti po meri --bs-ui-nested-dialogs za vsako pojavno okno v ozadju, zato se odmik in pomanjšanje s vsako ravnjo povečata, nadrejeni dialog pa svojo višino prilagodi podrejenemu, da plasti enakomerno kukajo. Ob zapiranju se vse obnovi v obratnem vrstnem redu, po eno plast naenkrat.
Ko se modalno okno zapre, se fokus vrne na njegov sprožilec in pristane na pravem elementu. Skupni pomočnik getAnchor pretvori ovoj sprožilca v sistemski gumb znotraj njega, zato fokus znova dobi vidni kontrolnik, ne nevidni ovoj.
Najvišje modalno okno se nikoli ne transformira
Učinek kukanja transformira samo dialoge v ozadju. Najvišje modalno okno namenoma ostane netransformirano, saj transformirani element postane vsebni blok za potomce position: fixed, kar bi pokvarilo vsa lebdeča pojavna okna, odprta znotraj njega.
To pravilo omogoča, da se celoten model plasti pravilno sestavlja. Vse lebdeče plasti se pozicionirajo s fiksnimi koordinatami, ki se nanašajo na vidno polje le, dokler vmes ne poseže transformiran prednik:
- Meni in kombinirano polje izračunata svoj položaj glede na sprožilec s strategijo
fixedknjižnice Floating UI ter se prikažeta pod njim in ob pomanjkanju prostora v vidnem polju obrneta ali premakneta. - Izbirnik naredi enako, kadar ni izbrana nobena možnost. Če je možnost že izbrana, pojavno okno poravna tako, da je izbrana možnost neposredno nad sprožilcem, pri čemer ga omeji na vidno polje, kot to počnejo izvorni izbirniki v macOS.
- Kontekstni meni se odpre na koordinatah
clientX/clientYkazalca.
Ker je najvišje modalno okno netransformirano, se vsi ti elementi pravilno zasidrajo na svoje sprožilce znotraj dialoga, opozorilnega dialoga ali predala, ne glede na globino gnezdenja. Pojavnim oknom ni treba vedeti, da so znotraj modalnega okna.
Tipka Escape najprej zapre najbolj notranjo plast
En pritisk tipke Escape zapre natanko eno plast, od najbolj notranje navzven:
- Najprej se zapre odprta lebdeča plast (seznam izbirnika, meni, pojavno okno, pojavno okno za datum ali telefon) in fokus se vrne na njen sprožilec. Izbirnik zaustavi širjenje dogodka, upravljavci modalnih oken pa se prav tako ne odzovejo, kadar je odprta katera koli lebdeča plast, zato dialog pod njo tega pritiska nikoli ne zazna.
- Nato se zapre najvišje modalno okno.
- Pri zloženih modalnih oknih vsak naslednji pritisk tipke Escape odstrani še eno okno s sklada.
Zapiranje je določeno s pravilom, ne prepuščeno naključju. Dialog, upodobljen z dismissable="false", prezre tako tipko Escape kot klike na ozadje. bsui/alert-dialog se na tipko Escape odzove kot vsako modalno okno, vendar namenoma prezre klike na ozadje: namen tega vzorca je, da je treba odločitev sprejeti, namesto da bi se okno zaprlo po nesreči. Klik na ozadje zapre navaden dialog, saj je dismissable privzeto nastavljen na true.
Obrazec v dialogu
Vzorec, ki hkrati preizkusi vsa zgornja pravila: sprožilec odpre modalno okno, to vsebuje obrazec s preverjanjem veljavnosti, obrazec pa lebdeči izbirnik.
<bs:bsui-dialog>
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
<bs:bsui-dialog-backdrop />
<bs:bsui-dialog-popup>
<bs:bsui-dialog-header>
<bs:bsui-dialog-title content="Invite a teammate" />
<bs:bsui-dialog-description content="They receive an email with a join link." />
</bs:bsui-dialog-header>
<bs:bsui-dialog-content>
<bs:bsui-form block="team/invite" successMessage="Invitation sent.">
<bs:bsui-field name="email">
<bs:bsui-field-label text="Email" />
<bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<bs:bsui-field name="role">
<bs:bsui-field-label text="Role" />
<bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
<bs:bsui-select-option value="admin" label="Admin" />
</bs:bsui-select-popup>
</bs:bsui-select>
</bs:bsui-field>
<bs:bsui-space size="2" />
<bs:bsui-button label="Send invite" />
</bs:bsui-form>
</bs:bsui-dialog-content>
<bs:bsui-dialog-footer>
<bs:bsui-dialog-close label="Cancel" />
</bs:bsui-dialog-footer>
</bs:bsui-dialog-popup>
</bs:bsui-dialog>
Vsaka zgornja oznaka in vsak atribut sta ključna: sprožilec posreduje dogodek sistemskemu gumbu, naslov in opis prejmeta content, polja vsebujejo imena, ki jih obrazec serializira, required="true" pa razčlenjevalnik oznak pretvori v pravo logično vrednost.
Kaj posamezna shramba počne med izvajanjem
bsui/dialog na strežniku vstavi {"open":false,"dismissable":true} v kontekst. Klik sprožilca izvede actions.open: pojavno okno in ozadje se prek portala premakneta v body, drsenje se zaklene z izravnavo širine drsnega traku, pojavno okno se prikaže z animacijo v 150ms, fokus se premakne na njegov prvi element, ki ga je mogoče fokusirati, tabulator pa kroži znotraj njega. Glava, vsebina in noga se razporedijo z odmiki iz žetonov za razmik modalnih oken.
bsui/select čaka znotraj obrazca, njegov seznam možnosti pa je hidden. Klik sprožilca preklopi context.open, seznam možnosti se pozicionira s fiksnimi koordinatami vidnega polja, ker pa je defaultValue="editor" že izbran, se pojavno okno poravna tako, da je možnost Editor neposredno nad sprožilcem. S puščičnimi tipkami, tipkama Home in End ter sprotnim iskanjem po tipkanju premikate aktivno možnost; z Enter ali klikom jo izberete; tabulator in kliki zunaj zaprejo seznam brez izbire. Vidno besedilo sprožilca se posodablja prek data-wp-text="state.displayValue", skriti <input name="role"> pa prek data-wp-bind--value="state.selectedValue" spremlja vrednost, ki jo obrazec pozneje serializira. Vse to se pravilno zasidra znotraj dialoga, ker najvišje modalno okno ni transformirano.
bsui/form prestreže oddajo. bsui/button na koncu obrazca izriše navaden element button brez atributa type, zato je po privzetih pravilih HTML kontrolnik za oddajo obrazca; gumb Prekliči je v nogi zunaj elementa form in ne more ničesar oddati. Ob oddaji shramba stanja serializira podatke FormData obrazca in jih pošlje prek podatkovnega API bloka, navedenega v block; tukaj ustvari vrstico po shemi zbirke podatkov bloka team/invite. Napake preverjanja veljavnosti se vrnejo za posamezna polja: vsak bsui/field ima svoj name, dobi oznako neveljavnosti, preklopi obroč fokusa na barvo za napake in prikaže sporočilo v opozorilu bsui/field-error. Ob uspehu se vsebina obrazca skrije in prikaže se successMessage, oboje prek data-wp-bind--hidden.
Plasti se razgradijo v pravilnem vrstnem redu. Ko je seznam možnosti odprt, Escape zapre seznam in vrne fokus na sprožilec izbirnika; naslednji Escape zapre dialog in vrne fokus na Povabi sodelavca. Klik na ozadje zapre dialog, ker je dismissable ostal pri privzeti vrednosti. Ob zaprtju se drsenje znova omogoči, pojavno okno pa se prekliče portal in vrne na svoje mesto v dokumentu.
Ista oznaka, prilepljena v datotečno stran, se sinhronizira kot izvorni blok, ista sestava, ustvarjena v urejevalniku, pa se v platnu interaktivno predogleda, saj je vse zgoraj opisano vedenje določeno z direktivami in shrambami, ki se naložijo v obeh kontekstih.
Kaj ohranja delovanje teh povezav
Zgornje povezave niso konvencije, temveč nespremenljiva pravila, ki jih knjižnica zagotavlja povsod, kjer izrisuje vsebino: vsaka oznaka se ujema z enako tipografijo, vsa modalna pojavna okna imajo enako površino in zatemnijo stran za seboj, lebdeča pojavna okna pa ohranijo sidrišče na sprožilcu med drsenjem po strani. Escape zapre natanko eno plast naenkrat, od najbolj notranje navzven. Jamstva veljajo v ospredju in v platnu urejevalnika, tako pri privzetih žetonih kot pri žetonih vaše teme, zato se sestava, ki deluje v enem kontekstu, enako vede tudi v drugih.
Primeri v živo
Sestave na tej strani so slovnica; /ui/examples pa je frazem. Vsebuje izrisane sestave v živo v treh ravneh: pare, ki pokažejo povezavo med dvema ali tremi komponentami, prepoznavne produktne vzorce, sestavljene iz nekaj komponent, in celotne mini aplikacije, sestavljene tako, kot so komponente vključene v resnične produkte. Stran vsake komponente na /ui vsebuje še lastne praktične primere, od označenega polja do koledarja za pojavnim oknom.
Direktiva in shramba prikazujeta model, na katerem temeljijo komponente UI, ter kako ga uporabiti v lastnih blokih.