Веб-компоненти: Створіть повторно використовувані UI-компоненти з Vanilla JavaScript
Навчіться працювати з веб-компонентами крок за кроком, створюючи повторно використовувану UI-карту з Custom Elements, Shadow DOM, HTML Templates, slots та JavaScript-модулями. Не потрібні фреймворки чи інструменти збірки.
Web Components: створюйте повторно використовувані UI-компоненти на чистому JavaScript
Уявіть, що ви створюєте картку для свого сайту, а потім використовуєте її в темі WordPress, розширенні Joomla або окремому застосунку без переписування для кожного середовища.
Це обіцянка Web Components: браузерних нативних інструментів для створення повторно використовуваних HTML-елементів. Для прикладу, який ми збираємося створити, не потрібні React, Vue, npm-пакети чи бандлер.
До кінця цього посібника у вас буде робочий компонент <ui-card> з налаштовуваним вмістом, ізольованими стилями, варіантом featured, кнопкою закриття та публічною подією. Ми створимо його невеликими кроками, щоб ви побачили, який внесок робить кожна технологія.
Що ви створите
Наш готовий компонент підтримуватиме такий 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>
Візуальний попередній перегляд — стандартна та featured-картка
Цей попередній перегляд є цільовим дизайном, а не скриншотом сторонньої бібліотеки. Ми відтворимо його за допомогою наведеного нижче коду.
1. Зрозумійте чотири будівельні блоки
Custom Elements дають змогу зареєструвати новий HTML-тег і його поведінку в JavaScript. Shadow DOM надає елементу власний внутрішній DOM і локальні стилі. HTML-шаблони та слоти дають змогу повторно використовувати структуру, вставляючи різний вміст у кожен екземпляр. ES Modules дають змогу завантажувати компонент зі звичайного файлу JavaScript.
Це окремі функції. Custom Element не обов'язково має використовувати 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. Зареєструйте свій перший Custom Element
Створіть 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 обов'язковий для назв автономних Custom Element. Зворотний виклик може виконатися знову, якщо елемент від'єднано й повторно вставлено, що важливо, коли ми додаємо логіку ініціалізації.
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 і таблицю стилів.
На відміну від звичайних селекторів документа, глобальний CSS, як-от article { border: none }, зазвичай не досягає цього shadow tree. Успадковані властивості та CSS custom properties все ще можуть перетинати межу. Shadow DOM інкапсулює подання; це не пісочниця безпеки.
Захист 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 tree кожної картки. Сам шаблон не відображається, доки ми його не клонуємо й не вставимо.
Ця версія виглядає майже ідентично. Покращення архітектурне: один шаблон може обслуговувати багато екземплярів.
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. Створіть варіант featured за допомогою 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(): вона стилізує компонент на основі атрибутів custom element. Якщо JavaScript пізніше змінить variant, CSS оновиться автоматично. Для зміни, керованої виключно CSS, attributeChangedCallback() не потрібен.
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);
}
Custom properties успадковуються shadow tree і керують значеннями, які ми відкрили. Атрибут part="container" дає змогу зовнішньому CSS націлюватися на вибраний внутрішній елемент за допомогою ::part(container).
Якщо вам потрібен інший фон featured, використовуйте --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, щоб зареєструвати й завантажити модуль. Не розкидайте жорстко закодовані теги script по виробничих шаблонах.
Для картки, згенерованої CMS, відображайте заголовок, абзац і посилання як HTML зі слотами. Екрануйте вміст і атрибути відповідно до правил виводу CMS.
Практична перевага: модуль Joomla і блок WordPress можуть обидва виводити той самий custom-тег, спільно використовуючи одну реалізацію компонента. Кожна CMS і далі відповідає за отримання й екранування власного вмісту.
12. Доступність, SEO та прогресивне покращення
Використовуйте нативні HTML-елементи керування всередині компонентів, коли це можливо. Наша дія закриття використовує справжній button, який забезпечує семантику активації з клавіатури, та aria-label, оскільки сам символ × не є описовим.
Якщо користувач закриває картку, коли фокус перебуває на клавіатурі, подумайте, куди фокус має перейти далі в складнішому інтерфейсі. Діалоги, меню й комбобокси потребують значно більше поведінки для доступності, ніж цей приклад.
Тримайте важливий вміст у змістовній розмітці light DOM, де це практично. Якщо JavaScript не працює, браузер не оновить <ui-card>; заголовок і абзац, вставлені через слоти, залишаться в документі, хоча стилізована оболонка компонента й кнопка закриття не існуватимуть.
Щодо пошукових систем, не припускайте, що вміст, доступний лише через JavaScript, індексується однаково в кожному сканері. Критичний вміст має бути доступним у початковому HTML або через відповідну стратегію рендерингу.
Shadow DOM також має обмеження: звичайні CSS-селектори документа не стилізують внутрішні вузли, а деякі зв'язки ARIA ID не можуть перетинати межі shadow. Проєктуйте API компонентів з урахуванням цих обмежень.
13. Чи завжди Web Components швидші?
Не обов'язково. Web Components уникають потреби в конкретному середовищі виконання фреймворку, але продуктивність залежить від обсягу JavaScript, складності DOM, частоти рендерингу й архітектури застосунку.
Невелика картка — хороший кандидат. Сотні складних елементів із непотрібною перебудовою DOM усе одно можуть працювати повільно. Повторно використовуйте шаблони, уникайте повторного повного рендерингу й вимірюйте реальну продуктивність.
Для великого застосунку, уже побудованого навколо керування станом і маршрутизації фреймворку, використання власних компонентів цього фреймворку може бути простішим. Web Components особливо корисні, коли стабільний UI-елемент має перетинати межі фреймворків або CMS.
14. Усунення несправностей
| Симптом | Ймовірна причина | Що перевірити |
|---|---|---|
| Картка порожня | Модуль не завантажився | Консоль DevTools, URL, MIME-тип сервера |
customElements.define видає помилку |
Неприпустима або повторювана назва | Вимога дефіса та захист реєстрації |
| CSS не застосовується всередині картки | Межа Shadow DOM | Використовуйте custom properties, :host або ::part |
| Вміст з'являється не в тому місці | Невідповідність назви слота | Порівняйте slot="title" з <slot name="title"> |
| Натискання закриття нічого не робить | Кнопка в шаблоні відсутня | Перегляньте shadow tree і консоль |
| Компонент не працює після переміщення | Ініціалізація виконується двічі | Захистіть створення shadow root |
| Посилання веде на 404 | Приклад URL не замінено | Використовуйте наявне призначення |
Пам'ятайте, що connectedCallback() може виконуватися більше одного разу. Захист у нашому фінальному прикладі робить ініціалізацію одноразовою; складніші компоненти можуть потребувати приєднання й видалення зовнішніх спостерігачів або глобальних слухачів подій протягом їхнього життєвого циклу підключення.
15. Коли варто використовувати Web Components?
Обирайте їх, коли компонент потребує повторно використовуваного, задокументованого HTML-інтерфейсу на кількох сайтах, у фреймворках або середовищах CMS. Картки, сповіщення, віджети продуктів і невеликі інтерактивні інструменти — хороші кандидати.
Пропустіть абстракцію, коли кілька рядків звичайного HTML і CSS уже вирішують проблему. І не відтворюйте нативні елементи керування без вагомої причини.
Корисний тест: чи отримала б інша програма користь від використання цього елемента, не знаючи, як його реалізовано? Якщо так, Web Component варто розглянути.
Висновок
Ви створили справжній повторно використовуваний компонент, а не просто прочитали про браузерний API. Він має custom-тег, локальні стилі, налаштовуваний вміст, варіант featured і подію, яку може слухати інший код.
Почніть з одного компонента, який багаторазово з'являється у ваших проєктах. Дайте йому невеликий публічний API, перевірте його в більш ніж одному макеті та зведіть його залежності до мінімуму.
Довгострокова цінність Web Components не в тому, що вони замінюють кожен фреймворк. Вона в тому, що вони дають корисним інтерфейсним елементам пережити фреймворк або CMS, які вперше їх розмістили.