Перейти до вмісту

Компоненти

Blockstudio постачається з 59 UI компонентами в кожній збірці. Вони реєструються автоматично, стилізуються за допомогою токенів дизайну та створюються з тим самим синтаксисом тегів, що й будь-який інший блок.

Blockstudio 7.3 містить вбудований набір безголових блоків UI на основі WordPress Інтерактивності 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;
}';
});

Усі компоненти

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