Componente
Compoziție
Componentele UI incluse sunt concepute pentru a fi asamblate, nu folosite individual. O listă de selecție se deschide într-o fereastră de dialog, un formular se validează într-un panou lateral, iar un meniu apare într-un rând de tabel. Această pagină explică mecanismele care fac posibile aceste conexiuni: structura familiilor compuse, modul în care declanșatoarele transmit proprietățile butoanelor, ce face în fundal magazinul de interactivitate API și modelul de stratificare care păstrează coerența suprafețelor suprapuse.
Familii compuse
O componentă compusă este formată dintr-un bloc rădăcină și blocuri copil. Rădăcina deține starea; fiecare copil își declară locul în familie prin parent și usesContext în block.json:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Rădăcinile expun o zonă InnerBlocks cu o listă allowedBlocks și un template inițial, astfel încât inserarea unei ferestre de dialog în editor să creeze automat declanșatorul, fundalul și fereastra pop-up; familia se comportă la fel, fie că este compusă în editor, într-o pagină bazată pe fișiere sau în etichete:
<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>
Ferestrele pop-up și panourile sunt zone InnerBlocks reale, nu sloturi cu sintaxă specială. Un bsui/dialog-popup acceptă blocuri imbricate la fel ca un bloc de grup, ceea ce permite includerea obișnuită a unui formular, a unei liste de selecție sau a altei ferestre de dialog.
Date plate sau copii compuși
Unele familii acceptă conținutul ca date, nu ca blocuri copil. Lista de selecție își generează propriul declanșator și propria listă de opțiuni dacă îi furnizați un tablou options JSON, o variantă potrivită pentru opțiunile provenite din 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'],
]),
],
]);
Ambele forme produc același contract de marcare și același comportament la execuție. Folosiți blocuri copil când structura este definită manual și options când este calculată.
Transmiterea proprietăților declanșatorului
Componentele suprapuse se deschid printr-un buton, iar acel buton trebuie să fie butonul sistemului. În loc ca fiecare declanșator să implementeze unul din nou, blocurile declanșatoare din bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible și bsui/tooltip includ bsui/button printr-un câmp block:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure extinde câmpurile butonului asupra declanșatorului, cu prefixul trigger_. Sunt disponibile toate proprietățile butonului: 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" />
În șablonul declanșatorului, $a['trigger'] este butonul randat complet, așa că foaia de stil a butonului și îmbunătățirile viitoare sunt preluate odată cu acesta. La execuție, un ajutor comun transmite legăturile ARIA ale învelișului (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) butonului interior și le menține sincronizate printr-un MutationObserver, astfel încât tehnologiile de asistare să perceapă un singur control coerent.
Magazinul de interactivitate API în fundal
Fiecare familie interactivă este un magazin de interactivitate WordPress API al cărui nume corespunde blocului rădăcină: bsui/dialog, bsui/select, bsui/form, bsui/tabs și așa mai departe. Rezultă trei consecințe.
Starea este inițializată pe server. Șablonul rădăcină afișează starea inițială ca data-wp-context, direct din atributele blocului:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Prima randare este corectă HTML, fără pâlpâire la hidratarea pe partea clientului; ferestrele pop-up pornesc hidden, iar aceeași marcare funcționează în zona editorului deoarece contextul nu depinde de o etapă de stare disponibilă doar pe frontend.
Comportamentul este configurat prin directive, nu prin JavaScript. Șabloanele conectează declarativ marcajul la magazine. Declanșatorul listei de selecție, fără PHP, conține doar directive:
<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 direcționează evenimentele către acțiuni, data-wp-bind menține atributele sincronizate cu starea derivată, data-wp-text redă starea ca text, iar data-wp-on-document--click permite rădăcinilor să închidă componenta la un clic în afara ei. Combinarea componentelor nu necesită scrierea unui gestionar de evenimente; magazinul este inclus cu blocul ca modul inline.
Magazinele dvs. se pot conecta la aceste puncte de integrare. Controalele de formular acceptă expresii de directive ca atribute, iar sintaxa cu spațiu de nume a magazinului de interactivitate API le direcționează către orice magazin. onChange direcționează gestionarea schimbărilor către una dintre acțiunile dvs., checked leagă starea controlului de starea dvs., iar bindText redă o etichetă într-un element span data-wp-text conectat la orice cale din stare:
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText este disponibil pe elementele bsui/label, bsui/checkbox, bsui/switch, bsui/toggle și bsui/radio-group. Pentru elementele casetă de selectare, comutator și buton radio, acesta este transmis primitivei comune pentru etichete, astfel încât textul controlat de stare păstrează exact tipografia etichetei sistemului. Listele de selecție și celelalte câmpuri de intrare declanșează, de asemenea, un eveniment change cu propagare de la rădăcină, care transmite noua valoare în detail, pentru integrări mai generale.
Valori controlate
Lăsați value sau checked nesetat pentru un control care își gestionează propria valoare. Folosiți
defaultValue, defaultChecked sau defaultPressed al comutatorului pentru selecția inițială. Un comutator independent gestionează interacțiunile cu indicatorul și tastatura fără un magazin consumator.
Pentru a controla un câmp din propriul magazin, furnizați atât legătura sa, cât și o
acțiune onChange care actualizează valoarea asociată. value este o cale de directivă,
nu o valoare implicită literală. Input, Textarea, Password Input, Number Field, Slider,
Radio Group, Color Picker, Rating și Time Picker acceptă value.
Checkbox, Switch și Toggle folosesc în schimb checked.
Calificați căile cu spațiul de nume care le deține, de exemplu
my/settings::context.quantity sau my/settings::state.quantity. Controalele compuse au propriul spațiu
de nume; o cale necalificată se referă la acel control,
nu automat la magazinul părinte. Legăturile valorilor compuse acceptă căi cu puncte
către context sau stare, inclusiv chei numerice de tablou, dar nu expresii JavaScript
sau apeluri de funcții.
Iată o legătură completă pentru Number Field într-un bloc personalizat, cu suportul Interactivity API activat:
<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;
}
},
},
});
Setați valoarea implicită corespunzătoare pentru valoarea inițială randată pe server. După hidratare,
modificările părintelui actualizează fiecare instanță asociată, inclusiv valorile zero, false și goale. Câmpurile ascunse pentru formulare ale Checkbox și Switch urmează, de asemenea, legătura checked.
Valorile Time Picker folosesc HH:MM în format de 24 de ore sau un șir gol.
Pentru handler-ele native Input, Textarea și Password Input, citiți
event.target.value; controalele compuse pentru valori publică event.detail.value.
Limitele Number Field sunt opționale: dacă min și max sunt omise, câmpul rămâne fără limite,
în timp ce zero explicit rămâne o limită validă.
Select, Date Input, Phone Input și OTP Input publică modificările prin
onChange, dar nu expun această legătură controlată value. Folosiți proprietățile implicite documentate pentru valorile inițiale.
Combinarea din blocurile proprii
Compoziția nu se limitează la pagini. Etichetele blocurilor sunt randate automat în șabloanele blocurilor, astfel încât un bloc al proiectului să poată genera direct componente bsui și să le încadreze în propria structură:
<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>
Același lucru este posibil din PHP cu bs_block(), inclusiv prin imbricare folosind cheia content, așa cum se arată la randarea programatică. În ambele cazuri, foaia de stil și magazinul componentei se încarcă împreună cu aceasta, iar blocul dvs. rămâne un strat subțire care aranjează componentele sistemului.
Pentru a aranja componentele una lângă alta, bsui/stack este rândul sau coloana flex generică: direction, gap pe scala spațierii, align, justify și o comutare wrap. În mod implicit, copiii își păstrează dimensiunea naturală; comutarea grow îi întinde pentru a împărți în mod egal lungimea stivei, astfel încât un subsol să poată împărți lățimea între două butoane în loc să le țină înghesuite la un capăt.
Grupuri de câmpuri și carduri
bsui/field-group redă un set de câmpuri. Varianta implicită grupează câmpurile asociate fără a adăuga o suprafață. Folosiți variant="card" pentru un cadru exterior discret, apoi plasați câmpurile în bsui/field-group-content pentru a obține suprafața interioară a conținutului. Păstrați titlul și descrierea în afara acestui bloc de conținut:
<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" din grup folosește comportamentul nativ al elementului fieldset pentru a dezactiva controalele formularului. Stilizarea cardului nu schimbă varianta implicită.
Separatoare pentru bara de instrumente
Plasați bsui/toolbar-separator între elementele barei de instrumente. Acesta urmează orientation barei de instrumente părinte: o bară de instrumente orizontală afișează un separator vertical pe toată înălțimea, iar una verticală afișează un separator orizontal pe toată lățimea. Separatoarele se extind până la marginile interioare ale chenarului barei de instrumente fără a schimba înălțimea controalelor. O bară de instrumente orizontală derulează atunci când conținutul depășește lățimea disponibilă.
Modelul de stratificare
Suprafețele suprapuse sunt punctul în care bibliotecile de componente se destramă de obicei. Componentele incluse respectă un set restrâns de reguli, concepute pentru cei care construiesc interfețe reale.
Ferestrele modale sunt plasate în body
Când se deschide o fereastră de dialog, una de alertă sau un panou lateral, fereastra pop-up și fundalul acesteia sunt mutate în document.body, iar un comentariu substituent marchează locul de revenire la închidere. Plasarea în afara ierarhiei eliberează fereastra modală de overflow oricărui element părinte, de transformări și de contextul de suprapunere. Deschiderea blochează și derularea paginii: blocarea este contorizată în comun pentru toate componentele suprapuse și compensează lățimea barei de derulare, astfel încât pagina să nu se deplaseze. Fundalul este la z-index: 50, fereastra pop-up la 51, focalizarea se mută în fereastra pop-up, tasta Tab este menținută în interior, iar la închidere focalizarea revine la declanșator.
Ferestrele modale se suprapun. Deschiderea unui dialog din interiorul altuia adaugă dialogul în aceeași stivă: doar dialogul exterior afișează fundalul întunecat, iar dialogurile din spatele celui de deasupra se micșorează și rămân vizibile parțial. Stiva controlează o proprietate personalizată --bs-ui-nested-dialogs pentru fiecare fereastră pop-up din fundal, astfel încât decalajul și micșorarea cresc cu fiecare nivel, iar fereastra părinte își potrivește înălțimea cu cea a ferestrei copil, pentru ca straturile să rămână vizibile uniform. La închidere, totul se restaurează în ordine inversă, câte un strat odată.
Când o fereastră modală se închide, focalizarea revine la declanșator și ajunge la elementul potrivit. Un ajutor comun getAnchor identifică butonul de sistem din interiorul unui container al declanșatorului, astfel încât focalizarea revine la controlul vizibil, nu la un container invizibil.
Fereastra modală de deasupra nu este niciodată transformată
Efectul de vizibilitate parțială transformă numai dialogurile din fundal. Fereastra modală de deasupra rămâne intenționat netransformată, deoarece un element transformat devine blocul de referință pentru descendenții position: fixed, ceea ce ar defecta toate ferestrele pop-up flotante deschise în interiorul său.
Această regulă face ca întregul model de suprapunere să funcționeze coerent. Toate straturile flotante se poziționează cu coordonate fixe, care se raportează la fereastra de vizualizare doar atât timp cât nu intervine un strămoș transformat:
- Meniul și caseta combinată își calculează poziția față de declanșator folosind strategia
fixeda UI, deschizându-se sub acesta și întorcându-se sau deplasându-se când nu mai este loc în fereastra de vizualizare. - Selectorul procedează la fel când nu este selectată nicio opțiune. Dacă există deja o selecție, își aliniază fereastra pop-up astfel încât opțiunea selectată să apară exact deasupra declanșatorului, limitată la fereastra de vizualizare, așa cum se comportă selectorii nativi pe macOS.
- Meniul contextual se deschide la coordonatele
clientX/clientYale indicatorului.
Deoarece fereastra modală de deasupra nu este transformată, toate aceste elemente se ancorează corect la declanșatoarele lor dintr-un dialog, un dialog de alertă sau un panou glisant, indiferent de nivelul de imbricare. Ferestrele pop-up nu știu că se află într-o fereastră modală și nici nu trebuie să știe.
Escape închide mai întâi stratul cel mai interior
O singură apăsare pe Escape închide exact un strat, dinspre interior spre exterior:
- Un strat flotant deschis (o listă de opțiuni a unui selector, un meniu, un popover, o fereastră pop-up pentru dată sau telefon) se închide primul, iar focalizarea revine la declanșator. Selectorul oprește propagarea evenimentului, iar gestionarele ferestrei modale nu reacționează cât timp este deschis orice strat flotant, astfel încât dialogul de dedesubt nu primește niciodată acea apăsare.
- Următoarea se închide fereastra modală de deasupra.
- Dacă ferestrele modale sunt suprapuse, fiecare apăsare suplimentară pe Escape scoate încă una din stivă.
Închiderea este o regulă, nu o întâmplare. Un dialog redat cu dismissable="false" ignoră atât Escape, cât și clicurile pe fundal. Iar bsui/alert-dialog tratează Escape ca orice fereastră modală, dar ignoră intenționat clicurile pe fundal: ideea acestui tipar este ca alegerea să fie explicită, nu anulată accidental. Clicurile pe fundal închid un dialog obișnuit, deoarece dismissable este true în mod implicit.
Un formular într-un dialog
Tiparul care pune simultan în practică toate regulile de mai sus: un declanșator deschide o fereastră modală, aceasta conține un formular cu validare, iar formularul conține un selector flotant.
<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>
Fiecare etichetă și atribut de mai sus este esențial: declanșatorul transmite acțiunea către butonul de sistem, titlul și descrierea preiau content, câmpurile au numele pe care formularul le serializează, iar required="true" este convertit într-o valoare booleană reală de analizorul etichetelor.
Rolul fiecărei stări la rulare
bsui/dialog inițializează {"open":false,"dismissable":true} în context pe server. Clicul pe declanșator rulează actions.open: fereastra pop-up și fundalul întunecat sunt atașate prin portal la body, derularea este blocată cu compensarea barei de derulare, fereastra pop-up se animă la deschidere timp de 150ms, focalizarea se mută la primul element focalizabil, iar tasta Tab circulă în interiorul ei. Regiunile de antet, conținut și subsol își reglează spațierea cu ajutorul tokenurilor pentru distanța ferestrei modale.
bsui/select așteaptă în formular, cu lista de opțiuni hidden. Clicul pe declanșator comută context.open, poziționează lista cu coordonate fixe față de fereastra de vizualizare și, deoarece defaultValue="editor" este deja selectat, aliniază fereastra pop-up astfel încât Editor să apară exact deasupra declanșatorului. Tastele săgeată, Home, End și completarea pe măsură ce tastați schimbă opțiunea activă; Enter sau un clic selectează opțiunea; Tab și clicurile în afara listei o închid fără a selecta. Textul vizibil al declanșatorului se actualizează prin data-wp-text="state.displayValue", iar câmpul <input name="role"> ascuns urmărește valoarea prin data-wp-bind--value="state.selectedValue", pe care formularul o serializează ulterior. Toate acestea se ancorează corect în dialog, deoarece fereastra modală de deasupra nu este transformată.
bsui/form interceptează trimiterea formularului. Elementul bsui/button de la sfârșitul formularului redă un element button simplu, fără atributul type, deci este controlul de trimitere al formularului prin comportamentul implicit HTML; butonul Anulare se află în subsol, în afara elementului form, și nu poate trimite nimic. La trimitere, starea serializează FormData formularului și le transmite prin API de date al blocului numit în block, creând aici un rând pentru schema bazei de date team/invite blocului bazei de date. Erorile de validare sunt returnate pentru fiecare câmp: fiecare bsui/field preia name, este marcat ca invalid, își schimbă inelul de focalizare la culoarea de avertizare și afișează mesajul în alerta bsui/field-error. La succes, corpul formularului este ascuns și se afișează successMessage, ambele prin data-wp-bind--hidden.
Straturile se închid în ordine. Cu lista de opțiuni deschisă, Escape o închide și readuce focalizarea la declanșatorul selectorului; următoarea apăsare pe Escape închide dialogul și readuce focalizarea la Invitați un coleg. Un clic pe fundal închide dialogul, deoarece dismissable a rămas la valoarea implicită. Închiderea deblochează derularea și mută fereastra pop-up din portal înapoi la locul ei în document.
Același marcaj, lipit într-o pagină bazată pe fișiere, se sincronizează ca blocuri native, iar aceeași compoziție creată în editor poate fi previzualizată interactiv în canvas, deoarece fiecare comportament de mai sus este implementat prin directive și stări care se încarcă în ambele contexte.
Ce păstrează funcționale aceste îmbinări
Îmbinările de mai sus nu sunt convenții, ci invariante pe care biblioteca le respectă oriunde redă conținut: fiecare etichetă corespunde aceleiași tipografii, toate ferestrele pop-up modale folosesc aceeași suprafață și întunecă pagina din spatele lor, ferestrele pop-up flotante rămân ancorate la declanșator în timp ce pagina derulează, iar Escape închide exact un strat odată, dinspre interior spre exterior. Aceste garanții se aplică atât în partea publică, cât și în canvas-ul editorului, cu tokenurile implicite sau cu cele ale temei dumneavoastră, astfel încât o compoziție care funcționează într-un context se comportă la fel și în celelalte.
Exemple interactive
Compozițiile de pe această pagină sunt gramatica; /ui/examples este ghidul de expresii. Acesta reunește compoziții randate și funcționale în trei niveluri: perechi care demonstrează o îmbinare între două sau trei componente, tipare de produs recognoscibile construite dintr-o mână de componente și miniaplicații complete, asamblate așa cum sunt livrate componentele în produse reale. Fiecare pagină de componentă de la /ui adaugă exemple proprii, de la un câmp etichetat la un calendar în spatele unei ferestre popover.
Directiva și starea modelează componentele UI pe care sunt construite și arată cum să le folosiți în propriile blocuri.