Технологическая отрасль

Веб-компоненты: создание повторяемых UI-компонентов с использованием чистого JavaScript

Web Components: Build Reusable UI Components with Vanilla JavaScript

Изучите веб-компоненты пошагово, создавая повторяемую UI-карточку с помощью пользовательских элементов, Shadow DOM, HTML-шаблонов, слотов и JavaScript-модулей. Не требуется фреймворк или сборочные инструменты.

Веб-компоненты: создание повторяемых UI-компонентов с помощью Vanilla JavaScript

Представьте, что вы создали карточку для своего сайта и затем использовали её в теме WordPress, расширении Joomla или автономном приложении, не переписывая её для каждой среды.

Именно это и предлагают веб-компоненты — встроенные в браузер инструменты для создания повторяемых HTML-элементов. Для примера, который мы будем создавать, не нужны ни React, ни Vue, ни npm-пакеты, ни бандлер.

К концу этого урока у вас будет работающий компонент с именем <ui-card>, который будет иметь настраиваемое содержимое, изолированные стили, фичерованный вариант, кнопку удаления и публичное событие. Мы создаем его пошагово, чтобы вы могли увидеть, что вносит каждая технология.

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

Наш готовый компонент будет поддерживать следующий HTML-код:

<ui-card variant="featured">
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

Предварительный просмотр — стандартные и фичерованные карточки

Предварительный просмотр стандартных и фичерованных карточек веб-компонента

Этот предварительный просмотр является целевым дизайном, а не скриншотом какой-либо другой библиотеки. Мы воссоздадим его с помощью приведенного ниже кода.

1. Понимание четырех строительных блоков

Пользовательские элементы позволяют нам зарегистрировать новый HTML-тэг и его JavaScript-поведение. Shadow DOM дает элементу собственный внутренний DOM и ограниченные стили. HTML-шаблоны и слоты позволяют нам повторно использовать структуру, вставляя при этом различное содержимое в каждый экземпляр. ES-модули позволяют нам загружать компонент из обычного JavaScript-файла.

Это отдельные функции. Пользовательский элемент не обязательно должен использовать Shadow DOM, и вам не нужен фреймворк для использования любой из них.

2. Создание файлов проекта

Создайте следующую структуру в своем редакторе:

web-components-demo/
├── index.html
├── components/
│   └── ui-card.js
└── css/
    └── main.css

Поместите это в index.html:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Web Components Demo</title>
  <link rel="stylesheet" href="./css/main.css">
  <script type="module" src="./components/ui-card.js"></script>
</head>
<body>
  <main class="container">
    <h1>Reusable UI Components</h1>
    <p>Let's build a reusable card without a framework.</p>
    <ui-card></ui-card>
  </main>
</body>
</html>

Добавьте стили страницы в css/main.css:

body {
  margin: 0;
  background: #f4f6f9;
  color: #1f2937;
  font-family: system-ui, sans-serif;
}
.container {
  max-width: 900px;
  margin: 60px auto;
  padding: 0 20px;
}
ui-card {
  display: block;
  margin-top: 24px;
}

Запустите локальный HTTP-сервер из директории проекта, например:

python -m http.server 8000

Перейдите по адресу http://localhost:8000. Заголовок появляется, но у карточки пока нет видимого содержимого. Используйте HTTP-сервер, а не открывайте index.html с file://: правила загрузки модулей браузера могут блокировать локальные импорты файлов.

3. Регистрация вашего первого пользовательского элемента

Создайте components/ui-card.js:

class UiCard extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from a Web Component!';
  }
}

customElements.define('ui-card', UiCard);

Обновите страницу. Теперь вы должны увидеть:

Ожидаемый результат — Шаг 3

Результат первого пользовательского элемента

HTMLElement обеспечивает нормальное DOM-поведение. connectedCallback() выполняется, когда элемент подключается к документу. customElements.define() связывает класс с HTML-тэгом.

Гифен в ui-card является обязательным для автономных имен пользовательских элементов. Коллбэк может выполниться снова, если элемент отключен и повторно вставлен, что важно при добавлении логики инициализации.

4. Придайте карточке свой собственный дизайн с помощью Shadow DOM

Замените ui-card.js на:

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });

    shadow.innerHTML = `
      <style>
        article {
          padding: 24px;
          background: white;
          border: 1px solid #dce3ec;
          border-radius: 12px;
        }
        h2 {
          margin: 0 0 12px;
          color: #2563eb;
        }
      </style>
      <article>
        <h2>My reusable card</h2>
        <p>This content lives inside Shadow DOM.</p>
      </article>
    `;
  }
}

