Komponenty
Kompozícia
Komponenty zabudované v UI sú navrhnuté na skladanie, nie na samostatné používanie. Výberové pole sa otvára v dialógovom okne, formulár sa overuje v bočnom paneli a ponuka sa zobrazuje v riadku tabuľky. Táto stránka vysvetľuje, ako fungujú tieto súčasti: štruktúru zložených skupín, spôsob odovzdávania vlastností tlačidla spúšťačom, prácu modulu Interactivity API na pozadí a model vrstvenia, vďaka ktorému prekrývajúce sa plochy zostávajú súvislé.
Zložené skupiny
Zložený komponent tvorí koreňový blok a jeho podriadené bloky. Koreňový blok spravuje stav; každý podriadený blok určuje svoje miesto v skupine pomocou parent a usesContext vo svojom block.json:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Koreňové bloky sprístupňujú oblasť InnerBlocks so zoznamom allowedBlocks a počiatočným template. Pri vložení dialógového okna do editora sa tak pripravia jeho spúšťač, pozadie a vyskakovacie okno a skupina sa správa rovnako bez ohľadu na to, či ju zostavíte v editore, na stránke založenej na súboroch alebo pomocou značiek:
<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>
Vyskakovacie okná a panely sú skutočné oblasti InnerBlocks, nie sloty so špeciálnou syntaxou. bsui/dialog-popup prijíma vnorené bloky rovnako ako skupinový blok, takže vloženie formulára, výberového poľa alebo ďalšieho dialógového okna doň je bežnou súčasťou skladania.
Ploché údaje alebo zložené podriadené bloky
Niektoré skupiny prijímajú obsah ako údaje namiesto podriadených blokov. Ak výberovému poľu odovzdáte pole options JSON, samo vykreslí spúšťač a zoznam možností. To sa hodí pri možnostiach získavaných z 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'],
]),
],
]);
Oba spôsoby vytvárajú rovnakú štruktúru značiek aj rovnaké správanie pri behu. Keď je štruktúra vytvorená ručne, použite podriadené bloky; keď sa generuje, použite options.
Odovzdávanie spúšťača
Prekrývajúce komponenty sa otvárajú tlačidlom a týmto tlačidlom má byť systémové tlačidlo. Namiesto opätovnej implementácie tlačidla v každom spúšťači vkladajú bloky spúšťačov bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible a bsui/tooltip blok bsui/button prostredníctvom poľa bloku blok:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure rozbalí polia tlačidla do spúšťača s predponou trigger_. K dispozícii sú všetky vlastnosti tlačidla: 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 šablóne spúšťača je $a['trigger'] úplne vykreslené tlačidlo, takže jeho štýlový súbor aj budúce vylepšenia sa prenášajú spolu s ním. Za behu spoločný pomocný nástroj prenáša ARIA prepojenia obalu (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) na vnútorné tlačidlo a synchronizuje ich cez MutationObserver, aby asistenčné technológie vnímali jeden súvislý ovládací prvok.
Modul Interactivity API na pozadí
Každá interaktívna rodina je úložisko WordPress Interactivity API pomenované podľa svojho koreňového bloku: bsui/dialog, bsui/select, bsui/form, bsui/tabs a tak ďalej. Z toho vyplývajú tri dôsledky.
Stav sa nastaví na strane servera. Šablóna koreňového bloku vypíše jeho počiatočný stav ako data-wp-context priamo z atribútov bloku:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Prvé vykreslenie je správne už od začiatku HTML, bez probliknutia pri hydratácii na strane klienta. Vyskakovacie okná sa spúšťajú hidden a rovnaké značky fungujú aj na plátne editora, pretože kontext nezávisí od spracovania stavu iba na frontende.
Správanie sa pripája pomocou direktív, nie pomocou vášho JavaScript. Šablóny deklaratívne prepájajú značky s úložiskami. Po odstránení PHP z prvku spúšťača výberového poľa zostanú iba direktívy:
<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 smeruje udalosti na akcie, data-wp-bind synchronizuje atribúty s odvodeným stavom, data-wp-text vykresľuje stav ako text a data-wp-on-document--click umožňuje koreňovým prvkom zatvárať sa kliknutím mimo nich. Pri skladaní komponentov netreba písať obslužné funkcie udalostí; úložisko je súčasťou bloku ako vložený modul.
Svoje úložiská môžete zapojiť do týchto prepojení. Ovládacie prvky formulára prijímajú ako atribúty výrazy direktív a syntax s priestorom názvov modulu Interactivity API ich nasmeruje na ľubovoľné úložisko. onChange smeruje spracovanie zmien na jednu z vašich akcií, checked prepája stav ovládacieho prvku s vaším stavom a bindText vykreslí označenie ako prvok data-wp-text prepojený s ľubovoľnou cestou k stavu:
<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 dostupné pre položky bsui/label, bsui/checkbox, bsui/switch, bsui/toggle a bsui/radio-group. Pri zaškrtávacích políčkach, prepínačoch a možnostiach výberu sa prenáša do spoločného prvku označenia, takže text riadený stavom zachováva presne typografiu systémového označenia. Výberové polia a ďalšie vstupy navyše vysielajú z koreňového prvku bublajúcu udalosť change, ktorá nesie novú hodnotu v detail, pre integrácie na vyššej úrovni.
Riadené hodnoty
Ak ovládací prvok spravuje vlastnú hodnotu, value alebo checked ponechajte nenastavené. Na počiatočný výber použite defaultValue, defaultChecked alebo vlastnosť defaultPressed prvku Toggle. Samostatný prvok Toggle spracúva vstupy myšou aj klávesnicou bez úložiska príjemcu.
Ak chcete ovládať pole z vlastného úložiska, poskytnite jeho väzbu aj akciu onChange, ktorá aktualizuje naviazanú hodnotu. value je cesta direktívy, nie doslovná predvolená hodnota. Podporujú ju prvky Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating a Time Picker: value.
Prvky Checkbox, Switch a Toggle namiesto toho používajú checked.
Cesty uvádzajte s menným priestorom vlastníka, napríklad my/settings::context.quantity alebo my/settings::state.quantity. Zložené ovládacie prvky majú vlastný menný priestor; cesta bez uvedenia menného priestoru odkazuje na daný ovládací prvok, nie automaticky na nadradené úložisko. Väzby hodnôt zložených ovládacích prvkov podporujú bodkové cesty do kontextu alebo stavu vrátane číselných kľúčov polí, ale nie výrazy JavaScript ani volania funkcií.
Tu je kompletný príklad väzby prvku Number Field vo vlastnom bloku s povolenou podporou 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;
}
},
},
});
Nastavte zodpovedajúcu predvolenú hodnotu pre počiatočnú hodnotu vykreslenú na serveri. Po hydratácii zmeny nadradeného prvku aktualizujú všetky naviazané inštancie vrátane hodnôt nula, false a prázdnych hodnôt. Skryté vstupy formulára prvkov Checkbox a Switch takisto sledujú svoju väzbu checked. Hodnoty prvku Time Picker používajú formát HH:MM v 24-hodinovom formáte alebo prázdny reťazec.
V obslužných rutinách natívnych prvkov Input, Textarea a Password Input čítajte event.target.value; zložené ovládacie prvky hodnoty zverejňujú cez event.detail.value.
Hranice prvku Number Field sú voliteľné: ak min a max vynecháte, hodnota nebude ohraničená, pričom explicitná nula zostáva platnou hranicou.
Prvky Select, Date Input, Phone Input a OTP Input zverejňujú zmeny prostredníctvom onChange, ale nepodporujú túto riadenú väzbu value. Počiatočné hodnoty nastavte pomocou zdokumentovaných predvolených vlastností.
Skladanie z vlastných blokov
Skladanie sa neobmedzuje na stránky. Značky blokov sa automaticky vykreslia v šablónach blokov, takže blok projektu môže priamo vytvárať komponenty bsui a obaliť ich vlastnou štruktúrou:
<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>
Rovnako to funguje aj v PHP pomocou bs_block(), a to aj pri vnáraní cez kľúč content, ako je opísané v časti programové vykresľovanie. V oboch prípadoch sa spolu s komponentom načíta jeho štýlový súbor a úložisko a váš blok zostáva tenkou vrstvou, ktorá usporadúva systémové časti.
Na usporiadanie komponentov vedľa seba slúži bsui/stack, všeobecný flex riadok alebo stĺpec: direction, gap na stupnici rozostupov, align, justify a prepínač wrap. Podriadené prvky si predvolene zachovávajú prirodzenú veľkosť. Prepínač grow ich roztiahne tak, aby si rovnomerne rozdelili dĺžku celého usporiadania. Vďaka tomu môžu dve tlačidlá v päte stránky rozdeliť jej šírku namiesto toho, aby sa tlačili na jednom konci.
Skupiny polí a karty
bsui/field-group vykreslí skupinu polí. Predvolený variant zoskupí súvisiace polia bez pridania plochy pozadia. Pomocou variant="card" pridáte tlmený vonkajší rám a potom vložte polia do bsui/field-group-content, čím získate vnútornú plochu pre obsah. Názov a popis ponechajte mimo tohto bloku obsahu:
<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 skupine používa natívne správanie prvku fieldset na zakázanie ovládacích prvkov formulára.
Štýl karty nemení predvolený variant.
Oddeľovače panela nástrojov
Umiestnite bsui/toolbar-separator medzi položky panela nástrojov. Riadia sa orientation nadradeného panela nástrojov: vodorovný panel má zvislý oddeľovač v plnej výške a zvislý panel má vodorovný oddeľovač v plnej šírke.
Oddeľovače siahajú po vnútorné okraje rámčeka panela nástrojov bez zmeny výšky ovládacích prvkov. Vodorovný panel nástrojov sa posúva, keď jeho obsah presahuje dostupnú šírku.
Model vrstvenia
Pri prekrývaní plôch sa knižnice komponentov zvyčajne rozsypú. Zabudované komponenty sa riadia niekoľkými jednoduchými pravidlami určenými pre tých, ktorí vytvárajú skutočné používateľské rozhrania.
Modálne okná sa presúvajú do tela dokumentu
Keď sa otvorí dialógové okno, upozorňovacie dialógové okno alebo bočný panel, jeho vyskakovacie okno a pozadie sa presunú do document.body. Zástupný komentár zaznamená pôvodné miesto, kam sa po zatvorení vrátia. Presunutie mimo pôvodného miesta oslobodí modálne okno od overflow ľubovoľného nadradeného prvku, jeho transformácie aj kontextu vrstvenia. Pri otvorení sa tiež uzamkne posúvanie stránky. Uzamknutie sa sleduje spoločne pre všetky prekrývajúce komponenty a kompenzuje šírku posúvača, aby sa stránka neposunula. Pozadie má úroveň z-index: 50, vyskakovacie okno 51, zameranie sa presunie do vyskakovacieho okna, kláves Tab zostane v ňom a po zatvorení sa zameranie vráti na spúšťač.
Modálne okná sa vrství. Otvorenie dialógu z iného dialógu ho pridá do spoločného zásobníka: pozadie zobrazuje iba najvonkajší dialóg a dialógy za vrchným sa zmenšia a vykúkajú spoza neho. Zásobník riadi vlastnosť --bs-ui-nested-dialogs na každom dialógovom okne v pozadí, takže odsadenie a zmenšenie sa s každou úrovňou zväčšujú. Rodič zároveň prispôsobí svoju výšku podradenému oknu, aby vrstvy vykúkali rovnomerne. Pri zatváraní sa všetko obnoví v opačnom poradí, po jednej vrstve.
Po zatvorení modálneho okna sa fokus vráti na jeho spúšťač a presunie sa na správny prvok. Spoločný pomocník getAnchor rozpozná systémové tlačidlo vo vnútri obalu spúšťača, takže fokus znovu získa viditeľný ovládací prvok, nie neviditeľný obal.
Vrchné modálne okno sa nikdy netransformuje
Efekt vykúkania transformuje iba dialógy v pozadí. Vrchné modálne okno zostáva zámerne netransformované, pretože transformovaný prvok sa stáva kontajnerom pre potomkov position: fixed, čo by narušilo každé plávajúce vyskakovacie okno otvorené v ňom.
Toto pravidlo umožňuje skladať celý model vrstvenia. Všetky plávajúce vrstvy sa umiestňujú pomocou pevných súradníc, ktoré označujú pozíciu v okne prehliadača iba vtedy, keď im v tom nebráni transformovaný predok:
- Ponuka a rozbaľovací zoznam vypočítajú svoju pozíciu vzhľadom na spúšťač pomocou stratégie
fixedknižnice Floating UI; zobrazia sa pod ním a pri nedostatku miesta v okne prehliadača sa preklopia alebo posunú. - Výberové pole postupuje rovnako, keď nie je nič vybraté. Ak už má vybratú položku, zarovná vyskakovacie okno tak, aby sa vybratá možnosť zobrazila priamo nad spúšťačom, pričom zostane v okne prehliadača, podobne ako natívne výberové polia v macOS.
- Kontextová ponuka sa otvorí na pozícii ukazovateľa
clientX/clientY.
Keďže vrchné modálne okno nie je transformované, všetky tieto prvky sa správne ukotvia k svojim spúšťačom v dialógu, upozorňovacom dialógu alebo vysúvacom paneli pri ľubovoľnej hĺbke vnorenia. Vyskakovacie okná nemusia vedieť, že sú v modálnom okne.
Kláves Escape najprv zatvorí najvnútornejšiu vrstvu
Jedno stlačenie klávesu Escape zatvorí presne jednu vrstvu, zvnútra smerom von:
- Najprv sa zatvorí otvorená plávajúca vrstva (zoznam možností výberového poľa, ponuka, kontextové okno, kalendár alebo telefónne okno) a fokus sa vráti na jej spúšťač. Výberové pole zastaví šírenie udalosti a obslužné rutiny modálneho okna sa tiež pozastavia, keď je otvorená ľubovoľná plávajúca vrstva, takže dialóg pod ňou stlačenie nezachytí.
- Potom sa zatvorí vrchné modálne okno.
- Pri vrstvených modálnych oknách každé ďalšie stlačenie Escape odstráni zo zásobníka ďalšie okno.
Zatváranie je zámerne nastavené, nie náhodné. Dialóg vykreslený s dismissable="false" ignoruje kláves Escape aj kliknutia na pozadie. bsui/alert-dialog reaguje na Escape ako každé modálne okno, ale zámerne ignoruje kliknutia na pozadie: zmyslom tohto vzoru je, aby sa rozhodnutie urobilo vedome a okno sa nezatvorilo náhodou. Kliknutie na pozadie bežný dialóg zatvorí, pretože dismissable má predvolenú hodnotu true.
Formulár v dialógu
Tento vzor naraz využíva všetky uvedené pravidlá: spúšťač otvorí modálne okno, v ňom sa nachádza formulár s overovaním a vo formulári je plávajúce výberové pole.
<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>
Každá značka a atribút vyššie sú dôležité: spúšťač odovzdáva udalosť systémovému tlačidlu, názov a opis preberajú content, polia majú názvy, ktoré formulár serializuje, a required="true" analyzátor značiek prevedie na skutočnú booleovskú hodnotu.
Čo jednotlivé úložiská robia za behu
bsui/dialog vloží {"open":false,"dismissable":true} do kontextu na serveri. Kliknutie na spúšťač vykoná actions.open: vyskakovacie okno a pozadie sa presunú do tela dokumentu, posúvanie sa uzamkne s kompenzáciou šírky posuvníka, okno sa animáciou zobrazí za 150ms, fokus sa presunie na prvý prvok, na ktorý sa dá zamerať, a kláves Tab cykluje v okne. Oblasti hlavičky, obsahu a päty sa rozostupujú podľa tokenov medzier modálneho okna.
bsui/select čaká vo formulári spolu so svojím zoznamom možností hidden. Kliknutie na spúšťač prepne context.open, umiestni zoznam možností pomocou pevných súradníc v okne prehliadača a keďže defaultValue="editor" je už vybraté, zarovná vyskakovacie okno tak, aby sa položka Editor zobrazila priamo nad spúšťačom. Šípky, Home, End a zadávanie textu menia aktívnu možnosť; Enter alebo kliknutie ju vyberie; kláves Tab a kliknutia mimo okna ho zatvoria bez výberu. Viditeľný text spúšťača sa aktualizuje cez data-wp-text="state.displayValue" a skryté <input name="role"> sleduje hodnotu cez data-wp-bind--value="state.selectedValue", ktorú formulár neskôr serializuje. Všetky tieto prvky sa správne ukotvia v dialógu, pretože vrchné modálne okno nie je transformované.
bsui/form zachytí odoslanie. bsui/button na konci formulára vykreslí obyčajný prvok button bez atribútu type, takže sa podľa predvoleného správania HTML stane ovládacím prvkom na odoslanie formulára; tlačidlo Zrušiť sa nachádza v päte mimo prvku form, a preto nemôže nič odoslať. Pri odoslaní úložisko serializuje FormData formulára a odošle ho cez dátové API bloku pomenovaného v block; v tomto prípade vytvorí riadok v schéme databázy bloku team/invitedatabázová schéma. Chyby overenia sa vracajú pre jednotlivé polia: každé bsui/field obsahuje svoje name, označí sa ako neplatné, farba obrysu pri zameraní sa zmení na farbu pre deštruktívne akcie a správa sa zobrazí v jeho upozornení bsui/field-error. Po úspešnom odoslaní sa telo formulára skryje a zobrazí sa successMessage, v oboch prípadoch prostredníctvom data-wp-bind--hidden.
Vrstvy sa zatvárajú v poradí. Keď je otvorený zoznam možností, Escape ho zatvorí a vráti fokus na spúšťač výberového poľa; ďalšie stlačenie Escape zatvorí dialóg a vráti fokus na Pozvať spolupracovníka. Kliknutie na pozadie zatvorí dialóg, pretože dismissable zostalo na predvolenej hodnote. Zatvorením sa odomkne posúvanie a vyskakovacie okno sa vráti na pôvodné miesto v dokumente.
Rovnaké značky vložené do stránky založenej na súbore sa synchronizujú ako natívne bloky, pričom rovnakú skladbu vytvorenú v editore možno interaktívne zobraziť na plátne, pretože všetky uvedené správania sú definované v direktívach a úložiskách, ktoré sa načítajú v oboch prostrediach.
Čo zabezpečuje fungovanie týchto rozhraní
Uvedené rozhrania nie sú len konvencie, ale invarianty, ktoré knižnica dodržiava všade, kde vykresľuje: každý štítok má rovnakú typografiu, všetky modálne okná zdieľajú rovnaký povrch a stmavujú stránku za sebou, plávajúce okná si pri posúvaní stránky zachovávajú ukotvenie k spúšťaču a Escape zatvára vždy jednu vrstvu po druhej, zvnútra smerom von. Tieto záruky platia na webovej stránke aj na plátne editora, s predvolenými tokenmi aj tokenmi vašej témy, takže skladba, ktorá funguje v jednom prostredí, sa bude rovnako správať aj v ostatných.
Živé príklady
Kompozície na tejto stránke tvoria gramatiku; ui/examples je slovník fráz. Zhromažďuje živé vykreslené kompozície v troch úrovniach: dvojice, ktoré ukazujú prepojenie dvoch alebo troch komponentov, rozpoznateľné vzory produktov zostavené z niekoľkých komponentov a kompletné miniaplikácie poskladané tak, ako sa komponenty dodávajú v skutočných produktoch. Každá stránka komponentu na adrese ui obsahuje vlastné praktické príklady, od označeného poľa až po kalendár v kontextovom okne.
Direktíva a úložisko modelujú základ, na ktorom sú postavené komponenty UI, a ukazujú, ako ich používať vo vlastných blokoch.