Web Components: Buduj wielokrotnego użytku komponenty UI z Vanilla JavaScript
Naucz się krok po kroku Web Components, budując wielokrotnego użytku kartę UI z Custom Elements, Shadow DOM, HTML Templates, slots i modułami JavaScript. Nie wymaga żadnego frameworka ani narzędzi do budowania.
Web Components: Tworzenie komponentów UI wielokrotnego użytku w czystym JavaScripcie
Wyobraź sobie, że tworzysz kartę dla swojej witryny, a następnie używasz jej w motywie WordPress, rozszerzeniu Joomla lub samodzielnej aplikacji bez przepisywania jej dla każdego środowiska.
To właśnie obiecują Web Components: natywne dla przeglądarki narzędzia do budowania elementów HTML wielokrotnego użytku. Do przykładu, który zbudujemy, nie są potrzebne React, Vue, pakiety npm ani bundler.
Pod koniec tego samouczka będziesz mieć działający komponent <ui-card> z konfigurowalną treścią, izolowanymi stylami, wariantem wyróżnionym, przyciskiem odrzucania oraz publicznym zdarzeniem. Zbudujemy go małymi krokami, abyś zobaczył, co wnosi każda technologia.
Co zbudujesz
Nasza ukończona komponent będzie obsługiwać ten 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>
Podgląd wizualny — standardowe i wyróżnione karty
Ten podgląd jest celem projektowym, a nie zrzutem ekranu niepowiązanej biblioteki. Odtworzymy go za pomocą poniższego kodu.
1. Zrozum cztery elementy składowe
Custom Elements pozwalają zarejestrować nowy tag HTML oraz jego zachowanie w JavaScripcie. Shadow DOM daje elementowi własny wewnętrzny DOM i styl zasięgu ograniczonego. Szablony HTML i sloty pozwalają ponownie wykorzystać strukturę, wstawiając różną treść do każdej instancji. ES Modules pozwalają załadować komponent ze zwykłego pliku JavaScript.
Są to odrębne funkcje. Custom Element nie musi używać Shadow DOM, a do korzystania z któregokolwiek z nich nie potrzebujesz frameworka.
2. Utwórz pliki projektu
Utwórz tę strukturę w swoim edytorze:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Wstaw to do 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>
Dodaj style na poziomie strony do 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;
}
Uruchom lokalny serwer HTTP z katalogu projektu, na przykład:
python -m http.server 8000
Odwiedź http://localhost:8000. Nagłówek się pojawi, ale karta nie ma jeszcze widocznej treści. Użyj serwera HTTP zamiast otwierania index.html za pomocą file://: reguły ładowania modułów w przeglądarce mogą blokować lokalne importy plików.
3. Zarejestruj swój pierwszy Custom Element
Utwórz components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Odśwież stronę. Powinieneś teraz zobaczyć:
Oczekiwany wynik — Krok 3
HTMLElement dostarcza normalne zachowanie DOM. connectedCallback() uruchamia się, gdy element połączy się z dokumentem. customElements.define() kojarzy klasę z tagiem HTML.
Myślnik w ui-card jest wymagany dla nazw autonomicznych Custom Elementów. Callback może zostać uruchomiony ponownie, jeśli element zostanie odłączony i ponownie wstawiony, co ma znaczenie, gdy dodamy logikę inicjalizacji.
4. Nadaj karcie własny wygląd za pomocą Shadow DOM
Zastąp ui-card.js tym:
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);
Oczekiwany wynik — Krok 4
Otwórz DevTools, zbadaj <ui-card> i rozwiń #shadow-root (open). Zobaczysz wewnętrzny artykuł i arkusz stylów.
W przeciwieństwie do zwykłych selektorów dokumentu, globalny CSS, taki jak article { border: none }, zwykle nie dociera do tego drzewa shadow. Właściwości dziedziczone i niestandardowe właściwości CSS nadal mogą przekraczać tę granicę. Shadow DOM enkapsuluje prezentację; nie jest to piaskownica bezpieczeństwa.
Strażnik if (this.shadowRoot) zapobiega dołączeniu drugiego shadow roota, jeśli element połączy się ponownie.
5. Oddziel układ za pomocą szablonu HTML
Osadzanie wszystkiego wewnątrz connectedCallback() staje się niewygodne w miarę rozrastania się komponentu. Zdefiniujmy znaczniki raz, a następnie klonujmy je dla każdej karty.
Zastąp plik tym:
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 to fragment dokumentu. cloneNode(true) kopiuje całą strukturę do drzewa shadow każdej karty. Sam szablon nie renderuje się, dopóki go nie sklonujemy i nie wstawimy.
Ta wersja wygląda niemal identycznie. Ulepszenie ma charakter architektoniczny: jeden szablon może obsługiwać wiele instancji.
6. Wstaw różną treść za pomocą slotów
Karta wielokrotnego użytku nie jest użyteczna, jeśli każda instancja ma ten sam nagłówek. Zastąp wyłącznie deklarację szablonu na początku ui-card.js poniższym kodem; zachowaj klasę i kod rejestracji z Kroku 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>
`;
Teraz zastąp <ui-card></ui-card> w 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>
Oczekiwany wynik — Krok 6
Nazwany slot otrzymuje element oznaczony jako slot="title". Nienazwany slot otrzymuje akapit. Slot akcji otrzymuje łącze. Tekst zastępczy slotu pojawia się, jeśli nic nie zostanie do niego przypisane.
Układ znajduje się w komponencie; rzeczywiste słowa i łącza pozostają w HTML strony. Jest to szczególnie przydatne w przypadku treści CMS. Zastąp /tutorial prawdziwym miejscem docelowym w swoim projekcie.
7. Utwórz wariant wyróżniony za pomocą CSS
Wewnątrz bloku <style> szablonu dodaj:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Następnie zastąp pojedynczą kartę w index.html dwiema kartami:
<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>
Oczekiwany wynik — Krok 7
Jest to szczególnie przydatna funkcja :host(): stylizuje komponent na podstawie atrybutów custom elementu. Jeśli JavaScript zmieni później variant, CSS zaktualizuje się automatycznie. Do czysto opartej na CSS zmiany nie potrzeba attributeChangedCallback().
8. Dodaj przycisk odrzucania i publiczne zdarzenie
Sprawmy, by karta była interaktywna. Wewnątrz <article> szablonu dodaj ten przycisk przed nagłówkiem:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Dodaj te reguły do CSS szablonu:
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;
}
Zastąp connectedCallback() w klasie tym:
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();
});
}
W index.html dodaj ten skrypt przed </body>:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Otwórz konsolę przeglądarki i kliknij ×. Karta znika, a konsola wyświetla komunikat.
Zdarzenie zapewnia publiczny punkt integracji: otaczająca aplikacja nie musi nic wiedzieć o wewnętrznym przycisku karty. bubbles sprawia, że zdarzenie się propaguje (bubble); composed pozwala przekraczać granicę shadow tam, gdzie ma to zastosowanie. Tutaj zdarzenie pochodzi z samego elementu hosta.
9. Kompletna wersja końcowa: skopiuj i użyj
Możesz teraz zastąpić całą zawartość components/ui-card.js tą skonsolidowaną wersją. Dodaje ona dostosowywanie CSS i eksportowane części, zachowując jednocześnie zachowanie zbudowane w poprzednich krokach.
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);
}
W przeciwieństwie do szybkiego dema ta wersja nie próbuje dołączać shadow roota dwukrotnie, nie wstawia niezaufanej treści za pomocą innerHTML i nie opiera się na frameworku. Ciąg szablonu jest kontrolowany przez programistę; nigdy nie interpoluj niezaufanego wejścia użytkownika do tego ciągu.
10. Ostylizuj to z hostującej witryny
Shadow DOM nie ma na celu uniemożliwienia dostosowywania. Zachęca do zdefiniowania celowego interfejsu stylizacji.
W css/main.css dodaj:
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
Niestandardowe właściwości są dziedziczone przez drzewo shadow i kontrolują wartości, które wystawiliśmy. Atrybut part="container" pozwala zewnętrznemu CSS kierować na wybrany wewnętrzny element za pomocą ::part(container).
Jeśli potrzebujesz innego tła wyróżnionego, użyj --card-featured-background. Jest to preferowane zamiast zmuszania konsumentów do zależności od dokładnej wewnętrznej struktury DOM.
11. Użyj karty ponownie w WordPress, Joomla lub zwykłym HTML
Skopiuj ui-card.js do docelowej witryny i załaduj ją jako moduł JavaScript:
<script type="module" src="/assets/js/ui-card.js"></script>
Następnie użyj <ui-card> w znacznikach strony. W WordPress rejestruj zasoby za pomocą motywu lub obsługiwanych API ładowania skryptów wtyczki, używając obsługi modułów odpowiedniej dla Twojej wersji WordPress. W Joomla użyj Web Asset Managera do zarejestrowania i załadowania modułu. Nie rozsiewaj zakodowanych na sztywno tagów skryptów po produkcyjnych szablonach.
W przypadku karty generowanej przez CMS renderuj tytuł, akapit i łącze jako HTML w slotach. Escapuj treść i atrybuty zgodnie z regułami wyjściowymi CMS-a.
Praktyczna korzyść: moduł Joomla i blok WordPress mogą zarówno wyprowadzać ten sam custom tag, dzieląc jedną implementację komponentu. Każdy CMS pozostaje odpowiedzialny za pobieranie i escapowanie własnej treści.
12. Dostępność, SEO i progresywne ulepszanie
Używaj natywnych kontrolek HTML wewnątrz komponentów, gdy tylko jest to możliwe. Nasze działanie odrzucania używa prawdziwego button, który dostarcza semantykę aktywacji klawiaturą, oraz aria-label, ponieważ samo × nie jest opisowe.
Jeśli użytkownik odrzuci kartę za pomocą fokusu klawiaturowego, rozważ, gdzie powinien trafić fokus w bardziej złożonym interfejsie. Okna dialogowe, menu i pola kombi wymagają znacznie więcej zachowań dostępności niż ten przykład.
Tam gdzie to praktyczne, trzymaj ważną treść w znaczącym znacznikach light-DOM. Jeśli JavaScript zawiedzie, przeglądarka nie uaktualni <ui-card>; slotted nagłówek i akapit pozostaną w dokumencie, choć ostylowana powłoka komponentu i przycisk odrzucania nie będą istnieć.
W przypadku wyszukiwarek nie zakładaj, że treść oparta wyłącznie na JavaScripcie jest indeksowana identycznie w każdym crawlerze. Krytyczna treść powinna być dostępna w początkowym HTML lub poprzez odpowiednią strategię renderowania.
Shadow DOM ma również ograniczenia: zwykłe selektory CSS dokumentu nie stylizują wewnętrznych węzłów, a niektóre relacje ID ARIA nie mogą przekraczać granic shadow. Projektuj API komponentów, mając na uwadze te ograniczenia.
13. Czy Web Components są zawsze szybsze?
Niekoniecznie. Web Components pozwalają uniknąć wymogu konkretnego runtime'u frameworka, ale wydajność zależy od ilości JavaScriptu, złożoności DOM, częstotliwości renderowania i architektury aplikacji.
Mała karta to dobry kandydat. Setki złożonych elementów z niepotrzebnym przebudowywaniem DOM mogą nadal być wolne. Używaj szablonów ponownie, unikaj powtarzanego pełnego renderowania i mierz rzeczywistą wydajność.
W przypadku dużej aplikacji już zbudowanej wokół zarządzania stanem i routingu frameworka użycie własnych komponentów tego frameworka może być prostsze. Web Components błyszczą, gdy stabilny element UI musi przekraczać granice frameworków lub CMS-ów.
14. Rozwiązywanie problemów
| Objaw | Prawdopodobna przyczyna | Co sprawdzić |
|---|---|---|
| Karta jest pusta | Moduł się nie załadował | Konsola DevTools, URL, typ MIME serwera |
customElements.define rzuca wyjątek |
Nieprawidłowa lub zduplikowana nazwa | Wymóg myślnika i strażnik rejestracji |
| CSS nie stosuje się wewnątrz karty | Granica Shadow DOM | Użyj niestandardowych właściwości, :host lub ::part |
| Treść pojawia się w niewłaściwym miejscu | Niezgodność nazwy slotu | Porównaj slot="title" z <slot name="title"> |
| Kliknięcie odrzucania nic nie robi | Brak przycisku szablonu | Zbadaj drzewo shadow i konsolę |
| Komponent zawodzi po przeniesieniu | Inicjalizacja uruchamia się dwukrotnie | Strażnik tworzenia shadow roota |
| Łącze prowadzi do 404 | Przykładowy URL nie został zastąpiony | Użyj istniejącego miejsca docelowego |
Pamiętaj, że connectedCallback() może zostać uruchomiony więcej niż raz. Strażnik w naszym końcowym przykładzie sprawia, że inicjalizacja jest jednorazowa; bardziej wyrafinowane komponenty mogą potrzebować dołączać i usuwać zewnętrznych obserwatorów lub globalnych nasłuchiwaczy zdarzeń podczas swojego cyklu życia połączenia.
15. Kiedy powinieneś używać Web Components?
Wybierz je, gdy komponent potrzebuje interfejsu HTML wielokrotnego użytku, udokumentowanego, w kilku witrynach, frameworkach lub środowiskach CMS. Karty, powiadomienia, widgety produktowe i małe interaktywne narzędzia to dobre kandydaci.
Pomiń abstrakcję, gdy kilka linii zwykłego HTML i CSS już rozwiązuje problem. I nie odtwarzaj natywnych kontrolek bez silnego powodu.
Przydatny test: czy inna aplikacja skorzystałaby na użyciu tego elementu bez wiedzy o tym, jak został zaimplementowany? Jeśli tak, warto rozważyć Web Component.
Podsumowanie
Zbudowałeś prawdziwy komponent wielokrotnego użytku, a nie tylko przeczytałeś o API przeglądarki. Ma on custom tag, ostylowany zasięg, konfigurowalną treść, wariant wyróżniony oraz zdarzenie, którego może nasłuchiwać inny kod.
Zacznij od jednego komponentu, który wielokrotnie pojawia się w Twoich projektach. Nadaj mu mały publiczny API, przetestuj go w więcej niż jednym układzie i trzymaj jego zależności na minimum.
Długoterminowa wartość Web Components nie polega na tym, że zastępują każdy framework. Polega na tym, że pozwalają użytecznym elementom interfejsu przetrwać framework lub CMS, który jako pierwszy je gościł.