customElements.define('ui-card', UiCard);

Ожидаемый результат — Шаг 4

Карточка со стилями внутри Shadow DOM

Откройте DevTools, инспектируйте <ui-card> и разверните #shadow-root (open). Вы увидите внутренний article и stylesheet.

В отличие от обычных селекторов документа, глобальный CSS, такой как article { border: none }, обычно не достигает этого shadow-дерева. Наследуемые свойства и CSS-кэстомные свойства все еще могут пересекаять границу. Shadow DOM инкапсулирует презентацию; он не является sandbox'ом безопасности.

ПРЕДОСТАВЛЯЕМЫЙ ОГРАНИЧИТЕЛЬ В if (this.shadowRoot) предотвращает прикрепление второй shadow root, если элемент переподключается.

5. Разделение разметки с помощью HTML-шаблона

Вкладывание всего внутрь connectedCallback() становится неудобным, как только компонент растет. Давайте определим разметку один раз и клонируем её для каждой карточки.

Замените файл на:

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 {
      margin: 0 0 12px;
      color: #2563eb;
    }
  </style>
  <article>
    <h2>My reusable card</h2>
    <p>Created from an HTML template.</p>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('ui-card', UiCard);

template.content — это фрагмент документа. cloneNode(true) копирует всю структуру в shadow-дерево каждой карточки. Сам шаблон не рендерится до тех пор, пока мы не клонируем и вставим его.

Эта версия выглядит почти идентично. Улучшение — архитектурное: один шаблон может обслуживать множество экземпляров.

6. Вставка различного содержимого с помощью слотов

