Компоненти
Композиция
Вградените компоненти UI са проектирани да се комбинират, а не да се използват поотделно. Поле за избор се отваря в диалогов прозорец, формуляр се валидира в страничен панел, а меню се намира в ред от таблица. Тази страница обяснява как работят тези връзки: как са структурирани съставните семейства, как тригерите препращат свойствата на бутоните, какво прави отдолу Interactivity API и как моделът на слоевете поддържа съгласуваност между подредените един върху друг повърхности.
Съставни семейства
Съставният компонент е коренов блок плюс дъщерни блокове. Коренът управлява състоянието, а всяко дъщерно блокче обозначава мястото си в семейството чрез parent и usesContext в своя block.json:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Кореновите блокове предоставят област InnerBlocks със списък allowedBlocks и начална template, така че при вмъкване на диалогов прозорец в редактора автоматично се създават неговите тригер, фон и изскачащ прозорец. Семейството се държи еднакво независимо дали е съставено в редактора, на страница от файлове или чрез етикети:
<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>
Изскачащите прозорци и панелите са истински области InnerBlocks, а не слотове със специален синтаксис. bsui/dialog-popup приема вложени блокове по същия начин като групов блок, което позволява съвсем естествено да поставите в него формуляр, поле за избор или друг диалогов прозорец.
Равнинни данни или съставни дъщерни елементи
Някои семейства приемат съдържанието си като данни, а не като дъщерни елементи. Ако подадете масив options JSON, полето за избор създава само своя тригер и списък за избор. Това е удобно за опции, които идват от 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'],
]),
],
]);
И двата варианта създават еднакъв договор за маркировката и еднакво поведение по време на изпълнение. Използвайте дъщерни елементи, когато структурата е зададена предварително, а options — когато се изчислява.
Препращане от тригери
Компонентите с наслагване се отварят с бутон, който трябва да е системният бутон. Вместо всеки тригер да реализира собствен бутон, тригерните блокове на bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible и bsui/tooltip вграждат bsui/button чрез поле на блок:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
idStructure разгръща полетата на бутона в тригера с префикс trigger_. Налични са всички свойства на бутона: 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" />
В шаблона на тригера $a['trigger'] е напълно визуализираният бутон, така че стиловата таблица на бутона и бъдещите му подобрения вървят заедно с него. По време на изпълнение общ помощен инструмент препраща ARIA настройките на обвивката (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) към вътрешния бутон и ги поддържа синхронизирани чрез MutationObserver, така че помощните технологии да възприемат единен елемент за управление.
Какво стои отдолу: Interactivity API
Всяко интерактивно семейство представлява WordPress Interactivity API хранилище с име, производно от името на основния му блок: bsui/dialog, bsui/select, bsui/form, bsui/tabs и т.н. От това следват три последствия.
Състоянието се задава от страна на сървъра. Шаблонът на кореновия блок извежда началното си състояние като data-wp-context директно от атрибутите на блока:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Първоначалното изобразяване е правилно HTML и няма примигване при хидратиране от страна на клиента. Изскачащите прозорци започват hidden, а същата маркировка работи в платното на редактора, защото контекстът не зависи от пропуск за състоянието само за предния край.
Поведение се задава чрез директиви, а не чрез вашия JavaScript. Шаблоните свързват маркировката с хранилищата декларативно. Тригерът на полето за избор, без своя PHP, се състои само от директиви:
<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 насочва събитията към действия, data-wp-bind синхронизира атрибутите с изведеното състояние, data-wp-text визуализира състоянието като текст, а data-wp-on-document--click осигурява затваряне на кореновия блок при щракване извън него. При комбинирането на компоненти не е необходимо да пишете обработчик на събития; хранилището се доставя с блока като вграден модул.
Вашите хранилища могат да се свързват към интерфейсите. Контролите във формулярите приемат изрази за директиви като атрибути, а синтаксисът с пространства от имена на Interactivity API насочва изразите към произволно хранилище. onChange насочва обработката на промяната към едно от вашите действия, checked свързва състоянието на контролата с вашето състояние, а bindText визуализира етикет като data-wp-text span, свързан с произволен път до състояние:
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText е налично при елементите bsui/label, bsui/checkbox, bsui/switch, bsui/toggle и bsui/radio-group. При елементите за отметка, превключвателя и радиобутона то се предава на общия примитив за етикети, така че текстът, зависещ от състоянието, запазва точната типография на системния етикет. Полетата за избор и другите входни елементи изпращат допълнително изскачащо събитие change от корена си, което предава новата стойност в detail за по-общи интеграции.
Контролирани стойности
Оставете value или checked незададено за контрол, който управлява собствената си стойност. Използвайте defaultValue, defaultChecked или defaultPressed на Toggle за първоначалния избор. Самостоятелният Toggle обработва въвеждането с показалец и клавиатура без хранилище на потребителя.
За да управлявате поле от собственото си хранилище, задайте както неговото свързване, така и действие onChange, което актуализира свързаната стойност. value е път на директива, а не буквална стойност по подразбиране. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating и Time Picker поддържат value.
Checkbox, Switch и Toggle използват вместо това checked.
Добавяйте пространството от имена на собственика към пътищата, например my/settings::context.quantity или my/settings::state.quantity. Съставните контроли имат собствено пространство от имена; път без квалификатор се отнася до тази контрола, а не автоматично до родителското ви хранилище. Свързванията на съставни стойности поддържат пътища с точки към контекст или състояние, включително числови ключове на масиви, но не и изрази JavaScript или извиквания на функции.
Ето пълно свързване на Number Field в персонализиран блок с активирана поддръжка на 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;
}
},
},
});
Задайте съответната стойност по подразбиране за първоначалната стойност, визуализирана от сървъра. След хидратирането промените в родителя актуализират всеки свързан екземпляр, включително със стойности нула, false и празни. Скритите входни полета на формулярите Checkbox и Switch също следват своето свързване checked. Стойностите на Time Picker използват HH:MM в 24-часов формат или празен низ.
За обработчиците на вградени Input, Textarea и Password Input прочетете event.target.value; контролите за съставни стойности предоставят event.detail.value.
Границите на Number Field не са задължителни: ако min и max бъдат пропуснати, стойността няма граници, а изрично зададена нула остава валидна граница.
Select, Date Input, Phone Input и OTP Input публикуват промените чрез onChange, но не предоставят това контролирано свързване value. Използвайте документираните им свойства по подразбиране за първоначалните стойности.
Композиция от ваши собствени блокове
Композицията не се ограничава до страниците. Етикетите на блокове се визуализират автоматично в шаблоните на блоковете, така че блок на проекта може директно да изведе компоненти bsui и да ги обгърне със собствена структура:
<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>
Същото важи и за PHP с bs_block(), включително влагане чрез ключа content, както е описано в раздела за програмно визуализиране. И в двата случая стиловата таблица и хранилището на компонента се зареждат заедно с него, а вашият блок остава тънък слой за подреждане върху системните части.
За подреждане на компонентите един до друг bsui/stack е универсалният flex ред или колона: direction, gap по скалата за разстояния, align, justify и превключвател wrap. По подразбиране дъщерните елементи запазват естествения си размер; превключвателят grow ги разтяга, така че да си поделят равномерно дължината на контейнера. Така два бутона в долната част заемат поравно ширината му, вместо да се скупчват в единия край.
Групи полета и карти
bsui/field-group визуализира fieldset. Вариантът по подразбиране групира свързани полета, без да добавя повърхност. Използвайте variant="card" за приглушена външна рамка, след което поставете полетата в bsui/field-group-content, за да получите вдлъбната повърхност на съдържанието. Оставете заглавието и описанието извън този блок със съдържание:
<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" в групата използва вграденото поведение на fieldset, за да деактивира контролите във формуляра ѝ. Стилът на картата не променя варианта по подразбиране.
Разделители в лентата с инструменти
Поставете bsui/toolbar-separator между елементите в лентата с инструменти. Той следва orientation на родителската лента с инструменти: хоризонталната лента получава вертикален разделител с пълна височина, а вертикалната лента получава хоризонтален разделител с пълна ширина. Разделителите се простират до вътрешните ръбове на рамката на лентата с инструменти, без да променят височината на контролите. Хоризонталната лента с инструменти се превърта, когато съдържанието ѝ надхвърли наличната ширина.
Модел на слоевете
Подредените един върху друг повърхности обикновено създават проблеми на библиотеките от компоненти. Вградените компоненти следват набор от правила, създадени за хора, които изграждат реални потребителски интерфейси.
Модалните прозорци се изнасят към body
Когато се отвори диалогов прозорец, предупредителен диалогов прозорец или страничен панел, изскачащият прозорец и фонът му се преместват в document.body, а коментар-заместител отбелязва мястото, където трябва да се върнат при затваряне. Изнасянето освобождава модалния прозорец от overflow на всеки негов родителски елемент, от трансформациите му и от контекста на подреждане. При отваряне се заключва и превъртането на страницата: заключването се отчита общо за всички компоненти с наслагване и компенсира ширината на лентата за превъртане, за да не се измества страницата. Фонът е на ниво z-index: 50, изскачащият прозорец — на 51, фокусът се премества в него, клавишът Tab остава в него, а при затваряне фокусът се връща към тригера.
Модалните прозорци се подреждат в стек. Отварянето на диалогов прозорец от друг диалогов прозорец го добавя към общия стек: фонът се показва само зад най-външния диалогов прозорец, а прозорците под най-горния се смаляват и се подават иззад него. Стекът задава персонализирано свойство --bs-ui-nested-dialogs на всеки фонов изскачащ прозорец, така че отместването и мащабирането на показващите се прозорци се увеличават с всяко ниво. Родителският прозорец наглася височината си спрямо дъщерния, за да се подават слоевете равномерно. При затваряне всичко се възстановява в обратен ред, по един слой наведнъж.
Когато модален прозорец се затвори, фокусът се връща към задействащия го елемент и отново попада на правилния елемент. Общ помощник getAnchor намира системния бутон във всеки контейнер на задействащия елемент, така че фокусът да се върне върху видимия елемент за управление, а не върху невидим контейнер.
Най-горният модален прозорец никога не се трансформира
Ефектът на показване иззад друг прозорец трансформира само фоновите диалози. Най-горният модален прозорец умишлено остава нетрансформиран, защото трансформираният елемент става съдържащ блок за потомците position: fixed, което би нарушило работата на всички плаващи изскачащи прозорци, отворени в него.
Това правило позволява на целия модел със слоеве да работи заедно. Всички плаващи слоеве се позиционират чрез фиксирани координати, които се отнасят до визуалния прозорец само ако между тях и него няма трансформиран предшественик:
- Менюто и комбинираното поле изчисляват позицията си спрямо задействащия елемент чрез стратегията
fixedна Floating UI: отварят се под него и се обръщат или изместват, когато във визуалния прозорец няма достатъчно място. - Списъкът за избор прави същото, когато няма избрана опция. Ако вече има избрана опция, вместо това изскачащият прозорец се подравнява така, че избраната опция да е точно над задействащия елемент, и се ограничава в рамките на визуалния прозорец, както при вградените списъци за избор в macOS.
- Контекстното меню се отваря при координатите
clientX/clientYна показалеца.
Тъй като най-горният модален прозорец не е трансформиран, всички тези изскачащи прозорци се закотвят правилно към задействащите ги елементи в диалогов прозорец, предупредителен диалогов прозорец или страничен панел, независимо колко са вложени. Изскачащите прозорци не знаят, че се намират в модален прозорец, и няма нужда да знаят.
Escape първо затваря най-вътрешния слой
Едно натискане на Escape затваря точно един слой, отвътре навън:
- Първо се затваря отворен плаващ слой (списък за избор, меню, изскачащ прозорец, изскачащ прозорец за дата или телефонен номер) и фокусът се връща към задействащия го елемент. Списъкът за избор спира разпространението на събитието, а обработчиците на модалните прозорци също не реагират, когато има отворен плаващ слой, така че диалоговият прозорец отдолу не улавя това натискане.
- След това се затваря най-горният модален прозорец.
- При няколко подредени модални прозореца всяко следващо натискане на Escape премахва още един от стека.
Затварянето следва зададени правила, а не става случайно. Диалогов прозорец, изобразен с dismissable="false", игнорира и Escape, и щракванията върху фона. А bsui/alert-dialog реагира на Escape като всеки модален прозорец, но умишлено игнорира щракванията върху фона: целта на този модел е решението да бъде взето съзнателно, вместо прозорецът да се затвори по погрешка. Щракване върху фона затваря обикновен диалогов прозорец, тъй като dismissable е true по подразбиране.
Формуляр в диалогов прозорец
Този модел задейства едновременно всички горни правила: задействащ елемент отваря модален прозорец, той съдържа формуляр с проверка на данните, а формулярът съдържа плаващ списък за избор.
<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>
Всеки от горните тагове и атрибути е необходим: задействащият елемент препраща към системния бутон, заглавието и описанието приемат content, полетата носят имената, които формулярът сериализира, а required="true" се преобразува в действителна булева стойност от анализатора на тагове.
Какво прави всяко хранилище по време на изпълнение
bsui/dialog зарежда {"open":false,"dismissable":true} в контекста на сървъра. При щракване върху задействащия елемент се изпълнява actions.open: изскачащият прозорец и фонът се преместват в портала към body, превъртането се заключва с компенсация за лентата за превъртане, изскачащият прозорец се анимира за 150ms, фокусът се премества към първия елемент, към който може да се премине с фокус, а Tab се придвижва циклично в него. Областите за горен колонтитул, съдържание и долен колонтитул се разполагат с отстоянията на модалните токени за интервал.
bsui/select изчаква във формуляра със своя списък за избор hidden. Щракването върху задействащия елемент превключва context.open, позиционира списъка с фиксирани координати спрямо визуалния прозорец и понеже defaultValue="editor" вече е избрано, подравнява изскачащия прозорец така, че Editor да е точно над задействащия елемент. Клавишите със стрелки, Home, End и въвеждането на текст преместват активната опция; Enter или щракване я избира, а Tab и щракванията извън списъка го затварят, без да избират опция. Видимият текст на задействащия елемент се обновява чрез data-wp-text="state.displayValue", а скритото <input name="role"> следи стойността чрез data-wp-bind--value="state.selectedValue", която формулярът по-късно сериализира. Всичко това се закотвя правилно в диалоговия прозорец, защото най-горният модален прозорец не е трансформиран.
bsui/form прихваща изпращането. bsui/button в края на формуляра визуализира обикновен елемент button без атрибут type, затова по подразбиране той е контролът за изпращане на формуляра според HTML; бутонът „Отказ“ е в долния колонтитул, извън елемента form, и не може да изпрати нищо. При изпращане хранилището сериализира FormData на формуляра и го изпраща чрез данните API на блока, посочен в block, като тук създава ред според team/inviteсхемата на базата данни. Грешките при валидация се връщат за всяко поле: всяко bsui/field получава своето name, маркира се като невалидно, цветът на контура при фокус се сменя с цвета за разрушителни действия и съобщението се показва в неговото предупреждение bsui/field-error. При успех тялото на формуляра се скрива и се показва successMessage, като и двете действия се изпълняват чрез data-wp-bind--hidden.
Слоевете се затварят по ред. Когато списъкът за избор е отворен, Escape го затваря и връща фокуса към задействащия елемент на списъка; следващото натискане на Escape затваря диалоговия прозорец и връща фокуса към Invite teammate. Щракване върху фона затваря диалоговия прозорец, защото dismissable е оставено със стойността си по подразбиране. При затваряне превъртането се отключва, а изскачащият прозорец се премества отново от портала на мястото си в документа.
Същата маркировка, поставена във файлова страница, се синхронизира като вградени блокове, а същата композиция, сглобена в редактора, се визуализира интерактивно в платното, защото всички описани поведения се задават с директиви и хранилища, които се зареждат и в двата контекста.
Какво поддържа работата на тези свързващи елементи
Свързващите елементи по-горе не са условности, а гарантирани правила, които библиотеката спазва навсякъде, където изобразява съдържание: всеки етикет се визуализира с еднаква типография, всеки модален изскачащ прозорец има една и съща повърхност и затъмнява страницата зад себе си, плаващите изскачащи прозорци остават закотвени към задействащия елемент при превъртане на страницата, а Escape затваря точно по един слой, отвътре навън. Гаранциите важат във фронтенда и в платното на редактора, както при токените по подразбиране, така и при тези на вашата тема. Затова композиция, която работи в единия контекст, ще работи по същия начин и в другите.
Примери на живо
Композициите на тази страница показват граматиката; /ui/examples е разговорникът. Той събира изобразени композиции на живо в три нива: двойки, които демонстрират връзка между два или три компонента, разпознаваеми продуктови модели, изградени от няколко компонента, и завършени миниприложения, сглобени така, както компонентите се доставят в реални продукти. Страницата на всеки компонент в /ui съдържа и свои практически примери — от поле с етикет до календар зад изскачащ прозорец.
Директивите и моделът с хранилища, върху които са изградени компонентите UI, и как да ги използвате в собствените си блокове.