Веб-компоненты: создание повторяемых UI-компонентов с использованием чистого 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
Откройте 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, которые впервые их хостили.