Web Components: Construiește componente UI reutilizabile cu JavaScript Vanilla
Învață Web Components pas cu pas construind un card UI reutilizabil cu Custom Elements, Shadow DOM, HTML Templates, slots și module JavaScript. Nu este necesar niciun framework sau instrument de build.
Componente Web: Construiește componente UI reutilizabile cu JavaScript Vanilla
Imaginează-ți că creezi un card pentru site-ul tău și apoi îl folosești într-o temă WordPress, o extensie Joomla sau o aplicație independentă fără să-l rescrii pentru fiecare mediu.
Aceasta este promisiunea Web Components: instrumente native ale browserului pentru construirea de elemente HTML reutilizabile. Nu sunt necesare React, Vue, pachete npm sau un bundler pentru exemplul pe care îl vom construi.
La finalul acestui tutorial, vei avea un component <ui-card> funcțional, cu conținut personalizabil, stiluri izolate, o variantă evidențiată, un buton de închidere și un eveniment public. Îl vom construi în pași mici, astfel încât să poți vedea ce contribuie fiecare tehnologie.
Ce vei construi
Componenta noastră finală va accepta acest 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>
Previzualizare vizuală — carduri standard și evidențiat
Această previzualizare este ținta de design, nu o captură de ecran a unei biblioteci fără legătură. O vom reproduce folosind codul de mai jos.
1. Înțelege cele patru elemente de bază
Custom Elements ne permit să înregistrăm o nouă etichetă HTML și comportamentul său JavaScript. Shadow DOM oferă elementului propriul DOM intern și stiluri cu scop delimitat. Șabloanele HTML și sloturile ne permit să reutilizăm structura în timp ce inserăm conținut diferit în fiecare instanță. Modulele ES ne permit să încărcăm componenta dintr-un fișier JavaScript obișnuit.
Acestea sunt caracteristici separate. Un Custom Element nu trebuie să folosească Shadow DOM și nu ai nevoie de un framework pentru a folosi oricare dintre ele.
2. Creează fișierele proiectului
Creează această structură în editorul tău:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Pune acest lucru în 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>
Adaugă stilurile la nivel de pagină în 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;
}
Rulează un server HTTP local din directorul proiectului, de exemplu:
python -m http.server 8000
Vizitează http://localhost:8000. Titlul apare, dar cardul nu are încă conținut vizibil. Folosește un server HTTP în loc să deschizi index.html cu file://: regulile de încărcare a modulelor din browser pot bloca importurile din fișiere locale.
3. Înregistrează primul tău Custom Element
Creează components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Reîmprospătează pagina. Acum ar trebui să vezi:
Rezultat așteptat — Pasul 3
HTMLElement oferă comportament DOM normal. connectedCallback() rulează atunci când elementul se conectează la document. customElements.define() asociază clasa cu eticheta HTML.
Liniuța din ui-card este necesară pentru numele de Custom Elements autonome. Callback-ul poate rula din nou dacă elementul este detașat și reinserat, ceea ce contează atunci când adăugăm logică de inițializare.
4. Oferă cardului propriul design cu Shadow DOM
Înlocuiește ui-card.js cu:
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);
Rezultat așteptat — Pasul 4
Deschide DevTools, inspectează <ui-card> și extinde #shadow-root (open). Vei vedea articolul intern și foaia de stil.
Spre deosebire de selectorii obișnuiți ai documentului, CSS global precum article { border: none } nu ajunge în mod normal la acest arbore shadow. Proprietățile moștenite și proprietățile CSS personalizate pot totuși traversa granița. Shadow DOM închide prezentarea; nu este un sandbox de securitate.
Gardă if (this.shadowRoot) împiedică atașarea unui al doilea root shadow dacă elementul se reconectează.
5. Separă aspectul cu un șablon HTML
Încorporarea a totul în interiorul connectedCallback() devine incomodă pe măsură ce componenta crește. Să definim marcarea o singură dată și să o clonăm pentru fiecare card.
Înlocuiește fișierul cu:
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 este un fragment de document. cloneNode(true) copiază întreaga structură în arborele shadow al fiecărui card. Șablonul în sine nu se randează până când nu îl clonăm și îl inserăm.
Această versiune arată aproape identic. Îmbunătățirea este arhitecturală: un singur șablon poate deservi multe instanțe.
6. Inserează conținut diferit folosind sloturi
Un card reutilizabil nu este util dacă fiecare instanță are același titlu. Înlocuiește doar declarația șablonului de la începutul ui-card.js cu următorul cod; păstrează clasa și codul de înregistrare din Pasul 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>
`;
Acum înlocuiește <ui-card></ui-card> din 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>
Rezultat așteptat — Pasul 6
Slotul denumit primește elementul marcat slot="title". Slotul fără nume primește paragraf. Slotul de acțiune primește linkul. Textul de rezervă al unui slot apare dacă nu îi este atribuit nimic.
Aspectul trăiește în componentă; cuvintele și linkurile reale rămân în HTML-ul paginii. Acest lucru este deosebit de util pentru conținutul CMS. Înlocuiește /tutorial cu o destinație reală în proiectul tău.
7. Creează o variantă evidențiată cu CSS
În interiorul blocului <style> al șablonului, adaugă:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Apoi înlocuiește cardul unic din index.html cu două carduri:
<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>
Rezultat așteptat — Pasul 7
Aceasta este o caracteristică deosebit de utilă a :host(): stilizează componenta pe baza atributelor elementului custom. Dacă JavaScript schimbă variant mai târziu, CSS se actualizează automat. Nu este necesar attributeChangedCallback() pentru o schimbare pur condusă de CSS.
8. Adaugă un buton de închidere și un eveniment public
Să facem cardul interactiv. În interiorul <article> al șablonului, adaugă acest buton înaintea titlului:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Adaugă aceste reguli la CSS-ul șablonului:
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;
}
Înlocuiește connectedCallback() din clasa cu:
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();
});
}
În index.html, adaugă acest script înainte de </body>:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Deschide consola browserului și dă click pe ×. Cardul dispare și consola afișează mesajul.
Evenimentul oferă un punct de integrare public: aplicația înconjurătoare nu trebuie să știe nimic despre butonul intern al cardului. bubbles face evenimentul să se propage în sus; composed permite traversarea unei granițe shadow acolo unde este cazul. Aici evenimentul se origazează chiar pe elementul gazdă.
9. Versiunea finală completă: copiază și utilizează
Acum poți înlocui întregul conținut al components/ui-card.js cu această versiune consolidată. Adaugă personalizare CSS și părți exportate, păstrând în același timp comportamentul construit în pașii anteriori.
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);
}
Spre deosebire de un demo rapid, această versiune nu încearcă să atașeze root-ul shadow de două ori, nu inserează conținut nesigur cu innerHTML și nu se bazează pe un framework. Șirul șablonului este controlat de dezvoltator; nu interpola niciodată intrare de utilizator nesigură în el.
10. Stilizează-l din site-ul care îl găzduiește
Shadow DOM nu are scopul de a face personalizarea imposibilă. Te încurajează să definești o interfață de stilizare intenționată.
În css/main.css, adaugă:
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
Proprietățile personalizate sunt moștenite de arborele shadow și controlează valorile pe care le-am expus. Atributul part="container" permite CSS extern să vizeze un element intern selectat cu ::part(container).
Dacă ai nevoie de un fundal evidențiat diferit, folosește --card-featured-background. Acest lucru este de preferat față de a forța consumatorii să depindă de structura DOM internă exactă.
11. Reutilizează cardul în WordPress, Joomla sau HTML simplu
Copiază ui-card.js în site-ul țintă și încarcă-l ca modul JavaScript:
<script type="module" src="/assets/js/ui-card.js"></script>
Apoi folosește <ui-card> în marcarea paginii. În WordPress, înregistrează resursele prin API-urile de încărcare a scripturilor acceptate de temă sau plugin, folosind suportul de module adecvat versiunii tale de WordPress. În Joomla, folosește Web Asset Manager pentru a înregistra și încărca modulul. Nu împrăștia etichete script codificate fix prin șabloanele de producție.
Pentru un card generat de CMS, randează titlul, paragraful și linkul ca HTML cu sloturi. Escapează conținutul și atributele conform regulilor de ieșire ale CMS-ului.
Beneficiu practic: un modul Joomla și un bloc WordPress pot ambele să emită aceeași etichetă custom în timp ce împart o singură implementare de componentă. Fiecare CMS rămâne responsabil pentru preluarea și escaparea propriului conținut.
12. Accesibilitate, SEO și îmbunătățire progresivă
Folosește controale HTML native în interiorul componentelor ori de câte ori este posibil. Acțiunea noastră de închidere folosește un button real, care oferă semantica de activare prin tastatură, și un aria-label deoarece × singur nu este descriptiv.
Dacă un utilizator închide un card cu focalizarea de tastatură, ia în considerare unde ar trebui să meargă focalizarea în continuare într-o interfață mai complexă. Dialogurile, meniurile și comboboxurile au nevoie de mult mai mult comportament de accesibilitate decât acest exemplu.
Păstrează conținutul important în marcare cu DOM-light semnificativ acolo unde este practic. Dacă JavaScript eșuează, browserul nu va face upgrade la <ui-card>; titlul și paragraful cu sloturi rămân în document, deși shell-ul stilizat al componentei și butonul de închidere nu vor exista.
Pentru motoarele de căutare, nu presupune că conținutul bazat doar pe JavaScript este indexat identic în fiecare crawler. Conținutul critic ar trebui să fie disponibil în HTML-ul inițial sau printr-o strategie de randare adecvată.
Shadow DOM are de asemenea limitări: selectorii CSS obișnuiți ai documentului nu stilizează nodurile interne, iar unele relații ARIA ID nu pot traversa granițele shadow. Proiectează API-urile componentelor având în vedere aceste constrângeri.
13. Sunt Web Components întotdeauna mai rapide?
Nu neapărat. Web Components evită cerința unui anumit runtime de framework, dar performanța depinde de cantitatea de JavaScript, complexitatea DOM, frecvența de randare și arhitectura aplicației.
Un card mic este un candidat bun. Sute de elemente complexe cu reconstrucții DOM inutile pot fi totuși lente. Reutilizează șabloanele, evită randarea completă repetată și măsoară performanța reală.
Pentru o aplicație mare deja construită în jurul gestionării stării și rutării unui framework, utilizarea propriilor componente ale acelui framework poate fi mai simplă. Web Components strălucesc atunci când un element UI stabil trebuie să traverseze granițele dintre framework-uri sau CMS-uri.
14. Depanare
| Simptom | Cauză probabilă | Ce să verifici |
|---|---|---|
| Cardul este gol | Modulul nu s-a încărcat | Consola DevTools, URL, tipul MIME al serverului |
customElements.define aruncă eroare |
Nume invalid sau duplicat | Cerința de liniuță și garda de înregistrare |
| CSS nu se aplică în interiorul cardului | Granița Shadow DOM | Folosește proprietăți personalizate, :host sau ::part |
| Conținutul apare în locul greșit | Nepotrivire nume slot | Compară slot="title" cu <slot name="title"> |
| Click pe închidere nu face nimic | Lipsește butonul din șablon | Inspectează arborele shadow și consola |
| Componenta eșuează când este mutată | Inițializarea rulează de două ori | Gărdește crearea root-ului shadow |
| Linkul duce la 404 | URL-ul exemplu nu a fost înlocuit | Folosește o destinație existentă |
Reține că connectedCallback() poate rula mai mult de o dată. Garda din exemplul nostru final păstrează inițializarea unice; componentele mai sofisticate ar putea avea nevoie să atașeze și să elimine observatori externi sau ascultători globali de evenimente în timpul ciclului lor de viață de conectare.
15. Când ar trebui să folosești Web Components?
Alege-le atunci când o componentă are nevoie de o interfață HTML reutilizabilă și documentată în mai multe site-uri web, framework-uri sau medii CMS. Cardurile, notificările, widgeturile de produs și instrumentele mici interactive sunt candidați buni.
Sari peste abstracțiune atunci când câteva linii de HTML și CSS obișnuite rezolvă deja problema. Și nu recrea controale native fără un motiv puternic.
Un test util: ar beneficia o altă aplicație de la utilizarea acestui element fără să știe cum a fost implementat? Dacă da, un Web Component merită luat în considerare.
Concluzie
Ai construit o componentă reală reutilizabilă, nu doar ai citit despre un API de browser. Are o etichetă custom, stilizare cu scop delimitat, conținut configurabil, o variantă evidențiată și un eveniment pe care alt cod îl poate asculta.
Începe cu o componentă care apare repetat în proiectele tale. Oferă-i un API public mic, testeaz-o în mai mult de un layout și păstrează-ți dependențele minime.
Valoarea pe termen lung a Web Components nu este aceea că înlocuiesc fiecare framework. Ci aceea că permit elementelor de interfață utile să supraviețuiască framework-ului sau CMS-ului care le-a găzduit inițial.