Компоненты
Композиция
Встроенные компоненты 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. Так вспомогательные технологии распознают их как единый элемент управления.
Что происходит внутри API Interactivity
Каждое интерактивное семейство использует 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 указывает, с каким хранилищем они связаны. onChange направляет обработку изменений одному из ваших действий, checked связывает состояние элемента управления с вашим состоянием, а bindText выводит подпись в виде элемента data-wp-text, связанного с любым путем состояния:API
<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 — это путь директивы, а не буквальное значение по умолчанию. Привязку value поддерживают Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating и Time Picker.
Вместо неё для 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;
}
},
},
});
Задайте соответствующее значение по умолчанию для начального значения, отрисовываемого на сервере. После гидратации изменения родителя обновляют все связанные экземпляры, включая значения 0, false и пустые значения. Скрытые поля формы Checkbox и Switch также следуют своей привязке checked. Значения Time Picker задаются в формате 24-часового времени через HH:MM или пустой строкой.
В обработчиках обычных 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 отображает набор полей. Вариант по умолчанию объединяет связанные поля без добавления фоновой области. Используйте 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, из-за чего перестают работать все плавающие всплывающие окна, открытые внутри него.
Это правило позволяет сочетать все слои в единой модели. Все плавающие слои позиционируются с фиксированными координатами, которые отсчитываются от области просмотра, только если между ними и областью просмотра нет трансформированного предка:
- Меню и комбинируемый список вычисляют положение относительно триггера, используя стратегию UI
fixed: раскрываются под ним и переворачиваются или смещаются, когда не хватает места в области просмотра. - Если в списке ничего не выбрано, он ведёт себя так же. Если же выбранный элемент есть, всплывающее окно выравнивается так, чтобы выбранный вариант находился прямо над триггером, и ограничивается областью просмотра, как в нативных списках выбора на 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, прокрутка блокируется с компенсацией ширины полосы прокрутки, окно анимированно появляется за 150мс, фокус переходит на первый элемент, доступный для фокусировки, а клавиша 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/invitedatabase schema. Ошибки проверки возвращаются для каждого поля: для каждого bsui/field передается name, поле помечается как недействительное, фокусная рамка меняет цвет на цвет ошибки, а сообщение отображается в предупреждении bsui/field-error. При успешной отправке тело формы скрывается и отображается successMessage; оба действия выполняются с помощью data-wp-bind--hidden.
Слои закрываются в обратном порядке. Если список выбора открыт, Escape закрывает его и возвращает фокус к триггеру списка; следующее нажатие Escape закрывает диалоговое окно и возвращает фокус к кнопке Invite teammate. Щелчок по фону закрывает диалоговое окно, поскольку dismissable осталось со значением по умолчанию. При закрытии прокрутка снова становится доступной, а всплывающее окно возвращается на прежнее место в документе.
Та же разметка, вставленная в страницу с файловой структурой, синхронизируется как нативные блоки, а та же композиция, собранная в редакторе, отображается на холсте в интерактивном режиме. Это возможно, поскольку все описанные выше механизмы работают через директивы и хранилища, загружаемые в обоих контекстах.
Что обеспечивает работу этих связей
Описанные выше связи — не соглашения, а инварианты, которые библиотека поддерживает везде, где выполняется отрисовка: каждой метке соответствует одна и та же типографика, все всплывающие окна модального слоя используют единую поверхность и затемняют страницу позади, плавающие окна сохраняют привязку к триггеру при прокрутке страницы, а Escape каждый раз закрывает ровно один слой, начиная с самого вложенного. Эти гарантии действуют во внешней части сайта и на холсте редактора — с токенами по умолчанию или токенами вашей темы. Поэтому композиция, работающая в одном контексте, так же работает и в остальных.
Интерактивные примеры
Композиции на этой странице показывают грамматику, а /ui/examples — сборник примеров. В нём собраны интерактивные композиции трёх уровней: пары, демонстрирующие связь двух или трёх компонентов; узнаваемые шаблоны продуктов, созданные из нескольких компонентов; и полноценные мини-приложения, собранные так же, как компоненты используются в реальных продуктах. На каждой странице компонента в разделе /ui есть собственные примеры: от поля с меткой до календаря во всплывающем окне.
О директивах и модели хранилищ, на которых построены компоненты UI, и о том, как использовать их в своих блоках.