Повторяемый кардек не полезен, если каждый экземпляр имеет одинаковую заголовку. Замените только объявление шаблона в верхней части ui-card.js на следующее; сохраните код класса и регистрации из Шага 5.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 { margin: 0 0 12px; color: #2563eb; }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
  </style>
  <article>
    <h2><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

Теперь замените <ui-card></ui-card> в index.html на:

<ui-card>
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

Ожидаемый результат — Шаг 6

Карточка с именованными слотами и ссылкой на действия

Именованный слот получает элемент, помеченный slot="title". Неименованный слот получает абзац. Слот действий получает ссылку. Текст, который отображается по умолчанию в слоте, появляется, если к нему ничего не назначено.

Разметка живет в компоненте; реальные слова и ссылки остаются в HTML страницы. Это особенно полезно для контента CMS. Замените /tutorial на реальное назначение в вашем проекте.

7. Создание фичерованного варианта с помощью CSS

Внутри <style> блока шаблона добавьте:

:host {
  display: block;
}
:host([variant="featured"]) article {
  background: #eff6ff;
  border-color: #93c5fd;
}

Затем замените одну карточку в index.html на две карточки:

<ui-card>
  <span slot="title">Standard card</span>
  <p>This card uses the default appearance.</p>
</ui-card>

<ui-card variant="featured">
  <span slot="title">Featured card</span>
  <p>This card has a highlighted appearance.</p>
</ui-card>

Ожидаемый результат — Шаг 7

Стандартные и фичерованные варианты карточек

Это особенно полезная фичет :host(): он стилизует компонент на основе атрибутов пользовательского элемента. Если JavaScript изменяет variant позже, CSS обновляется автоматически. Нет необходимости в attributeChangedCallback() для чисто CSS-управляемых изменений.

8. Добавление кнопки удаления и публичного события

Давайте сделаем карточку интерактивной. Внутри <article> блока шаблона добавьте эту кнопку перед заголовком:

<button class="dismiss" type="button" aria-label="Dismiss card">
  ×
</button>

Добавьте эти правила в CSS шаблона:

article { position: relative; }
.dismiss {
  position: absolute;
  top: 12px;
  right: 12px;
  width: 32px;
  height: 32px;
  border: 0;
  border-radius: 6px;
  background: transparent;
  color: #475569;
  font-size: 24px;
  cursor: pointer;
}
.dismiss:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

Замените connectedCallback() в классе на:

connectedCallback() {
  if (this.shadowRoot) return;

  const shadow = this.attachShadow({ mode: 'open' });
  shadow.appendChild(template.content.cloneNode(true));

  shadow.querySelector('.dismiss').addEventListener('click', () => {
    this.dispatchEvent(new CustomEvent('card-dismissed', {
      bubbles: true,
      composed: true
    }));
    this.remove();
  });
}

В index.html добавьте этот скрипт перед </body>:

<script type="module">
  document.addEventListener('card-dismissed', () => {
    console.log('A card was dismissed.');
  });
</script>

Откройте консоль браузера и нажмите ×. Карточка исчезает, и в консоли отображается сообщение.

Событие обеспечивает публичный интеграционный пункт: окружающее приложение не нужно знать ничего о внутренней кнопке карточки. bubbles делает событие пузырьком; composed разрешает пересекая shadow-границу, когда это применимо. Здесь событие происходит на самом хост-элементе.

9. Полная финальная версия: копирование и использование

Теперь вы можете заменить весь контент components/ui-card.js этим консолидированным вариантом. Он добавляет CSS-настраиваемость и экспортированные части, сохраняя поведение, построенное на предыдущих этапах.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    :host {
      display: block;
      color: #1f2937;
      font-family: system-ui, sans-serif;
    }
    article {
      position: relative;
      box-sizing: border-box;
      padding: 24px;
      background: var(--card-background, #fff);
      border: 1px solid var(--card-border, #dce3ec);
      border-radius: 12px;
    }
    :host([variant="featured"]) article {
      background: var(--card-featured-background, #eff6ff);
      border-color: var(--card-featured-border, #93c5fd);
    }
    h2 {
      margin: 0 36px 12px 0;
      color: var(--card-title-color, #2563eb);
      font-size: 1.25rem;
    }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
    .dismiss {
      position: absolute;
      top: 12px;
      right: 12px;
      width: 32px;
      height: 32px;
      border: 0;
      border-radius: 6px;
      background: transparent;
      color: #475569;
      font-size: 24px;
      cursor: pointer;
    }
    .dismiss:hover { background: rgba(0, 0, 0, 0.06); }
    .dismiss:focus-visible {
      outline: 2px solid #2563eb;
      outline-offset: 2px;
    }
  </style>
  <article part="container">
    <button class="dismiss" type="button"
            aria-label="Dismiss card">×</button>
    <h2 part="title"><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));

    shadow.querySelector('.dismiss').addEventListener('click', () => {
      this.dispatchEvent(new CustomEvent('card-dismissed', {
        bubbles: true,
        composed: true,
        detail: {
          variant: this.getAttribute('variant') || 'default'
        }
      }));
      this.remove();
    });
  }
}

if (!customElements.get('ui-card')) {
  customElements.define('ui-card', UiCard);
}

В отличие от быстрого демо, эта версия не пытается прикрепить shadow root дважды, не вставляет ненадежное содержимое с innerHTML и не зависит от фреймворка. Шаблонная строка контролируемая разработчиком; никогда не интерполируйте ненадежный пользовательский ввод в неё.

10. Стилизация компонента на хостинг-веб-сайте

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

В css/main.css добавьте:

ui-card {
  --card-border: #cbd5e1;
  --card-title-color: #0f766e;
}
ui-card::part(container) {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}

Кастомные свойства наследуются shadow tree и контролируют значения, которые мы раскрыли. Атрибут part="container" позволяет внешнему CSS целиться в выбранный внутренний элемент с ::part(container).

Если вам нужен другой фичерованный фон, используйте --card-featured-background. Это предпочтительнее, чем принуждать потребителей зависеть от точной внутренней DOM-структуры.

11. Повторное использование карточки в WordPress, Joomla или обычном HTML

Скопируйте ui-card.js в целевой веб-сайт и загрузите его как JavaScript-модуль:

<script type="module" src="/assets/js/ui-card.js"></script>

Затем используйте <ui-card> в разметке страницы. В WordPress зарегистрируйте активы через тему или плагин с помощью поддерживаемых API загрузки скриптов, используя модуль поддержки, подходящий к вашей версии WordPress. В Joomla используйте Web Asset Manager для регистрации и загрузки модуля. Не рассылайте хардкодированные скрипт-тэги через производственные шаблоны.

Для CMS-генерации карточки рендерите заголовок, абзац и ссылку как слотовое HTML. Эскейпите контент и атрибуты согласно правилам вывода CMS.

Практическая выгода: Joomla-модуль и WordPress-блок могут оба выводить один и тот же пользовательский тэг, пока делятся одной и той же компонентной реализацией. Каждый CMS остается ответственным за извлечение и эскейпирование своего собственного контента.

12. Доступность, SEO и прогрессивное улучшение

Используйте нативные HTML-контроли внутри компонентов, когда это возможно. Наше действие удаления использует реальный button, который обеспечивает семантику активации с клавиатуры, и aria-label, потому что × один не описателен.

Если пользователь удаляет карточку с фокусом клавиатуры, подумайте, куда фокус должен перейти следующим в более сложном интерфейсе. Диалоги, меню и комбобоксы нуждаются во много больше поведения доступности, чем этот пример.

Сохраните важный контент в осмысленной light-DOM-разметке, когда это практический. Если JavaScript не работает, браузер не улучшит <ui-card>; слотовые заголовок и абзац остаются в документе, хотя стилизованный каркас компонента и кнопка удаления не существуют.

Для поисковых систем не предполагайте, что JavaScript-контролируемый контент индексируется идентично в каждом крэкере. Критический контент должен быть доступен в начальном HTML или через соответствующую стратегию рендеринга.

Shadow DOM также имеет ограничения: обычные селекторы документа не стилизуют внутренние ноды, и некоторые ARIA ID-отношения не могут пересино через shadow-границы. Проектируйте API компонента с этими ограничениями в виду.

13. Всегда ли Веб-компоненты быстрее?

Не обязательно. Веб-компоненты избегают требования к определенному фреймворк-рассысанию, но производительность зависит от количества JavaScript, сложности DOM, частоты рендеринга и архитектуры приложения.

Небольшая карточка — хороший кандидат. Сотни сложных элементов с ненужным перестроением DOM могут все еще быть медленными. Повторно используйте шаблоны, избегайте повторного полного рендеринга и измерьте реальную производительность.

Для большого приложения, уже построенного вокруг фреймворк-управления состоянием и маршрутизации, использование компонентв самого фреймворка может быть проще. Веб-компоненты сияют, когда стабильный UI-элемент нуждается в перекрестии через фреймворк или CMS границы.

14. Устранение неполадок

Симптом Вероятная причина Что проверить
Карточка пуста Модуль не загрузился консоль DevTools, URL, серверный MIME type
customElements.define бросает Неверное или дублирующееся имя требование к гифену и guard регистрации
CSS не применяется внутри карточки Граница Shadow DOM Используйте кастомные свойства, :host или ::part
Контент появляется в неправильном месте Несоответствие имени слота Сравните slot="title" с <slot name="title">
Нажатие на удаление ничего не делает Кнопка шаблона отсутствует Инспектируйте shadow tree и консоль
Компонент не работает, когда перемещен Инициализация выполняется дважды Guard создания shadow root
Ссылка ведет на 404 URL примера не был заменен Используйте существующее назначение

Помните, что connectedCallback() может выполниться больше одного раза. Guard в нашем финальном примере сохраняет инициализацию одноразово; более сложные компоннеты могут нуждаться в прикреплении и удалении внешних наблюдателей или глобальных слушателей событий во время своего жизненного цикла подключения.

15. Когда вам следует использовать Веб-компоненты?

Выбирайте их, когда компонент нуждается в повторяемом, документированном HTML-интерфейсе через несколько веб-сайтов, фреймворков или CMS-сред. Карточки, уведомления, продуктовые виджеты и небольшие интерактивные инструменты — хорошие кандидаты.

Пропустите абстракцию, когда несколько линий обычного HTML и CSS уже решают проблему. И не воссоздавайте нативные контроли без сильной причины.

Полезный тест: воспользуется ли другая приложенческая использование этого элемента без знания того, как он был реализован? Если да, то Веб-компонент стоит рассмотреть.

Заключение

Вы создали реальный повторяемый компонент, а не просто прочитали о браузерном API. У него есть пользовательский тэг, ограниченные стили, настраиваемое содержимое, фичерованный вариант и событие, которое другой код может прослушивать.

Начните с одного компонента, который появляется многократно в ваших проектах. Дайте ему небольшой публичный API, протестируйте его в более чем одном лейауте и сохраните его зависимости минимальными.

Долгосрочная ценность Веб-компонентов не в том, что они заменят каждый фреймворк. Она в том, что они позволяют полезным интерфейсным элементам пережить фреймворк или CMS, которые впервые их хостили.

Официальные справочники