Komponendid
Kooslus
Kaasasolevad UI komponendid on mõeldud kokkupanekuks, mitte ühekaupa kasutamiseks. Valikväli avaneb dialoogiaknas, vormi valideerimine toimub sahtlis ja menüü paikneb tabelireal. See leht selgitab, kuidas need osad koos töötavad: kuidas liitkomponentide perekonnad on üles ehitatud, kuidas päästikud edastavad nupu omadused, mida Interactivity API taustal teeb ning kuidas kihistusmudel hoiab virnastatud pinnad korrastatuna.
Liitkomponentide perekonnad
Liitkomponent koosneb juurplokist ja alamplokkidest. Juurplokk haldab olekut; iga alamplokk määrab oma koha perekonnas oma block.json-is väljadega parent ja usesContext:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Juurplokid pakuvad InnerBlocks ala, millel on allowedBlocks loend ja algne template. Nii lisab dialoogiakna redaktorisse sisestamine automaatselt selle päästiku, tausta ja hüpikakna ning perekond käitub ühtmoodi nii redaktoris, failipõhisel lehel kui ka siltides looduna:
<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>
Hüpikaknad ja paneelid on päris InnerBlocks alad, mitte erisüntaksiga pesad. bsui/dialog-popup aktsepteerib pesastatud plokke samamoodi nagu rühmaplokk, nii et vormi, valikvälja või teise dialoogiakna lisamine selle sisse on tavaline koostamisviis.
Lamedad andmed või koostatud alamplokid
Mõned perekonnad võtavad sisu alamplokkide asemel andmetena. Kui annate valikväljale options JSON massiivi, renderdab see ise päästiku ja loendkasti. See sobib valikutega, mis pärinevad allikast 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'],
]),
],
]);
Mõlemad vormid loovad sama märgistuslepingu ja käitusaja käitumise. Kasutage alamplokke, kui struktuur on käsitsi koostatud, ning options, kui see arvutatakse.
Päästiku edastamine
Ülekattekomponendid avatakse nupuga ja see nupp peaks olema süsteeminupp. Selle asemel et iga päästik nuppu uuesti teostaks, lisavad komponentide bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible ja bsui/tooltip päästikplokid selle plokivälja kaudu bsui/button:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure lisab nupu väljad päästikule prefiksiga trigger_. Saadaval on kõik nupu omadused: 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" />
Päästiku mallis on $a['trigger'] täielikult renderdatud nupp, nii et nupu stiilileht ja tulevased täiustused tulevad sellega kaasa. Käitusajal edastab ühine abifunktsioon ümbrise ARIA-seosed (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) sisemisele nupule ja hoiab neid MutationObserver kaudu sünkroonis, nii et abitehnoloogia näeb ühtset juhtelementi.
Interactivity API taustal
Igal interaktiivsel perekonnal on juurploki järgi nimetatud WordPress Interactivity API andmehoidla: bsui/dialog, bsui/select, bsui/form, bsui/tabs jne. Sellest tuleneb kolm asja.
Olek määratakse serveris. Juurmall prindib algoleku atribuudina data-wp-context, otse ploki atribuutidest:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Esimene kaader kuvatakse õigesti HTML ilma kliendipoolse hüdreerimise virvenduseta; hüpikaknad algavad olekus hidden ning sama märgistus töötab redaktori lõuendil, sest kontekst ei sõltu ainult kasutajaliidesele mõeldud olekusammust.
Käitumist juhivad direktiivid, mitte teie JavaScript. Mallid seovad märgistuse deklaratiivselt andmehoidlatega. Valikvälja päästik, millelt PHP on eemaldatud, koosneb ainult direktiividest:
<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 suunab sündmused toimingutele, data-wp-bind hoiab atribuudid tuletatud olekuga sünkroonis, data-wp-text renderdab oleku tekstina ja data-wp-on-document--click võimaldab juurplokkide sulgemist välisklõpsuga. Komponentide koostamiseks pole vaja sündmusekäitlejat kirjutada; andmehoidla tuleb plokiga kaasa reasisese moodulina.
Teie andmehoidlad sobituvad komponentide liidestega. Vormielemendid aktsepteerivad atribuutidena direktiivavaldisi ning Interactivity API nimeruumiga süntaks võimaldab suunata need mis tahes andmehoidlasse. onChange suunab muutuste käsitlemise ühele teie toimingule, checked seob juhtelemendi oleku teie olekuga ja bindText renderdab sildi kui data-wp-text span-elemendi, mis on seotud mis tahes olekurajaga:
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText on saadaval bsui/label, bsui/checkbox, bsui/switch, bsui/toggle ja bsui/radio-group elementidel. Märkeruudu, lüliti ja raadionupu elementidel jõuab see ühisesse sildiprimitiiivi, nii et olekust sõltuv tekst säilitab täpselt süsteemi sildi tüpograafia. Valikväljad ja muud sisendid saadavad lisaks oma juurelemendist mullitava sündmuse change, mis kannab uut väärtust väljas detail, võimaldades lihtsamaid integratsioone.
Juhitavad väärtused
Jätke value või checked määramata, kui juhtelement haldab ise oma väärtust. Kasutage algse valiku määramiseks defaultValue, defaultChecked või Toggle'i defaultPressed. Eraldiseisev Toggle käsitleb hiire- ja klaviatuurisisendit ilma tarbijapoe kasutamiseta.
Välja juhtimiseks oma poe kaudu määrake nii selle sidumine kui ka onChange toiming, mis seotud väärtust uuendab. value on direktiivi tee, mitte sõnasõnaline vaikeväärtus. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating ja Time Picker toetavad väärtust value.
Checkbox, Switch ja Toggle kasutavad selle asemel väärtust checked.
Lisage teedele omaniknimeruum, näiteks my/settings::context.quantity või my/settings::state.quantity. Liitjuhtelementidel on oma nimeruum; nimeruumita tee viitab sellele juhtelemendile ega osuta automaatselt teie ülemüksuse poele. Liitväärtuste sidumised toetavad punktteid konteksti või oleku sisse, sealhulgas massiivi numbrilisi võtmeid, kuid mitte JavaScript avaldisi ega funktsioonikutseid.
Siin on täielik Number Fieldi sidumine kohandatud plokis, kus Interactivity tugi API on lubatud:
<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;
}
},
},
});
Määrake serveris renderdatava algväärtuse jaoks vastav vaikeväärtus. Pärast hüdreerimist uuendavad ülemüksuse muudatused kõiki seotud eksemplare, sealhulgas väärtusi null, false ja tühi. Checkboxi ja Switchi peidetud vormisisendid järgivad samuti sidumise väärtust checked. Time Pickeri väärtused on 24-tunnises vormingus HH:MM või tühi string.
Loomulike Inputi, Textarea ja Password Inputi käsitlejate puhul lugege väärtust event.target.value; liitväärtuste juhtelemendid annavad välja event.detail.value.
Number Fieldi piirid on valikulised: kui min ja max on määramata, pole väärtusel piire, samas kui selgesõnaline null jääb kehtivaks piiriks.
Select, Date Input, Phone Input ja OTP Input annavad muudatustest teada väärtuse onChange kaudu, kuid ei paku seda juhitavat sidumist value. Algväärtuste jaoks kasutage dokumenteeritud vaikeväärtuse atribuute.
Koostamine oma plokkidest
Koostamine ei piirdu lehtedega. Plokisildid renderdatakse plokimallides automaatselt, nii et projektiplokk saab väljastada bsui komponente otse ja ümbritseda need oma struktuuriga:
<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>
Sama toimib PHP kaudu koos bs_block()-ga, sealhulgas pesastamine võtme content kaudu, nagu on kirjeldatud jaotises programmilise renderdamise kohta. Mõlemal juhul laaditakse komponendi stiilileht ja andmehoidla koos sellega ning teie plokk jääb süsteemi osade õhukeseks paigutuskihiks.
Komponentide kõrvuti paigutamiseks on bsui/stack üldotstarbeline paindpaigutusega rida või veerg: direction, vahed suurusskaalal gap, align, justify ja lüliti wrap. Vaikimisi säilitavad alamplokid oma loomuliku suuruse; lüliti grow paneb need hõivama virna pikkust võrdselt. Nii saab jalus panna kaks nuppu jagama laiust, selle asemel et need ühte serva koonduksid.
Väljarühmad ja kaardid
bsui/field-group renderdab väljade rühma. Vaikevariant rühmitab seotud väljad ilma pinda lisamata. Summutatud välisraami saamiseks kasutage variant="card" ning asetage väljad sisu sisse bsui/field-group-content, et saada süvistatud sisupind. Jätke pealkiri ja kirjeldus sellest sisuplokist väljapoole:
<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>
Rühmas kasutab disabled="true" väljade algset fieldset-käitumist vormi juhtelementide keelamiseks. Kaardi stiil ei muuda vaikevarianti.
Tööriistariba eraldajad
Paigutage bsui/toolbar-separator tööriistariba üksuste vahele. See järgib ülem-tööriistariba orientation: horisontaalse tööriistariba korral on see täiskõrgune vertikaalne eraldaja ja vertikaalse tööriistariba korral täislaiune horisontaalne eraldaja. Eraldajad ulatuvad tööriistariba äärise sisekülgedeni, muutmata juhtelementide kõrgust. Horisontaalne tööriistariba kerib, kui selle sisu ületab saadaoleva laiuse.
Kihistusmudel
Just virnastatud pinnad on koht, kus komponenditeegid tavaliselt hätta jäävad. Kaasasolevad komponendid järgivad väikest reeglistikku, mis on mõeldud päris kasutajaliideste ehitajatele.
Modaaldialoogid portitakse dokumendi kehasse
Dialoogiakna, hoiatusdialoogi või sahtli avamisel teisaldatakse selle hüpikaken ja taust document.body-i ning kohatäite kommentaar märgib algse asukoha, kuhu need sulgemisel tagasi viiakse. Portimine vabastab modaalakna kõigi eellaste overflow-ist, teisendusest ja virnastamiskontekstist. Avamisel lukustatakse ka lehe kerimine: lukku loendatakse kõigi ülekattekomponentide lõikes ning kompenseeritakse kerimisriba laius, et leht paigast ei nihkuks. Taust asub kihil z-index: 50 ja hüpikaken kihil 51; fookus liigub hüpikaknasse, Tab-klahv jääb selle sisse ning sulgemisel taastatakse fookus päästikule.
Modaali kuhjuvad. Dialoogi sees uue dialoogi avamine lisab selle ühele ühisele pinule: tausta näitab ainult kõige välimine dialoog ning ülemise taga olevad dialoogid kahanevad ja paistavad selle tagant välja. Pinu juhib iga taustal oleva hüpikakna atribuuti --bs-ui-nested-dialogs, nii et piilumise nihe ja suuruse vähenemine süvenevad iga tasemega; vanemdialoogi kõrgus kohandub lapse omaga, et kihid paistaksid ühtlaselt. Sulgemisel taastatakse kõik vastupidises järjekorras, üks kiht korraga.
Modaali sulgemisel naaseb fookus selle käivitajale ja õigele elemendile. Ühine abifunktsioon getAnchor leiab käivitaja ümbrisest süsteeminupu, nii et fookuse saab tagasi nähtav juhtelement, mitte nähtamatu ümbris.
Ülemist modaali ei teisendata kunagi
See piilumisefekt teisendab ainult taustal olevaid dialooge. Ülemine modaal jäetakse teadlikult teisendamata, sest teisendatud elemendist saab selle position: fixed järeltulijate positsioneerimise kontekst, mis rikuks kõik selle sees avatud hõljuvad hüpikaknad.
See reegel paneb kogu kihtide mudeli koos toimima. Kõik hõljuvad kihid kasutavad fikseeritud koordinaate, mis viitavad vaateaknale ainult siis, kui ükski teisendatud eellane vahele ei jää:
- Menüü ja liitkast arvutavad asukoha käivitaja suhtes, kasutades Floating UI-i
fixedstrateegiat: need avanevad käivitaja alla ning pöörduvad ümber või nihkuvad, kui vaateaknas ruumi napib. - Valikuloend teeb sama, kui midagi pole valitud. Kui valik on juba olemas, joondab see hüpikakna nii, et valitud suvand asub otse käivitaja kohal, piirdudes vaateakna mõõtmetega, nagu süsteemsetes valikuloendites macOS.
- Kontekstimenüü avaneb kursori
clientX/clientYjuures.
Kuna ülemine modaal on teisendamata, joondatakse kõik need hüpikaknad õigesti oma käivitajatega dialoogis, hoiatavas dialoogis või sahtlis, olenemata pesastuse sügavusest. Hüpikaknad ei tea, et asuvad modaali sees, ega peagi teadma.
Escape sulgeb kõigepealt kõige sisemise kihi
Üks Escape-klahvi vajutus sulgeb täpselt ühe kihi, alustades kõige sisemisest:
- Kõigepealt sulgub avatud hõljuv kiht (valikuloend, menüü, hüpikaken, kuupäeva- või telefoninumbri hüpikaken) ja fookus naaseb selle käivitajale. Valikuloend peatab sündmuse leviku ning modaali käsitlejad ei reageeri samuti, kui mõni hõljuv kiht on avatud, nii et selle all olev dialoog seda vajutust ei näe.
- Järgmisena sulgub ülemine modaal.
- Kuhjatud modaalide korral eemaldab iga järgmine Escape-klahvi vajutus pinust veel ühe modaali.
Sulgemine on reegel, mitte juhus. Atribuudiga dismissable="false" renderdatud dialoog eirab nii Escape-klahvi vajutust kui ka taustale klõpsamist. bsui/alert-dialog reageerib Escape-klahvile nagu iga modaal, kuid eirab teadlikult taustale klõpsamist: selle mustri mõte on, et valik tuleb teha, mitte kogemata sulgeda. Tavapärane dialoog sulgub taustale klõpsates, sest dismissable vaikeväärtus on true.
Vorm dialoogis
See muster rakendab korraga kõiki eelnevaid reegleid: käivitaja avab modaali, modaal sisaldab valideerivat vormi ja vorm sisaldab hõljuvat valikuloendit.
<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>
Kõik ülaltoodud sildid ja atribuudid on olulised: käivitaja suunab edasi süsteeminupule, pealkiri ja kirjeldus võtavad väärtuse content-ist, väljad sisaldavad nimesid, mille vorm serialiseerib, ning required="true" teisendatakse sildiparseris ehtsaks tõeväärtuseks.
Mida iga olekupood käitusajal teeb
bsui/dialog lisab {"open":false,"dismissable":true} serveris konteksti. Käivitajal klõpsamine käivitab actions.open: hüpikaken ja taust viiakse portaali kaudu body sisse, kerimine lukustatakse koos kerimisriba kompenseerimisega, hüpikaken ilmub animeeritult 150ms jooksul, fookus liigub esimesele fookustatavale elemendile ja Tab liigub tsüklina selle sees. Päise, sisu ja jaluse osad kasutavad vahede määramiseks modaalide vahe token'eid.
bsui/select asub vormi sees koos oma loendiboksiga hidden. Käivitajal klõpsamine muudab väärtuse context.open, paigutab loendiboksi fikseeritud vaateakna koordinaatide järgi ning joondab hüpikakna nii, et Editor asub otse käivitaja kohal, sest defaultValue="editor" on juba valitud. Nooleklahvid, Home, End ja teksti järgi otsimine muudavad aktiivset suvandit; Enter või klõps valib selle; Tab ja klõps väljaspool loendit sulgevad selle valikut tegemata. Käivitaja nähtavat teksti uuendatakse data-wp-text="state.displayValue" abil ning peidetud <input name="role"> jälgib väärtust data-wp-bind--value="state.selectedValue" kaudu, mille vorm hiljem serialiseerib. Kõik see ankurdub dialoogi sees õigesti, sest ülemine modaal on teisendamata.
bsui/form püüab esitamise kinni. Vormi lõpus olev bsui/button renderdab lihtsa button elemendi ilma atribuudita type, seega on see vaikimisi HTML järgi vormi esitamise juhtelement; nupp Cancel asub jaluses väljaspool elementi form ega saa midagi esitada. Esitamisel jadastab salvesti vormi FormData ja saadab selle andmete API kaudu plokile, mille nimi on block; siin luuakse rida ploki team/invite jaoks mõeldud andmebaasi skeemis. Valideerimisvead tagastatakse väljade kaupa: iga bsui/field sisaldab oma name, märgitakse kehtetuks, selle fookusrõnga värv muutub ohuvärviks ja teade kuvatakse selle bsui/field-error märguandes. Edu korral peidetakse vormi sisu ja kuvatakse successMessage, mõlemad data-wp-bind--hidden kaudu.
Kihid sulguvad õiges järjekorras. Kui loendiboks on avatud, sulgeb Escape selle ja viib fookuse valikuloendi käivitajale; järgmine Escape sulgeb dialoogi ja viib fookuse nupule Invite teammate. Taustale klõpsamine sulgeb dialoogi, sest dismissable jäeti vaikeväärtusele. Sulgemisel vabastatakse kerimislukk ja hüpikaken viiakse portaali kaudu tagasi oma kohale dokumendis.
Sama märgistus failipõhisele lehele kleebituna sünkroonitakse süsteemsete plokkidena ning redaktoris koostatud sama kompositsiooni saab lõuendil interaktiivselt eelvaadata, sest kõiki neid käitumisi juhivad direktiivid ja olekupoed, mis laaditakse mõlemas kontekstis.
Mis hoiab need ühenduskohad toimivana
Ülaltoodud ühenduskohad pole kokkulepped, vaid invariandid, mida teek järgib igal pool, kus see renderdab: iga silt kasutab sama tüpograafiat, igal modaali hüpikaknal on sama pind ja see tumendab tagapool oleva lehe, hõljuvad hüpikaknad püsivad kerimise ajal käivitaja küljes ning Escape sulgeb korraga täpselt ühe kihi, alustades kõige sisemisest. Need tagatised kehtivad nii esiküljel kui ka redaktori lõuendil, nii vaikimisi token'ite kui ka teie teema omadega; seega toimib ühes kontekstis käituv kompositsioon samamoodi ka teistes.
Näited reaalajas
Selle lehe kompositsioonid on grammatika; /ui/examples on väljendite kogu. See koondab renderdatud näiteid kolme tasemena: kahe või kolme komponendi ühenduskohta tõestavad paarid, mõnest komponendist koosnevad äratuntavad tootemustrid ning terviklikud minirakendused, mis on kokku pandud nii, nagu komponendid päristoodetes kasutusele võetakse. Iga komponendi lehel aadressil /ui on veel töötavaid näiteid, alates sildiga väljast kuni hüpikakna taga oleva kalendrini.
Direktiivide ja olekupoodide mudel, millele komponendid UI on rajatud, ning juhised selle kasutamiseks oma plokkides.