Перейти к содержимому

Компоненты

Blockstudio включает 59 UI компонентов в каждой сборке. Они регистрируются автоматически, оформляются с помощью дизайн-токенов и создаются с тем же синтаксисом тегов, что и любые другие блоки.

Blockstudio 7.3 включает набор готовых блоков UI без интерфейса, работающих на основе WordPress Interactivity API. Они регистрируются в пространстве имён bsui/* и могут использоваться в шаблонах, страницах с файловой структурой, паттернах и содержимом записей.

Примечание

Компоненты UI находятся в стадии бета-тестирования: мы собираем отзывы о наборе компонентов, их названиях, поведении и способах использования в проектах. Их уже можно попробовать в версии 7.3, но интерфейс API может измениться до присвоения стабильного статуса.

Включение компонентов UI

Готовые компоненты UI по умолчанию отключены. Включите их в blockstudio.json своей темы:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

Или включите их с помощью фильтра:

PHP
add_filter('blockstudio/settings/ui/enabled', '__return_true');

После включения Blockstudio регистрирует библиотеку готовых компонентов из includes/ui/blocks.

Общедоступный каталог и примеры

Реализующие их блоки остаются обычными регистрациями bsui/*, но при создании галереи компонентов следует использовать общедоступный каталог семейств:

PHP
use Blockstudio\Ui;

$families = Ui::inventory();
$examples = Ui::examples();

Ui::inventory() группирует составные компоненты по общедоступным корневым компонентам и перечисляет регистрации компонентов, необходимые для каждого семейства. Ui::examples() добавляет детерминированное нормализованное объявление со значениями по умолчанию и примерами данных. Оно сохраняет обязательные связи корневых и дочерних компонентов, поэтому результат можно напрямую передать в Blockstudio\Render::document().

Общедоступный каталог Canvas предоставляет эти примеры с типом ui и исключает регистрации готовых компонентов из обычного типа blocks. Так для каждого общедоступного семейства компонентов создаётся один полный пример, а не галерея из внутренних фрагментов корневых компонентов, триггеров, всплывающих окон и слоёв.

При сборке уже отрисованного документа Ui::global_assets($block_names, $html) возвращает точные глобальные стили и скрипт из набора только в том случае, если в выбранном UI выводе используется компонент.

Рендеринг

Используйте обычный синтаксис тегов блоков:

HTML
<block name="bsui/button" label="Save" variant="default"></block>

Можно использовать и сокращённый синтаксис <bs:>:

HTML
<bs:bsui-button label="Save" variant="default" />

В шаблонах Blockstudio теги блоков отображаются автоматически. На страницах с файловой структурой и в паттернах они синхронизируются как нативные блоки WordPress. Чтобы отображать компоненты UI непосредственно в содержимом записей или областях виджетов, включите теги блоков на уровне страницы:

JSON
{
  "ui": {
    "enabled": true
  },
  "blockTags": {
    "enabled": true,
    "allow": ["bsui/*", "app/*"]
  }
}

Базовые компоненты

Простые компоненты отображаются как один блок:

HTML
<block name="bsui/button" label="Continue" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
  name="bsui/input"
  nameAlt="email"
  type="email"
  placeholder="Email"
></block>
<block name="bsui/textarea" name="message" placeholder="Message"></block>
<block name="bsui/spinner"></block>

Атрибуты напрямую соответствуют атрибутам block.json каждого компонента. Например, bsui/button поддерживает label, icon, iconPosition, href, variant, size и disabled.

PHP
bs_render_block([
  'name' => 'bsui/button',
  'data' => [
    'label' => 'Continue',
    'icon' => [
      'set' => 'heroicons',
      'subSet' => 'outline',
      'icon' => 'arrow-right',
    ],
    'iconPosition' => 'right',
  ],
]);

Составные компоненты

Многие компоненты UI состоят из нескольких блоков. Корневой блок управляет состоянием, а дочерние блоки указывают своего родителя.

Вкладки

HTML
<block name="bsui/tabs" defaultValue="tab1">
  <block name="bsui/tabs-list">
    <block name="bsui/tabs-trigger" value="tab1" title="Features"></block>
    <block name="bsui/tabs-trigger" value="tab2" title="Pricing"></block>
    <block name="bsui/tabs-trigger" value="tab3" title="FAQ"></block>
  </block>
  <block name="bsui/tabs-panel" value="tab1">
    <p>Features content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab2">
    <p>Pricing content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab3">
    <p>FAQ content.</p>
  </block>
</block>

Диалоговое окно

HTML
<block name="bsui/dialog">
  <block name="bsui/dialog-trigger" label="Open Dialog"></block>
  <block name="bsui/dialog-backdrop"></block>
  <block name="bsui/dialog-popup">
    <p>Dialog content.</p>
    <block name="bsui/dialog-close" label="Close"></block>
  </block>
</block>

Список выбора

HTML
<block name="bsui/select" placeholder="Choose a fruit" nameAlt="fruit">
  <block name="bsui/select-trigger"></block>
  <block name="bsui/select-popup">
    <block name="bsui/select-option" value="apple" label="Apple"></block>
    <block name="bsui/select-option" value="banana" label="Banana"></block>
    <block name="bsui/select-option" value="cherry" label="Cherry"></block>
  </block>
</block>

Поля формы

HTML
<block name="bsui/form" block="contact/form" successMessage="Thank you!">
  <block name="bsui/field">
    <block name="bsui/field-label" text="Email"></block>
    <block name="bsui/input" nameAlt="email" type="email"></block>
    <block name="bsui/field-error"></block>
  </block>
</block>

Доступные блоки

В библиотеку готовых компонентов UI входят:

Область Блоки
Компоновка bsui/aspect-ratio, bsui/card, bsui/separator, bsui/stack, bsui/table
Действия bsui/button, bsui/button-group, bsui/toggle, bsui/toggle-group, bsui/toolbar
Ввод bsui/checkbox, bsui/color-picker, bsui/date-input, bsui/file-upload, bsui/input, bsui/number-field, bsui/otp-input, bsui/password-input, bsui/phone-input, bsui/radio-group, bsui/rating, bsui/select, bsui/slider, bsui/switch, bsui/textarea, bsui/time-picker
Наложения bsui/alert-dialog, bsui/dialog, bsui/drawer, bsui/menu, bsui/menubar, bsui/popover, bsui/preview-card, bsui/tooltip
Навигация bsui/accordion, bsui/breadcrumb, bsui/carousel, bsui/collapsible, bsui/context-menu, bsui/navigation-menu, bsui/pagination, bsui/tabs
Обратная связь bsui/badge, bsui/kbd, bsui/meter, bsui/progress, bsui/skeleton, bsui/spinner, bsui/text, bsui/toast
Формы bsui/field, bsui/field-group, bsui/form

Составные компоненты также предоставляют дочерние блоки, например bsui/dialog-trigger, bsui/dialog-popup, bsui/tabs-list, bsui/tabs-trigger, bsui/tabs-panel, bsui/select-trigger, bsui/select-popup и bsui/select-option.

Стилизация

Компоненты UI поставляются со своими пользовательскими свойствами CSS с префиксом --bs-ui-*. Их можно переопределить в CSS своей темы:

CSS
:root {
  --bs-ui-radius: 0.5rem;
  --bs-ui-primary: oklch(0.45 0.18 260);
  --bs-ui-primary-foreground: white;
}

Компоненты не задают поведение, но содержат достаточно рекомендаций, чтобы сразу приступить к работе. Сначала переопределите токены, затем при необходимости добавьте специфичные для компонентов CSS.

Стили готовых компонентов CSS выводятся в именованный каскадный слой bsui. Стили CSS темы, не включённые в слой, могут переопределять правила компонентов без !important:

CSS
.button-brand {
  background: var(--brand-primary);
}

Чтобы добавить пользовательский вариант bsui/button, добавьте параметр списка выбора, используя существующий фильтр атрибутов, и укажите CSS варианта с помощью blockstudio/ui/button/variants-style:

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (($block['name'] ?? '') === 'bsui/button' && ($attribute['id'] ?? '') === 'variant') {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

add_filter('blockstudio/ui/button/variants-style', function($css) {
  return $css . '
[data-bsui-button][data-variant="brand"] {
  background: var(--brand-primary);
  color: white;
}';
});

Все компоненты

Аккордеон Секции расположены друг над другом; одновременно раскрывается только одна панель. Диалоговое окно с предупреждением Модальное окно, прерывающее работу и требующее ответа перед закрытием. Соотношение сторон Фиксирует содержимое в заданном соотношении ширины и высоты. Аватар Изображение пользователя, при ошибке загрузки заменяемое инициалами. Значок Небольшая метка для статуса, количества и категорий. Хлебные крошки Показывает положение текущей страницы в иерархии. Кнопка Выполняет действие; есть варианты для разной степени акцента. Группа кнопок Объединяет связанные кнопки в один сегментированный элемент управления. Календарь Календарная сетка для выбора одного дня. Карточка Область с заголовком, основным содержимым и нижним колонтитулом. Карусель Прокручиваемая лента слайдов с поддержкой клавиатуры. Флажок Бинарный переключатель с поддержкой неопределенного состояния. Сворачиваемый блок Скрывает и показывает одну область содержимого. Выбор цвета Выбирает цвет и отправляет его вместе с остальными данными формы. Поле с выпадающим списком Текстовое поле, которое фильтрует список вариантов по мере ввода. Контекстное меню Действия, открывающиеся при щелчке правой кнопкой мыши и привязанные к указателю. Ввод даты Маскированное поле для ввода дат без календаря. Диалоговое окно Модальный слой для сосредоточенной работы и подтверждений. Боковая панель Панель, выезжающая с любой стороны экрана. Поле Объединяет элемент управления с подписью, описанием и сообщением об ошибке. Группа полей Группирует связанные поля под общим заголовком. Загрузка файла Область перетаскивания и выбора файлов с поддержкой нескольких файлов. Форма Отправляет данные полей и сообщает об успехе без перезагрузки страницы. Ввод Однострочное текстовое поле для всех распространенных типов ввода. Сочетание клавиш Отображает сочетание клавиш в виде отдельной клавиши. Подпись Подпись к элементу управления, общая для всех компонентов с метками. Меню Выпадающий список действий, привязанный к элементу-триггеру. Строка меню Горизонтальная панель меню, как в настольном приложении. Индикатор уровня Показывает измеренное значение в заданном диапазоне. Меню навигации Навигация по сайту с вложенными ссылками и панелями, появляющимися при наведении. Числовое поле Числовое поле со стрелками и ограниченным диапазоном. Поле ввода одноразового пароля Отдельные ячейки для ввода одноразового кода. Пагинация Ссылки на страницы с переходами назад и вперед и сокращением списка. Поле ввода пароля Поле пароля с переключателем видимости. Поле ввода телефона Поле телефона с выбором страны и форматированием. Всплывающее окно Форматированное содержимое, привязанное к элементу-триггеру и закрываемое щелчком вне его. Карточка предпросмотра Карточка при наведении, показывающая, куда ведет ссылка. Ход выполнения Показывает ход выполнения задачи. Группа переключателей Набор вариантов, из которых можно выбрать ровно один. Оценка Звездный элемент управления для выставления оценки. Область прокрутки Контейнер прокрутки со стилизованными полосами прокрутки поверх содержимого. Выберите Выпадающий список для выбора одного из вариантов. Разделитель Линия, разделяющая содержимое или группы элементов управления. Каркас Заполнитель в виде фигуры, отображаемый во время загрузки содержимого. Слайдер Выбор значения или диапазона перетаскиванием вдоль шкалы. Пробел Фиксированный шаг вертикального ритма из шкалы отступов. Спиннер Показывает, что работа выполняется, когда ее длительность неизвестна. Стопка Располагает дочерние элементы в строку или столбец с равномерными промежутками. Переключатель Переключает настройку, которая применяется сразу. Таблица Табличные данные с возможностью сортировки и чередованием цветов строк. Вкладки Переключение между панелями, занимающими одну и ту же область. Text Отображает текст заданного размера с выбранным семантическим тегом. Текстовая область Многострочное текстовое поле, высота которого увеличивается по мере добавления строк. Выбор времени Выбор времени суток с заданным шагом. Провайдер уведомлений Показывает временные уведомления в углу экрана. Переключатель Кнопка, которая остается нажатой, обозначая включенное состояние. Группа переключателей Набор переключателей для выбора одного или нескольких вариантов. Панель инструментов Ряд элементов управления с последовательной передачей фокуса между ними. Всплывающая подсказка Краткая подсказка при наведении или фокусе.