Web Components: Vytvořte opakovatelně použitelné UI komponenty pomocí Vanilla JavaScript
Naučte se Web Components krok za krokem vytvářením opakovatelně použitelné UI karty s Custom Elements, Shadow DOM, HTML Templates, slots a JavaScript moduly. Žádný framework ani nástroje pro build nejsou potřeba.
Web Components: Vytvořte opakovaně použitelné komponenty uživatelského rozhraní pomocí čistého JavaScriptu
Představte si, že vytvoříte kartu pro svůj web a poté ji budete moci použít v šabloně WordPressu, rozšíření Joomla nebo samostatné aplikaci bez nutnosti ji pro každé prostředí znovu přepisovat.
Přesně to slibují Web Components: nativní nástroje prohlížeče pro vytváření opakovaně použitelných HTML prvků. Pro náš příklad nebudeme potřebovat React, Vue, balíčky npm ani bundler.
Na konci tohoto tutoriálu budete mít funkční komponentu s názvem <ui-card>, která bude mít přizpůsobitelný obsah, izolované styly, variantu s prominentním postavením, tlačítko pro zavření a veřejnou událost. Budeme ji vytvářet ve malých krocích, abyste mohli vidět, jak každý prvek přispívá k výsledku.
Co vytvoříte
Naše dokončená komponenta bude podporovat následující HTML kód:
<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>
Vizualizace – standardní a prominentní karty
Tato vizualizace představuje cílový design, nikoliv screenshot nesouvisející knihovny. Budeme ji reprodukovat pomocí níže uvedeného kódu.
1. Porozumění čtyřm stavebním kamenům
Vlastní prvky nám umožňují zaregistrovat nový HTML tag a jeho JavaScriptové chování. Shadow DOM dodává prvku vlastní vnitřní DOM a izolované styly. HTML šablony a sloty nám umožňují znovu použít strukturu a zároveň vložit do každého výskytu různý obsah. ES Moduly nám umožňují načíst komponentu z běžného JavaScriptového souboru.
Jedná se o samostatné funkce. Vlastní prvek nemusí používat Shadow DOM a k použití kterékoli z nich nepotřebujete žádný framework.
2. Vytvořte soubory projektu
Vytvořte v editoru následující strukturu:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Do souboru index.html vložte následující:
<!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>
Přidejte styly na úrovni stránky do souboru 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;
}
Spusťte lokální HTTP server z adresáře projektu, například:
python -m http.server 8000
Otevřete http://localhost:8000 v prohlížeči. Zobrazí se nadpis, ale karta ještě nemá viditelný obsah. Použijte HTTP server místo otevírání index.html pomocí file://: pravidla načítání modulů v prohlížeči mohou blokovat lokální importy.
3. Zaregistrujte svůj první vlastní prvek
Vytvořte soubor components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Obnovte stránku. Nyní byste měli vidět:
Očekávaný výsledek – krok 3
HTMLElement poskytuje běžné DOM chování. connectedCallback() se spouští, když se prvek připojí k dokumentu. customElements.define() spojuje třídu s HTML tagem.
Pomocí ui-card se pro názvy autonomních vlastních prvků vyžaduje pomlčka. Callback se může spustit znovu, pokud je prvek odpojen a znovu vložen, což je důležité, když přidáváme inicializační logiku.
4. Dodajte kartě vlastní design pomocí Shadow DOM
Nahradte soubor ui-card.js následujícím kódem:
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);
Očekávaný výsledek – krok 4
Otevřete DevTools, zkontrolujte <ui-card> a rozbalte #shadow-root (open). Uvidíte vnitřní článek a stylesheet.
Na rozdíl od běžných selektorů dokumentu se globální CSS jako article { border: none } obvykle nedostanou do tohoto stínového stromu. Děděné vlastnosti a CSS vlastní vlastnosti mohou i nadále překračovat tuto hranici. Shadow DOM izoluje prezentaci; nejedná se o bezpečnostní sandbox.
Pomocí if (this.shadowRoot) se zabrání připojení druhého stínového kořenového prvku, pokud se prvek znovu připojí.
5. Oddělte rozložení pomocí HTML šablony
Vložení všeho uvnitř connectedCallback() se stává nepohodlným, jak komponenta roste. Definujme markup jednou a klonujme jej pro každou kartu.
Nahradte soubor následujícím kódem:
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 je dokumentový fragment. cloneNode(true) kopíruje celou strukturu do stínového stromu každé karty. Šablona samotná se nezobrazí, dokud ji nezkopírujeme a nevložíme.
Tato verze vypadá téměř identicky. Zlepšení je architektonické: jedna šablona může sloužit mnoha výskyt месту.
6. Vložte různý obsah pomocí slotů
Opakovaně použitelná karta není užitečná, pokud každý výskyt má stejný nadpis. Nahraďte pouze deklaraci šablony na začátku ui-card.js následujícím kódem; ponechte třídu a registrační kód 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>
`;
Nyní nahraďte <ui-card></ui-card> v index.html následujícím kódem:
<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>
Očekávaný výsledek – krok 6
Pojmenovaný slot přijímá prvek označený slot="title". Nejmový slot přijímá odstavec. Akční slot přijímá odkaz. Pokud není k slotu přiřazeno nic, zobrazí se jeho textová výplň.
Rozložení žije v komponentě; skutečná slova a odkazy zůstávají v HTML stránky. To je obzvláště užitečné pro obsah CMS. Nahraďte /tutorial skutečnou cílovou adresou ve svém projektu.
7. Vytvořte variantu s prominentním postavením pomocí CSS
Uvnitř šablonového bloku <style> přidejte následující kód:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Poté nahraďte jedinou kartu v index.html dvěma 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>
Očekávaný výsledek – krok 7
Toto je obzvláště užitečná funkce :host(): styluje komponentu na základě atributů vlastního prvku. Pokud JavaScript později změní variant, CSS se automaticky aktualizuje. Není potřeba attributeChangedCallback() pro čistě CSS-driven změnu.
8. Přidejte tlačítko pro zavření a veřejnou událost
Udělejme kartu interaktivní. Uvnitř šablonového bloku <article> přidejte toto tlačítko před nadpisem:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Přidejte tato pravidla do šablonového 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;
}
Nahraďte connectedCallback() v třídě následujícím kódem:
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();
});
}
V index.html přidejte tento skript před </body>:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Otevřete konzolu prohlížeče a klikněte na ×. Karta zmizí a v konzole se zobrazí zpráva.
Událost poskytuje veřejný integrační bod: okolová aplikace nemusí nic vědět o vnitřním tlačítku karty. bubbles zajišťuje, že událost bubluje; composed umožňuje překročení stínové hranice, pokud je to vhodné. Zde událost pochází ze samotného hostitelského prvku.
9. Dokončete konečnou verzi: zkopírujte a použijte
Nyní můžete nahradit celý obsah components/ui-card.js tímto konsolidovaným verzí. Přidává CSS přizpůsobení a exportované části, zároveň zachovává chování vytvořené v předchozích krocích.
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);
}
Na rozdíl od rychlé demonstrace tato verze nezkouší připojit stínový kořen dvakrát, nevkládá nedůvěryhodný obsah pomocí innerHTML a nespoléhá na framework. Šablonový řetězec je řízen vývojářem; nikdy neinterpolujte nedůvěryhodný uživatelský vstup do něj.
10. Stylujte to z hostitelského webu
Shadow DOM není určen k tomu, aby znemožňoval přizpůsobení. Povzbuzuje vás k definování záměrného stylingového rozhraní.
Do css/main.css přidejte následující kód:
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
Vlastní vlastnosti jsou děděny stínovým stromem a řídí hodnoty, které jsme odhalili. Atribut part="container" umožňuje externímu CSS cílit na vybraný vnitřní prvek s ::part(container).
Pokud potřebujete jinou prominentní pozadí, použijte --card-featured-background. To je preferovanější než nutit spotřebitele záviset na přesné vnitřní struktuře DOM.
11. Opakovaně použijte kartu ve WordPressu, Joomle nebo plain HTML
Zkopírujte ui-card.js do cílové webové stránky a načtěte ji jako JavaScriptový modul:
<script type="module" src="/assets/js/ui-card.js"></script>
Poté použijte <ui-card> v markupu stránky. Ve WordPressu zaregistrujte aktiva prostřednictvím šablony nebo pluginu pomocí podporovaných API načítání skriptů, s využitím podpory modulů vhodné pro vaši verzi WordPressu. V Joomle použijte Web Asset Manager k registraci a načtení modulu. Nepoužívejte rozházené hardcodeované skriptové tagy v produkčních šablonách.
Pro CMS generovanou kartu vykreslete nadpis, odstavec a odkaz jako vložený HTML obsah. Escapeujte obsah a atributy podle pravidel výstupu CMS.
Praktický přínos: Joomla modul a WordPress blok mohou oba výstupovat stejný vlastní tag, zatímco sdílejí jednu implementaci komponenty. Každý CMS zůstává zodpovědný za načítání a escapeování svého vlastního obsahu.
12. Přístupnost, SEO a progresivní vylepšení
Používejte nativní HTML kontroly uvnitř komponent, kdykoli je to možné. Naše akce zavření používá skutečný button, který poskytuje sémantiku aktivace pomocí klávesnice, a aria-label, protože × samo o sobě není popisné.
Pokud uživatel zavře kartu s klávesnicovým fokusem, zvažte, kam by se měl fokus přesunout dále v komplexnějším rozhraní. Dialogy, menu a comboboxy potřebují mnohem více přístupnostního chování než tento příklad.
Udržujte důležitý obsah v smysluplném light-DOM markupu, kde je to praktické. Pokud JavaScript selže, prohlížeč neupgraduje <ui-card>; vložený nadpis a odstavec zůstanou v dokumentu, i když komponentovo stylizované schránkové řešení a tlačítko pro zavření nebudou existovat.
Pro vyhledávače nepředpokládejte, že obsah pouze z JavaScriptu je indexován identicky všemi prohledávači. Kritický obsah by měl být dostupný v počátečním HTML nebo prostřednictvím vhodné strategie vykreslování.
Shadow DOM má také omezení: běžné CSS selektory dokumentu nestylují vnitřní uzly a některé ARIA ID vztahy nemohou překročit stínové hranice. Navrhujte komponentové API s těmito omezeními na paměti.
13. Jsou Web Components vždy rychlejší?
Ne nutně. Web Components se vyhýbají nutnosti konkrétního frameworkového runtime, ale výkon závisí na množství JavaScriptu, složitosti DOM, frekvenci renderování a architektuře aplikace.
Malá karta je dobrým kandidátem. Stovky složitých prvků s zbytečným opětovným sestavením DOM mohou být stále pomalé. Opakovaně používejte šablony, vyhněte se opakovanému plnému renderování a měřte skutečný výkon.
Pro rozsáhlou aplikaci již postavenou na frameworkovém řízení stavu a routingu může být jednodušší použít frameworkové komponenty samotného frameworku. Web Components září, když stabilní UI prvek potřebuje překročit hranice frameworku nebo CMS.
14. Řešení problémů
| Příznak | Pravděpodobná příčina | Co zkontrolovat |
|---|---|---|
| Karta je prázdná | Modul se nenačetl | Konzola DevTools, URL, server MIME type |
customElements.define vyhodí chybu |
Neplatný nebo duplicitní název | Požadavek na pomlčku a registrační guard |
| CSS se uvnitř karty neuplatňuje | Hraniční zóna Shadow DOM | Použijte vlastní vlastnosti, :host nebo ::part |
| Obsah se objeví na nesprávném místě | Neshoda názvu slotu | Porovnejte slot="title" s <slot name="title"> |
| Kliknutí na tlačítko pro zavření nic neudělá | Chybí tlačítko v šabloně | Zkontrolujte stínový strom a konzoli |
| Komponenta selže při přesunu | Inicializace se spustí dvakrát | Guard vytvoření stínového kořene |
| Odkaz vede k 404 | Příklad URL nebyl nahrazen | Použijte existující cílovou adresu |
Pamatujte, že connectedCallback() se může spustit více než jednou. Guard v našem konečném příkladu udržuje inicializaci jednorázovou; složitější komponenty mohou potřebovat připojit a odstranit externí pozorovatele nebo globální událostní posluchače během životního cyklu připojení.
15. Kdy byste měli použít Web Components?
Vyberte je, když komponent potřebuje opakovaně použitelný, zdokumentovaný HTML interface napříč několika webovými stránkami, frameworky nebo CMS prostředími. Karty, oznámení, produktové widgety a malé interaktivní nástroje jsou dobrými kandidáty.
Přeskočíte abstrakci, když několik řádů běžného HTML a CSS již problém vyřeší. A nepřekonávejte nativní kontroly bez silného důvodu.
Užný test: měl by mít další aplikace prospěch z použití tohoto prvku bez znalosti toho, jak byl implementován? Pokud ano, Web Component stojí za zvážení.
Závěr
Vytvořili jste reálnou opakovaně použitelnou komponentu, ne jen četli o prohlížečovém API. Má vlastní tag, izolované styly, přizpůsobitelný obsah, variantu s prominentním postavením a událost, na kterou se může další kód připojit.
Začněte s jednou komponentou, která se opakuje ve vašich projektech. Dejte jí malý veřejný API, otestujte ji ve více než jednom rozložení a udržujte její závislosti minimální.
Dlouhodobá hodnota Web Components nespočívá v tom, že nahradí každý framework. Spočívá v tom, že umožní užitečným rozhraním prvků přežít framework nebo CMS, který je původně hostil.