Komponenty
Kompozice
Součásti UI dodávané v balíčku jsou navržené tak, aby se skládaly dohromady, nikoli používaly samostatně. Výběrové pole se otevírá v dialogovém okně, formulář se ověřuje v bočním panelu a nabídka se zobrazuje v řádku tabulky. Tato stránka vysvětluje, jak funguje jejich propojení: jak se strukturují složené skupiny, jak spouštěcí prvky předávají vlastnosti tlačítek, co zajišťuje API Interactivity na pozadí a jak model vrstev udržuje soulad mezi překrývajícími se prvky.
Složené skupiny
Složená komponenta se skládá z kořenového bloku a podřízených bloků. Kořen spravuje stav; každý podřízený blok určuje své místo ve skupině pomocí parent a usesContext ve svém block.json:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Kořeny zpřístupňují oblast InnerBlocks se seznamem allowedBlocks a výchozím template, takže po vložení dialogového okna do editoru se připraví jeho spouštěcí prvek, pozadí a vyskakovací okno. Skupina se chová stejně, ať ji sestavíte v editoru, na stránce založené na souboru, nebo pomocí značek:
<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>
Vyskakovací okna a panely jsou skutečné oblasti InnerBlocks, nikoli sloty se zvláštní syntaxí. bsui/dialog-popup přijímá vnořené bloky stejně jako skupinový blok, takže umístit do něj formulář, výběrové pole nebo další dialogové okno je běžným způsobem skládání komponent.
Plochá data nebo složené podřízené prvky
Některé skupiny přijímají obsah jako data místo podřízených prvků. Když předáte výběrovému poli pole options JSON, vykreslí si vlastní spouštěcí prvek a seznam možností. Hodí se to pro možnosti načítané 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'],
]),
],
]);
Obě podoby vytvářejí stejné značky a stejné chování za běhu. Podřízené prvky použijte, když je struktura vytvořená předem, a options, když se generuje.
Předávání vlastností spouštěcího prvku
Překryvné komponenty se otevírají tlačítkem a tímto tlačítkem má být systémové tlačítko. Spouštěcí bloky komponent bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible a bsui/tooltip proto místo vlastní implementace vkládají bsui/button prostřednictvím pole bloku:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure rozbalí pole tlačítka do spouštěcího prvku s předponou trigger_. K dispozici jsou všechny vlastnosti tlačítka: 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 šabloně spouštěcího prvku je $a['trigger'] plně vykreslené tlačítko, takže se spolu s ním přenášejí jeho styly i budoucí úpravy. Za běhu sdílená pomocná funkce předává vnitřnímu tlačítku propojení ARIA z obalového prvku (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) a průběžně je synchronizuje pomocí MutationObserver, takže asistenční technologie vnímá jeden ucelený ovládací prvek.
Jak funguje API Interactivity
Každá interaktivní skupina je úložiště WordPress Interactivity API pojmenované podle svého kořenového bloku: bsui/dialog, bsui/select, bsui/form, bsui/tabs a tak dále. Z toho vyplývají tři důsledky.
Stav se nastaví na straně serveru. Šablona kořenového bloku vypíše počáteční stav jako data-wp-context přímo z atributů bloku:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
První vykreslení je správné HTML, bez bliknutí při hydrataci na straně klienta; vyskakovací okna se spouštějí hidden a stejné značky fungují i na plátně editoru, protože kontext nezávisí na průchodu stavem pouze na frontendu.
Chování se propojuje direktivami, nikoli vaším JavaScript. Šablony deklarativně propojují značky s úložišti. Po odebrání PHP ze spouštěcího prvku výběrového pole zůstanou pouze direktivy:
<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 směruje události na akce, data-wp-bind synchronizuje atributy s odvozeným stavem, data-wp-text vykresluje stav jako text a data-wp-on-document--click zajišťuje zavření kořenových prvků kliknutím mimo ně. Při skládání komponent nemusíte psát obslužné funkce událostí; úložiště je součástí bloku jako vložený modul.
Vaše úložiště lze připojit do těchto rozhraní. Ovládací prvky formulářů přijímají výrazy direktiv jako atributy a jmenná syntaxe API Interactivity je nasměruje na libovolné úložiště. onChange směruje zpracování změn na některou z vašich akcí, checked váže stav ovládacího prvku k vašemu stavu a bindText vykreslí štítek jako prvek data-wp-text propojený s libovolnou cestou ke 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é u položek bsui/label, bsui/checkbox, bsui/switch, bsui/toggle a bsui/radio-group. U položek se zaškrtávacím políčkem, přepínačem a přepínači možností se přenáší do sdíleného primitivního prvku štítku, takže text řízený stavem zachovává přesnou typografii systémového štítku. Výběrová pole a další vstupy navíc ze svého kořenového prvku vysílají bublající událost change, která nese novou hodnotu v detail a slouží k jednoduššímu napojení.
Řízené hodnoty
U ovládacího prvku, který spravuje vlastní hodnotu, ponechte value nebo checked nenastavené. Pro počáteční výběr použijte defaultValue, defaultChecked nebo defaultPressed u přepínače Toggle. Samostatný přepínač Toggle zpracovává vstup z myši i klávesnice bez úložiště konzumenta.
Chcete-li ovládat pole z vlastního úložiště, zadejte jeho vazbu i akci onChange, která aktualizuje navázanou hodnotu. value je cesta direktivy, nikoli doslovná výchozí hodnota. Vazbu value podporují prvky Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating a Time Picker. Prvky Checkbox, Switch a Toggle místo toho používají checked.
Cesty upřesněte názvem příslušného prostoru názvů, například my/settings::context.quantity nebo my/settings::state.quantity. Složené ovládací prvky mají vlastní prostor názvů; neupřesněná cesta odkazuje na daný ovládací prvek, nikoli automaticky na nadřazené úložiště. Vazby složených hodnot podporují tečkové cesty do kontextu nebo stavu, včetně číselných klíčů polí, nikoli však výrazy JavaScript ani volání funkcí.
Zde je úplný příklad vazby prvku Number Field ve vlastním bloku se zapnutou 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 odpovídající výchozí hodnotu pro počáteční vykreslení na serveru. Po hydrataci změny nadřazeného prvku aktualizují všechny navázané instance, včetně hodnot 0, false a prázdných hodnot. Skryté vstupy formuláře u prvků Checkbox a Switch se také řídí jejich vazbou checked. Hodnoty prvku Time Picker používají HH:MM ve 24hodinovém formátu nebo prázdný řetězec. U obslužných funkcí nativních prvků Input, Textarea a Password Input čtěte event.target.value; složené ovládací prvky hodnotu předávají přes event.detail.value.
Meze prvku Number Field jsou volitelné: pokud min a max vynecháte, hodnota není omezena, zatímco výslovná nula zůstává platnou mezí.
Prvky Select, Date Input, Phone Input a OTP Input předávají změny prostřednictvím onChange, ale tuto řízenou vazbu value nezpřístupňují. Počáteční hodnoty nastavte pomocí jejich zdokumentovaných výchozích vlastností.
Skládání z vlastních bloků
Skládání se neomezuje na stránky. Značky bloků se automaticky vykreslují uvnitř šablon bloků, takže projektový blok může přímo vytvořit komponenty bsui a obalit je vlastní strukturou:
<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>
Totéž funguje z PHP pomocí bs_block(), včetně vnořování přes klíč content, jak je popsáno v části programové vykreslování. V obou případech se spolu s komponentou načtou její styly a úložiště a váš blok zůstane tenkou vrstvou, která skládá systémové části dohromady.
Chcete-li komponenty uspořádat vedle sebe, slouží k tomu bsui/stack, obecný flex řádek nebo sloupec: direction, gap na škále mezer, align, justify a přepínač wrap. Podřízené prvky si ve výchozím nastavení zachovávají přirozenou velikost; přepínač grow je roztáhne tak, aby si délku celé skupiny rozdělily rovnoměrně. Díky tomu mohou například dvě tlačítka v patičce zabrat každé polovinu šířky místo toho, aby se držela u jednoho okraje.
Skupiny polí a karty
bsui/field-group vykreslí skupinu polí. Výchozí varianta seskupuje související pole bez přidání podkladu. Použijte variant="card" pro tlumený vnější rámeček a potom vložte pole dovnitř bsui/field-group-content, čímž získáte vnitřní plochu pro obsah. Název a popis ponechte mimo tento blok 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" ve skupině využívá nativní chování prvku fieldset k zakázání
ovládacích prvků formuláře. Stylování karty nemění výchozí variantu.
Oddělovače na panelu nástrojů
Umístěte bsui/toolbar-separator mezi položky panelu nástrojů. Řídí se orientation nadřazeného panelu nástrojů: vodorovný panel má svislý oddělovač přes celou výšku a svislý panel vodorovný oddělovač přes celou šířku. Oddělovače sahají k vnitřním okrajům rámečku panelu, aniž by měnily výšku ovládacích prvků. Pokud obsah vodorovného panelu přesáhne dostupnou šířku, panel se posouvá.
Model vrstev
Právě na překrývajících se prvcích se knihovny komponent obvykle rozpadají. Součásti dodávané v balíčku se řídí několika jednoduchými pravidly pro tvorbu skutečných uživatelských rozhraní.
Modální okna se přesouvají do těla dokumentu
Po otevření dialogového okna, upozorňovacího dialogu nebo bočního panelu se jeho vyskakovací okno a pozadí přesunou do document.body; jejich původní místo označuje komentářový prvek, který při zavření umožní návrat. Přesun mimo hierarchii prvků zbaví modální okno vlivu jakéhokoli nadřazeného prvku overflow, transformace nebo kontextu skládání. Při otevření se také uzamkne posouvání stránky. Zámek se počítá společně pro všechny překryvné komponenty a kompenzuje šířku posuvníku, takže se stránka neposune. Pozadí se umístí na z-index: 50 a vyskakovací okno na 51. Fokus se přesune do okna, klávesa Tab zůstane uvnitř a při zavření se fokus vrátí na spouštěcí prvek.
Modální okna se vrství. Otevření dialogu uvnitř jiného dialogu jej přidá na společný zásobník: pozadí zobrazuje pouze nejvzdálenější dialog a dialogy pod tím nejvyšším se zmenší a vykouknou zpoza něj. Zásobník řídí vlastní vlastnost --bs-ui-nested-dialogs u každého dialogu na pozadí, takže odsazení a zmenšení se s každou úrovní zvětšují. Nadřazený dialog navíc přizpůsobí výšku dialogu pod sebou, aby vrstvy vykukovaly rovnoměrně. Při zavírání se vše vrací v opačném pořadí, po jedné vrstvě.
Když se modální okno zavře, fokus se vrátí k jeho spouštěči a skončí na správném prvku. Sdílená pomocná funkce getAnchor převede obal spouštěče na systémové tlačítko uvnitř, takže fokus znovu získá viditelný ovládací prvek, nikoli neviditelný obal.
Nejvyšší modální okno se nikdy netransformuje
Efekt vykukování transformuje pouze dialogy na pozadí. Nejvyšší modální okno záměrně zůstává bez transformace, protože transformovaný prvek se stává ohraničujícím blokem pro potomky position: fixed, což by rozbilo všechna plovoucí vyskakovací okna otevřená uvnitř.
Toto pravidlo umožňuje skládat celý model vrstev. Všechny plovoucí vrstvy se umisťují pomocí pevných souřadnic, které odkazují na výřez stránky, pokud jim v tom nebrání transformovaný předek:
- Nabídka a kombinované pole vypočítají svou polohu vzhledem ke spouštěči pomocí strategie
fixedknihovny Floating UI: zobrazí se pod ním a při nedostatku místa ve výřezu se přesunou na druhou stranu nebo posunou. - Výběrové pole se chová stejně, pokud není nic vybráno. Pokud už má výběr, zarovná vyskakovací okno tak, aby vybraná možnost ležela přímo nad spouštěčem; okno přitom zůstane uvnitř výřezu, stejně jako u nativních výběrových polí v macOS.
- Kontextová nabídka se otevře na souřadnicích
clientX/clientYukazatele.
Protože nejvyšší modální okno není transformované, všechny tyto prvky se správně ukotví ke svým spouštěčům uvnitř dialogu, upozorňovacího dialogu nebo výsuvného panelu, a to při libovolné hloubce vnoření. Vyskakovací okna nijak nezjišťují, zda se nacházejí uvnitř modálního okna, a ani to nepotřebují.
Klávesa Escape zavírá nejprve nejvnitřnější vrstvu
Jedno stisknutí klávesy Escape zavře přesně jednu vrstvu, od nejvnitřnější směrem ven:
- Nejprve se zavře otevřená plovoucí vrstva (seznam možností výběrového pole, nabídka, vyskakovací okno, kalendář nebo telefonní okno) a fokus se vrátí k jejímu spouštěči. Výběrové pole zastaví šíření události a obslužné rutiny modálních oken se navíc pozastaví, kdykoli je otevřená nějaká plovoucí vrstva, takže dialog pod ní toto stisknutí nezaznamená.
- Poté se zavře nejvyšší modální okno.
- U naskládaných modálních oken každé další stisknutí Escape odebere ze zásobníku další vrstvu.
Zavírání se řídí pravidly, nejde o náhodné chování. Dialog vykreslený pomocí dismissable="false" ignoruje klávesu Escape i kliknutí na pozadí. bsui/alert-dialog reaguje na Escape jako každé modální okno, ale záměrně ignoruje kliknutí na pozadí: smyslem tohoto vzoru je, aby bylo nutné zvolit akci, a ne aby se dialog zavřel omylem. Kliknutí na pozadí běžný dialog zavře, protože dismissable má ve výchozím nastavení hodnotu true.
Formulář v dialogu
Tento vzor uplatňuje všechna výše uvedená pravidla najednou: spouštěč otevře modální okno, které obsahuje formulář s validací a v němž je plovoucí výběrové 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 atribut výše mají důležitou funkci: spouštěč předává ovládání systémovému tlačítku, nadpis a popis přebírají content, pole obsahují názvy, které formulář serializuje, a required="true" se v analyzátoru značek převede na skutečnou logickou hodnotu.
Co jednotlivá úložiště dělají za běhu
bsui/dialog vloží {"open":false,"dismissable":true} do kontextu na serveru. Kliknutí na spouštěč spustí actions.open: vyskakovací okno a pozadí se přesunou do těla dokumentu, posouvání se uzamkne s kompenzací šířky posuvníku, okno se během 150 ms animovaně zobrazí, fokus přejde na jeho první prvek, který jej může získat, a klávesa Tab se cyklicky pohybuje uvnitř okna. Oblasti záhlaví, obsahu a zápatí mají rozestupy určené tokeny mezer modálního okna.
bsui/select čeká uvnitř formuláře se svým seznamem možností hidden. Kliknutím na spouštěč se přepne context.open, seznam se umístí pomocí pevných souřadnic ve výřezu a protože už je vybraná možnost defaultValue="editor", vyskakovací okno se zarovná tak, aby Editor ležel přímo nad spouštěčem. Šipky, Home, End a průběžné vyhledávání podle psaných znaků mění aktivní možnost; Enter nebo kliknutí ji vybere; Tab a kliknutí mimo seznam jej zavřou bez výběru. Viditelný text spouštěče se aktualizuje prostřednictvím data-wp-text="state.displayValue" a skrytý prvek <input name="role"> sleduje hodnotu přes data-wp-bind--value="state.selectedValue", kterou pak formulář serializuje. Vše se správně ukotví uvnitř dialogu, protože nejvyšší modální okno není transformované.
bsui/form zachytí odeslání. Prvek bsui/button na konci formuláře vykreslí prostý prvek button bez atributu type, takže se ve výchozím nastavení HTML stane odesílacím ovládacím prvkem formuláře; tlačítko Zrušit je v patičce mimo prvek form a nemůže nic odeslat. Při odeslání úložiště serializuje FormData formuláře a odešle je přes datové API bloku uvedeného v block, čímž zde vytvoří řádek podle team/inviteschématu databáze. Validační chyby se vracejí pro jednotlivá pole: každé bsui/field obdrží své name, je označeno jako neplatné, kroužek fokusu se přepne na destruktivní barvu a zpráva se zobrazí v jeho výstražném prvku bsui/field-error. Při úspěchu se skryje tělo formuláře a zobrazí se successMessage, obojí prostřednictvím data-wp-bind--hidden.
Vrstvy se zavírají ve správném pořadí. Když je seznam možností otevřený, klávesa Escape jej zavře a vrátí fokus na spouštěč výběrového pole; další stisknutí Escape zavře dialog a vrátí fokus na tlačítko Pozvat kolegu. Kliknutí na pozadí dialog zavře, protože dismissable zůstalo ve výchozím nastavení. Po zavření se odemkne posouvání a vyskakovací okno se přesune zpět na původní místo v dokumentu.
Stejný kód značek vložený do souborové stránky se synchronizuje jako nativní bloky a stejná kompozice sestavená v editoru se interaktivně zobrazí v plátně, protože všechna výše popsaná chování zajišťují direktivy a úložiště, které se načítají v obou prostředích.
Co zajišťuje fungování těchto propojení
Výše popsaná propojení nejsou jen zvyklosti, ale neměnné vlastnosti, které knihovna zachovává při každém vykreslení: každý štítek používá stejné písmo, všechna vyskakovací okna modálních dialogů sdílejí stejný povrch a ztmavují stránku za sebou, plovoucí okna zůstávají ukotvena ke spouštěči i při posouvání stránky a klávesa Escape zavírá vždy právě jednu vrstvu, od nejvnitřnější směrem ven. Tyto záruky platí na webu i v plátně editoru, ať už používáte výchozí tokeny, nebo tokeny své šablony. Kompozice, která se chová správně v jednom prostředí, se tedy stejně chová i v ostatních.
Ukázky v provozu
Kompozice na této stránce ukazují pravidla; stránka /ui/examples je jejich přehled. Najdete na ní vykreslené ukázky ve třech úrovních: dvojice, které předvádějí propojení dvou či tří komponent; rozpoznatelné vzory pro konkrétní produkty vytvořené z několika komponent; a kompletní malé aplikace sestavené tak, jak se komponenty používají ve skutečných produktech. Stránka každé komponenty na /ui přidává vlastní praktické ukázky, od označeného pole po kalendář zobrazený za vyskakovacím oknem.
Model direktiv a úložišť, na kterém jsou komponenty UI postavené, a návod k jeho použití ve vlastních blocích.