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

Компоненти

Композиція

Вбудовані в UI компоненти створені для спільного використання, а не окремо. Список вибору відкривається в діалоговому вікні, форма перевіряє дані в бічній панелі, а меню розташовується в рядку таблиці. На цій сторінці пояснюється, як усе це працює: як влаштовані складені групи, як тригери передають властивості кнопки, що робить директива Interactivity API і як модель шарів забезпечує узгодженість накладених елементів.

Складені групи

Складений компонент — це кореневий блок і дочірні блоки. Кореневий блок керує станом, а кожен дочірній визначає своє місце в групі через parent і usesContext у своєму block.json:

JSON
{
  "name": "bsui/select-option",
  "parent": ["bsui/select-popup"],
  "usesContext": ["bsui/select"]
}

Кореневі блоки надають область InnerBlocks зі списком allowedBlocks і початковим template. Тож після вставлення діалогового вікна в редактор автоматично створюються його тригер, тло й спливне вікно, а група поводиться однаково незалежно від того, чи її створено в редакторі, на сторінці з файловою структурою, чи в тегах:

HTML
<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:

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 через поле блоку:

JSON
{
  "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.

HTML
<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 безпосередньо з атрибутів блоку:

HTML
<div
  data-wp-interactive="bsui/select"
  data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
  data-bsui-select-root
>

Початкове відображення одразу правильне HTML, без блимання під час гідратації на клієнті; спливні вікна спочатку hidden, а та сама розмітка працює на полотні редактора, адже контекст не залежить від передавання стану лише на фронтенді.

Поведінка задається директивами, а не JavaScript. Шаблони декларативно пов’язують розмітку зі сховищами. Тригер компонента вибору без PHP — це лише директиви:

HTML
<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, прив’язаний до будь-якого шляху стану:

HTML
<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:

PHP
<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>
JavaScript
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 задаються у форматі 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 і обгортати їх у власну структуру:

PHP
<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, щоб отримати внутрішню поверхню вмісту. Залиште заголовок і опис поза цим блоком вмісту:

HTML
<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 не виходить за його межі, а після закриття фокус повертається до тригера.

Модальні вікна утворюють стос. Якщо відкрити діалогове вікно з іншого діалогового вікна, воно додається до спільного стосу: тло показує лише найзовнішнє вікно, а вікна позаду верхнього зменшуються й виглядають з-за нього. Для кожного фонового спливного вікна стос задає власну CSS-властивість --bs-ui-nested-dialogs, тож зі зростанням рівня збільшуються зміщення й масштаб видимої частини; батьківське вікно підлаштовує висоту під дочірнє, щоб шари виглядали рівномірно. Під час закриття все відновлюється у зворотному порядку, по одному шару за раз.

Після закриття модального вікна фокус повертається до його тригера, а саме до потрібного елемента. Спільна допоміжна функція getAnchor визначає системну кнопку всередині обгортки тригера, тож фокус повертається до видимого елемента керування, а не невидимої обгортки.

Верхнє модальне вікно ніколи не трансформується

Ефект підглядання змінює лише фонові діалогові вікна. Верхнє модальне вікно навмисно залишається без трансформації, адже трансформований елемент стає блоком-контейнером для position: fixed нащадків, що порушило б роботу кожного плаваючого спливного вікна, відкритого всередині нього.

Саме це правило дає змогу поєднувати всі рівні в одній моделі. Усі плаваючі шари позиціонуються за фіксованими координатами, які відповідають координатам вікна перегляду, лише якщо між ними немає трансформованого предка:

  • Меню та комбінований список обчислюють своє положення відносно тригера за стратегією fixed від Floating UI: вони відкриваються під ним і перевертаються або зміщуються, коли у вікні перегляду бракує місця.
  • Список вибору поводиться так само, коли нічого не вибрано. Якщо вибір уже є, спливне вікно вирівнюється так, щоб вибрана опція розташовувалася безпосередньо над тригером, у межах вікна перегляду, як у нативних списках вибору в macOS.
  • Контекстне меню відкривається за координатами clientX/clientY вказівника.

Оскільки верхнє модальне вікно не трансформоване, усі ці елементи правильно прив’язуються до своїх тригерів усередині діалогового вікна, діалогового вікна сповіщення або бічної панелі на будь-якій глибині вкладеності. Спливним вікнам не потрібно знати, що вони перебувають у модальному вікні, і це знання їм не потрібне.

Escape спершу закриває найближчий внутрішній шар

Одне натискання Escape закриває рівно один шар, починаючи з внутрішнього:

  1. Спершу закривається відкрите плаваюче вікно (список вибору, меню, спливна панель, вікно вибору дати або телефону), а фокус повертається до його тригера. Список вибору зупиняє поширення події, а обробники модального вікна також не реагують, поки відкрите будь-яке плаваюче вікно, тож діалогове вікно позаду не отримує цього натискання.
  2. Далі закривається верхнє модальне вікно.
  3. Якщо модальні вікна розташовані одне над одним, кожне наступне натискання Escape закриває ще одне з них.

Закриття визначається правилами, а не випадковою поведінкою. Діалогове вікно, відтворене з dismissable="false", ігнорує і Escape, і натискання на тло. А bsui/alert-dialog реагує на Escape, як будь-яке модальне вікно, але навмисно ігнорує натискання на тло: суть цього шаблону в тому, що вибір потрібно зробити, а не закривати вікно випадково. Звичайне діалогове вікно закривається натисканням на тло, оскільки dismissable за замовчуванням має значення true.

Форма в діалоговому вікні

Цей шаблон одночасно задіює всі наведені вище правила: тригер відкриває модальне вікно, у ньому міститься форма з перевіркою, а у формі — плаваючий список вибору.

HTML
<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; кнопка Cancel розташована в нижньому колонтитулі поза елементом 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, а також пояснюють, як використовувати цю модель у власних блоках.