Руководство по Web Components

Нативные пользовательские элементы без среды выполнения фреймворка. Каждый выводит настоящий <button> или <input> в светлом DOM, поэтому формы, CSS и querySelector работают как на написанном вручную HTML.

Что вы создадите

Небольшую форму обратной связи с подписанными полями и кнопкой отправки, связанную несколькими строками скрипта, сначала без оформления, потом с ним, примерно за 10 минут.

Прежде чем начать

Нужны Node.js и сборщик или любая настройка, которая разрешает импорт модулей по имени пакета. Каталог охватывает 626 из 661 компонентов; вложенные элементы таблиц и несколько семейств элементов списков опущены, потому что автономный пользовательский элемент не может заменить <tr> или <li>.

Шаг 1 — Установите и зарегистрируйте

npm install @lilydesignsystem/web-components-headless
<script type="module">
  import "@lilydesignsystem/web-components-headless";
</script>

Импорт пакета определяет все элементы, каждый с именем lily- и идентификатором компонента: <lily-button>, <lily-text-input>, <lily-range-fieldset>.

Шаг 2 — Ваш первый компонент

<lily-button type="submit">Send</lily-button>

Элемент выводит внутри себя настоящий <button class="button"> поэтому Enter, Пробел и роль кнопки работают нативно. Добавленные атрибуты передаются этому внутреннему элементу.

Шаг 3 — Соберите небольшую форму

<lily-form label="Contact us">
  <lily-field label="Full name" required>
    <lily-text-input label="Full name" name="name" autocomplete="name" required></lily-text-input>
  </lily-field>
  <lily-field label="Email" required>
    <lily-email-input label="Email" name="email" required></lily-email-input>
  </lily-field>
  <lily-button type="submit">Send</lily-button>
</lily-form>

<script type="module">
  const form = document.querySelector("lily-form form");
  form.addEventListener("submit", () => {
    const data = new FormData(form);
    console.log(Object.fromEntries(data));
  });
</script>

<lily-form> отменяет переход по странице и даёт событию submit всплыть, так что дальнейшее решает ваш скрипт. Поля — настоящие элементы формы, поэтому FormData их читает.

Проверьте работу: нажимайте Tab по форме, затем отправьте её: в консоли появятся name и email. Оставьте поле пустым, и собственная проверка required браузера остановит отправку.

Шаг 4 — Оформите

Классы стоят на внутренних элементах, поэтому 63 темы и ваш CSS обращаются к ним как к обычному HTML:

<link rel="stylesheet" href="/themes/light.css" />

<style>
  .button { padding: 0.75rem 1.5rem; }
  lily-field { display: block; margin-block-end: 1rem; }
</style>

Нет теневого DOM, через который нужно пробиваться: ничего не скрыто ни от вашей таблицы стилей, ни от вспомогательных технологий.

Шаг 5 — Посмотрите, как всё работает

  • У каждого элемента есть story: pnpm run storybook в lily-design-system-web-components-headless.
  • Помощники тоже выпускаются как пользовательские элементы: <lily-theme-picker>, таблица данных, календарь и другие (@lilydesignsystem/web-components-*).

Что дальше