Komponenty
Kompozycja
Komponenty dołączoneUIbundled są przeznaczone do łączenia, a nie do używania pojedynczo. Wybór otwiera się w oknie dialogowym, formularz jest walidowany w wysuwanym panelu, a menu znajduje się w wierszu tabeli. Ta strona wyjaśnia mechanizmy, które spajają te elementy: strukturę rodzin komponentów złożonych, przekazywanie właściwości przycisków przez wyzwalacze, działanie Interactivity API pod spodem oraz model warstw, który zapewnia spójność nakładających się powierzchni.
Rodziny komponentów złożonych
Komponent złożony składa się z bloku głównego i bloków podrzędnych. Blok główny zarządza stanem, a każdy blok podrzędny określa swoje miejsce w rodzinie za pomocą parent i usesContext w swoim block.json:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Bloki główne udostępniają obszar InnerBlocks z listą allowedBlocks i początkowym template. Dzięki temu wstawienie okna dialogowego w edytorze automatycznie tworzy jego wyzwalacz, tło i okno, a cała rodzina zachowuje się tak samo, niezależnie od tego, czy została złożona w edytorze, na stronie opartej na plikach, czy w tagach:
<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>
Okna wyskakujące i panele to rzeczywiste obszary InnerBlocks, a nie miejsca zarezerwowane ze specjalną składnią. bsui/dialog-popup akceptuje zagnieżdżone bloki tak samo jak blok grupy, dzięki czemu umieszczenie w nim formularza, listy wyboru lub innego okna dialogowego jest zwykłym łączeniem komponentów.
Płaskie dane czy złożone elementy podrzędne
Niektóre rodziny przyjmują zawartość w postaci danych zamiast elementów podrzędnych. Lista wyboru sama renderuje swój wyzwalacz i listę opcji po przekazaniu tablicy options JSON, co sprawdza się w przypadku opcji pochodzących 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'],
]),
],
]);
Obie formy zapewniają ten sam kontrakt znaczników i takie samo działanie w czasie wykonania. Używaj elementów podrzędnych, gdy struktura jest tworzona ręcznie, a options, gdy jest obliczana.
Przekazywanie właściwości do wyzwalacza
Komponenty nakładane otwierają się po kliknięciu przycisku, który powinien być przyciskiem systemowym. Zamiast implementować go na nowo w każdym wyzwalaczu, bloki wyzwalaczy bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible i bsui/tooltip osadzają bsui/button przez pole blok:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure rozwija pola przycisku na wyzwalaczu, dodając prefiks trigger_. Dostępne są wszystkie właściwości przycisku: 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" />
W szablonie wyzwalacza $a['trigger'] oznacza w pełni wyrenderowany przycisk, więc jego arkusz stylów i przyszłe udoskonalenia są z nim powiązane. W czasie działania wspólna funkcja pomocnicza przekazuje powiązania ARIA otoczki (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) na wewnętrzny przycisk i synchronizuje je za pomocą MutationObserver, dzięki czemu technologie asystujące widzą jeden spójny element sterujący.
Działanie Interactivity API pod spodem
Każda interaktywna rodzina to sklep Interactivity WordPressAPI nazwany od nazwy bloku głównego: bsui/dialog, bsui/select, bsui/form, bsui/tabs i tak dalej. Wynikają z tego trzy rzeczy.
Stan jest ustawiany po stronie serwera. Szablon bloku głównego zapisuje początkowy stan jako data-wp-context, bezpośrednio na podstawie atrybutów bloku:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Pierwsze renderowanie jest od razu poprawne HTML, bez migotania podczas nawadniania po stronie klienta; okna wyskakujące początkowo są hidden, a te same znaczniki działają w obszarze edytora, ponieważ kontekst nie zależy od stanu dostępnego wyłącznie po stronie frontendowej.
Działanie jest definiowane za pomocą dyrektyw, a nie własnego JavaScript. Szablony deklaratywnie łączą znaczniki ze sklepami. Po usunięciu PHP z wyzwalacza listy wyboru pozostają same dyrektywy:
<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 kieruje zdarzenia do akcji, data-wp-bind synchronizuje atrybuty z wyliczonym stanem, data-wp-text renderuje stan jako tekst, a data-wp-on-document--click zapewnia blokom głównym zamykanie po kliknięciu poza nimi. Łączenie komponentów nigdy nie wymaga pisania obsługi zdarzeń; sklep jest dołączony do bloku jako moduł wbudowany.
Twoje sklepy mogą korzystać z tych punktów integracji. Kontrolki formularzy akceptują wyrażenia dyrektyw jako atrybuty, a składnia przestrzeni nazw Interactivity API wskazuje dowolny sklep. onChange kieruje obsługę zmian do jednej z Twoich akcji, checked wiąże stan kontrolki z Twoim stanem, a bindText renderuje etykietę jako element span data-wp-text powiązany z dowolną ścieżką stanu:
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText jest dostępne dla elementów bsui/label, bsui/checkbox, bsui/switch, bsui/toggle i bsui/radio-group. W przypadku elementów pola wyboru, przełącznika i przycisków radiowych trafia do wspólnego prymitywu etykiety, dzięki czemu tekst sterowany stanem zachowuje dokładną typografię etykiety systemowej. Listy wyboru i inne pola wejściowe wysyłają dodatkowo z elementu głównego zdarzenie change propagowane w górę, zawierające nową wartość w detail, co ułatwia integracje działające na wyższym poziomie.
Wartości kontrolowane
Pozostaw value lub checked bez wartości dla kontrolki, która zarządza własną wartością. Użyj defaultValue, defaultChecked lub defaultPressed kontrolki Toggle, aby ustawić jej początkowy wybór. Samodzielna kontrolka Toggle obsługuje kliknięcia i wprowadzanie danych z klawiatury bez magazynu danych odbiorcy.
Aby kontrolować pole z własnego magazynu danych, podaj zarówno jego powiązanie, jak i akcję onChange, która aktualizuje powiązaną wartość. value to ścieżka dyrektywy, a nie dosłowna wartość domyślna. Kontrolki Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating i Time Picker obsługują value. Kontrolki Checkbox, Switch i Toggle używają zamiast tego checked.
Kwalifikuj ścieżki nazwą przestrzeni nazw, do której należą, na przykład my/settings::context.quantity lub my/settings::state.quantity. Złożone kontrolki mają własną przestrzeń nazw; niekwalifikowana ścieżka odnosi się do tej kontrolki, a nie automatycznie do nadrzędnego magazynu danych. Powiązania wartości złożonych kontrolek obsługują ścieżki kropkowe prowadzące do kontekstu lub stanu, w tym numeryczne klucze tablicy, ale nie JavaScript wyrażenia ani wywołania funkcji.
Oto kompletne powiązanie kontrolki Number Field w bloku niestandardowym z włączoną obsługą 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;
}
},
},
});
Ustaw odpowiadającą wartość domyślną dla początkowej wartości renderowanej po stronie serwera. Po hydratacji zmiany w elemencie nadrzędnym aktualizują każdą powiązaną instancję, w tym wartości zero, false i puste. Ukryte pola formularza kontrolek Checkbox i Switch również korzystają z powiązania checked. Wartości kontrolki Time Picker mają format HH:MM, 24-godzinny lub są pustym ciągiem. W przypadku natywnych handlerów kontrolek Input, Textarea i Password Input odczytuj event.target.value; złożone kontrolki wartości udostępniają event.detail.value. Ograniczenia Number Field są opcjonalne: pominięcie min i max oznacza brak ograniczeń, a jawnie podane zero pozostaje prawidłową granicą.
Kontrolki Select, Date Input, Phone Input i OTP Input publikują zmiany przez onChange, ale nie udostępniają tego kontrolowanego powiązania value. Wartości początkowe ustawiaj za pomocą udokumentowanych właściwości domyślnych.
Łączenie z własnych bloków
Kompozycja nie ogranicza się do stron. Tagi bloków są automatycznie renderowane w szablonach bloków, więc blok projektu może bezpośrednio emitować komponenty bsui i otaczać je własną strukturą:
<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>
To samo działa z PHP za pomocą bs_block(), również przy zagnieżdżaniu przez klucz content, zgodnie z opisem w sekcji renderowanie programowe. W obu przypadkach arkusz stylów i sklep komponentu są ładowane razem z nim, a Twój blok pozostaje cienką warstwą układającą elementy systemowe.
Do układania komponentów obok siebie służy bsui/stack, czyli ogólny wiersz lub kolumna flex: direction, gap ze skali odstępów, align, justify i przełącznik wrap. Domyślnie elementy podrzędne zachowują naturalny rozmiar; przełącznik grow rozciąga je tak, by równomiernie wypełniały długość stosu. Dzięki temu stopka może podzielić swoją szerokość między dwa przyciski, zamiast skupiać je przy jednym końcu.
Grupy pól i karty
bsui/field-group renderuje zestaw pól formularza. Domyślny wariant grupuje powiązane pola bez dodawania tła. Użyj variant="card", aby dodać przygaszoną zewnętrzną ramkę, a następnie umieść pola wewnątrz bsui/field-group-content, aby uzyskać wewnętrzną powierzchnię treści. Tytuł i opis pozostaw poza tym blokiem treści:
<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" w grupie korzysta z natywnego zachowania fieldset, aby wyłączać
jego kontrolki formularza. Styl karty nie zmienia domyślnego wariantu.
Separatory paska narzędzi
Umieść bsui/toolbar-separator między elementami paska narzędzi. Działa zgodnie z orientation elementu nadrzędnego: poziomy pasek narzędzi wyświetla separator pionowy na całą wysokość, a pionowy pasek narzędzi — separator poziomy na całą szerokość. Separatory rozciągają się do wewnętrznych krawędzi obramowania paska narzędzi, nie zmieniając wysokości kontrolek. Poziomy pasek narzędzi przewija się, gdy jego zawartość przekracza dostępną szerokość.
Model warstw
Nakładające się powierzchnie to miejsce, w którym zwykle zawodzą biblioteki komponentów. Dołączone komponenty stosują niewielki zestaw zasad opracowanych z myślą o osobach tworzących rzeczywiste interfejsy użytkownika.
Okna modalne są przenoszone do elementu body
Po otwarciu okna dialogowego, okna alertu lub wysuwanego panelu jego okno i tło są przenoszone do document.body; komentarz zastępczy wskazuje miejsce, do którego należy je przywrócić po zamknięciu. Przeniesienie poza strukturę dokumentu uwalnia okno modalne od overflow, transformacji i kontekstu stosu dowolnego elementu nadrzędnego. Otwarcie blokuje też przewijanie strony: blokada jest zliczana wspólnie dla wszystkich nakładanych komponentów i kompensuje szerokość paska przewijania, aby strona się nie przesuwała. Tło znajduje się na poziomie z-index: 50, okno na poziomie 51, fokus przechodzi do okna, klawisz Tab pozostaje w jego obrębie, a po zamknięciu fokus wraca do wyzwalacza.
Okna modalne układają się warstwami. Otwarcie okna dialogowego z poziomu innego okna dodaje je do wspólnego stosu: tylko najbardziej zewnętrzne okno ma tło, a okna za najwyższym zmniejszają się i wystają zza niego. Stos steruje właściwością niestandardową --bs-ui-nested-dialogs każdego popupu w tle, dlatego wysunięcie i zmniejszenie skali pogłębiają się na każdym poziomie, a okno nadrzędne dopasowuje wysokość do podrzędnego, aby warstwy wystawały równomiernie. Zamykanie przywraca wszystko w odwrotnej kolejności, po jednej warstwie na każde zamknięcie.
Po zamknięciu okna modalnego fokus wraca do elementu, który je otworzył, i trafia we właściwe miejsce. Wspólny helper getAnchor zamienia wrapper wyzwalacza na znajdujący się w nim przycisk systemowy, dzięki czemu fokus odzyskuje widoczny element sterujący, a nie niewidoczny wrapper.
Najwyższe okno modalne nigdy nie jest przekształcane
Efekt wysunięcia przekształca tylko okna dialogowe w tle. Najwyższe okno modalne celowo pozostaje nieprzekształcone, ponieważ przekształcony element staje się blokiem zawierającym dla potomków position: fixed, co zepsułoby każdy pływający popup otwarty wewnątrz niego.
Ta zasada pozwala całemu modelowi warstw współdziałać. Wszystkie pływające warstwy pozycjonują się za pomocą stałych współrzędnych, które odnoszą się do obszaru widoku tylko wtedy, gdy nie ma między nimi przekształconego elementu nadrzędnego:
- Menu i pole kombi obliczają pozycję względem wyzwalacza za pomocą strategii
fixedFloating UI: otwierają się pod nim i zmieniają stronę lub przesuwają, gdy brakuje miejsca w obszarze widoku. - Lista wyboru działa tak samo, gdy nic nie jest zaznaczone. Jeśli coś już wybrano, ustawia popup tak, aby wybrana opcja znajdowała się bezpośrednio nad wyzwalaczem, w granicach obszaru widoku, tak jak w natywnych listach wyboru w macOS.
- Menu kontekstowe otwiera się w punkcie
clientX/clientYwskaźnika.
Ponieważ najwyższe okno modalne nie jest przekształcone, wszystkie te elementy prawidłowo kotwiczą się przy swoich wyzwalaczach wewnątrz okna dialogowego, okna alertu lub wysuwanego panelu, niezależnie od głębokości zagnieżdżenia. Popupy nie wiedzą, że znajdują się w oknie modalnym, i nie muszą tego wiedzieć.
Escape najpierw zamyka warstwę najbardziej wewnętrzną
Jedno naciśnięcie Escape zamyka dokładnie jedną warstwę, zaczynając od najbardziej wewnętrznej:
- Najpierw zamyka się otwarta warstwa pływająca (lista wyboru, menu, popup, okno daty lub telefonu), a fokus wraca do jej wyzwalacza. Lista wyboru zatrzymuje propagację zdarzenia, a dodatkowo procedury obsługi okna modalnego wstrzymują działanie, gdy otwarta jest dowolna warstwa pływająca, więc okno dialogowe poniżej nie reaguje na to naciśnięcie.
- Następnie zamyka się najwyższe okno modalne.
- Przy zagnieżdżonych oknach modalnych każde kolejne naciśnięcie Escape usuwa z stosu następną warstwę.
Zasady zamykania są określone, a nie przypadkowe. Okno dialogowe wyrenderowane z dismissable="false" ignoruje zarówno Escape, jak i kliknięcia tła. bsui/alert-dialog reaguje na Escape jak każde okno modalne, ale celowo ignoruje kliknięcia tła: istotą tego wzorca jest konieczność podjęcia decyzji, a nie przypadkowe zamknięcie. Kliknięcie tła zamyka zwykłe okno dialogowe, ponieważ dismissable ma domyślnie wartość true.
Formularz w oknie dialogowym
Ten wzorzec jednocześnie wykorzystuje wszystkie powyższe zasady: wyzwalacz otwiera okno modalne, okno zawiera formularz z walidacją, a formularz — pływającą listę wyboru.
<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żdy powyższy tag i atrybut ma znaczenie: wyzwalacz przekazuje działanie do przycisku systemowego, tytuł i opis przyjmują content, pola mają nazwy serializowane przez formularz, a required="true" jest konwertowane przez parser tagów na prawdziwą wartość logiczną.
Działanie poszczególnych store w czasie wykonywania
bsui/dialog umieszcza {"open":false,"dismissable":true} w kontekście po stronie serwera. Kliknięcie wyzwalacza uruchamia actions.open: popup i tło są przenoszone do body, przewijanie zostaje zablokowane z kompensacją szerokości paska przewijania, popup pojawia się w animacji trwającej 150ms, fokus przechodzi na pierwszy element, który może go przyjąć, a klawisz Tab pozwala poruszać się w jego obrębie. Sekcje nagłówka, treści i stopki rozmieszczają się z użyciem tokenów odstępu modalnego.
bsui/select czeka wewnątrz formularza razem ze swoją listą hidden. Kliknięcie wyzwalacza przełącza context.open, ustawia listę wyboru za pomocą stałych współrzędnych obszaru widoku, a ponieważ defaultValue="editor" jest już zaznaczone, wyrównuje popup tak, aby Editor znajdował się bezpośrednio nad wyzwalaczem. Klawisze strzałek, Home, End i wpisywanie tekstu zmieniają aktywną opcję; Enter lub kliknięcie wybiera opcję; Tab i kliknięcia poza listą zamykają ją bez wyboru. Widoczny tekst wyzwalacza aktualizuje się za pomocą data-wp-text="state.displayValue", a ukryty <input name="role"> śledzi wartość przez data-wp-bind--value="state.selectedValue", co formularz później serializuje. Wszystkie te elementy prawidłowo kotwiczą się w oknie dialogowym, ponieważ najwyższe okno modalne nie jest przekształcone.
bsui/form przechwytuje wysłanie formularza. Końcowy bsui/button renderuje zwykły element button bez atrybutu type, dlatego zgodnie z domyślnym zachowaniem HTML wysyła formularz; przycisk Anuluj znajduje się w stopce poza elementem form i nie może niczego wysłać. Przy wysyłaniu magazyn stanu serializuje FormData formularza i przesyła je przez API danych bloku wskazanego w block, tutaj tworząc wiersz według schematu bazy danych bloku team/invite. Błędy walidacji wracają dla każdego pola: każde bsui/field ma własne name, zostaje oznaczone jako nieprawidłowe, zmienia kolor obramowania fokusu na kolor błędu i pokazuje komunikat w alercie bsui/field-error. Po sukcesie treść formularza znika i pojawia się successMessage; oba stany są sterowane przez data-wp-bind--hidden.
Warstwy zamykają się w odpowiedniej kolejności. Gdy lista wyboru jest otwarta, Escape zamyka ją i przywraca fokus wyzwalaczowi listy; następne Escape zamyka okno dialogowe i przywraca fokus przyciskowi Invite teammate. Kliknięcie tła zamyka okno dialogowe, ponieważ dismissable zachowało wartość domyślną. Zamknięcie odblokowuje przewijanie i przenosi popup z powrotem na jego miejsce w dokumencie.
Ten sam znacznik wklejony do strony opartej na plikach synchronizuje się jako natywne bloki, a ta sama kompozycja złożona w edytorze wyświetla interaktywny podgląd na kanwie, ponieważ wszystkie opisane zachowania są realizowane przez dyrektywy i store ładowane w obu kontekstach.
Co zapewnia działanie tych połączeń
Opisane połączenia nie są konwencjami, lecz niezmiennikami utrzymywanymi przez bibliotekę w każdym miejscu renderowania: każda etykieta jest powiązana z tą samą typografią, wszystkie popupy modalne mają wspólną powierzchnię i przyciemniają stronę za sobą, popupy pływające pozostają zakotwiczone przy wyzwalaczu podczas przewijania strony, a Escape zamyka dokładnie jedną warstwę naraz, zaczynając od najbardziej wewnętrznej. Te gwarancje obowiązują zarówno na stronie, jak i na kanwie edytora, przy domyślnych tokenach i tokenach motywu, więc kompozycja działająca w jednym kontekście działa tak samo w pozostałych.
Przykłady na żywo
Kompozycje na tej stronie tworzą gramatykę; /ui/examples to rozmówki. Zawiera działające, wyrenderowane kompozycje w trzech kategoriach: pary pokazujące połączenie dwóch lub trzech komponentów, rozpoznawalne wzorce produktów zbudowane z kilku komponentów oraz kompletne miniaplikacje złożone tak, jak komponenty są dostarczane w prawdziwych produktach. Strony poszczególnych komponentów pod adresem /ui zawierają dodatkowe przykłady, od pola z etykietą po kalendarz za popupem.
Model dyrektyw i store, na których opierają się komponenty UI, oraz sposób ich użycia we własnych blokach.