Web Components: Byg genbrugelige UI-komponenter med Vanilla JavaScript
Lær Web Components trin for trin ved at bygge et genbrugeligt UI-kort med Custom Elements, Shadow DOM, HTML Templates, slots og JavaScript-moduler. Ingen framework eller build-værktøjer er påkrævet.
Forestil dig at oprette et kort til dit website og derefter bruge det i et WordPress-tema, en Joomla-udvidelse eller et selvstændigt program, ohne at skrive om det for hver miljø.
Det er løftet fra Web Components: browser-native værtil til at bygge genbrugelige HTML-elementer. Ingen React, Vue, npm-pakker eller bundler er påkrævet for eksemplet, vi skal bygge.
Ved tutorialens afslutning vil du have et fungerende <ui-card>-komponent med tilpasseligt indhold, isolerede stiler, en fremhævet variant, en lukke-knap og en offentlig begivenhed. Vi bygger det i små trin, så du kan se, hvad hver teknologi bidrager med.
Det du vil bygge
Vores færdige komponent vil understøtte følgende 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>
Visuel forhåndsvisning — standard og fremhævede kort
Denne forhåndsvisning er designmålet, ikke et skærmbillede af et relateret bibliotek. Vi vil genskabe det ved hjælp af koden nedenfor.
1. Forstå de fire byggesten
Custom Elements giver os mulighed for at registrere en ny HTML-tag og dens JavaScript-adfærd. Shadow DOM giver elementet sit egne interne DOM og scoped stiler. HTML-skabeloner og slots muliggør genbrug af struktur, mens vi indsætter forskelligt indhold i hver instans. ES-Moduler lad os komponenten ind fra en almindelig JavaScript-fil.
Disse er separate funktioner. Et Custom Element behøver ikke at bruge Shadow DOM, og du behøver et framework for at bruge nogen af dem.
2. Oprojekt filerne
Opret denne struktur i din editor:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Sæt dette ind i 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>
Tilføj side-niveaustiler til 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;
}
Kør en lokal HTTP-server fra projektmappen, for eksempel:
python -m http.server 8000
Besøg http://localhost:8000. Overskriften vises, men kortet har ingen synligt indhold endnu. Brug en HTTP-server i stedet for at åbne index.html med file://: browserens regler for modul-indlæsning kan blokere lokale fil-imports.
3. Registrér dit første Custom Element
Opret components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Opdatér siderne. Du burde nu se:
Forventet result — Step 3
HTMLElement leverer normal DOM-adfærd. connectedCallback() kører, when elementet tilsluttes dokumentet. customElements.define() associerer klassen med HTML-taggen.
Bindestreglen i ui-card er påkrævet for autonome Custom Element-navne. Callbacken kan køre igen, hvis elementet bliver frakoblet og sat ind igen, hvilket er vigtigt, quando vi tilføjer initialiseringslogik.
4. Giv kortet sit egne design med Shadow DOM
Erstat ui-card.js med:
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);
Forventet result — Step 4
Åbn DevTools, insplicitér <ui-card>, og udvid #shadow-root (open). Du vil se den interne article og stylesheet.
I modsætning til almindelige dokumentselektorer, global CSS som article { border: none } rammer normalt ikke dette shadow-træ. Arvede egenskaber og CSS-brugerdefinerede egenskaber kan stadig krydse grænsen. Shadow DOM indkapsler præsentation; det er ikke en sikkerheds-sandbox.
if (this.shadowRoot)-beskyttelsen forhindrer, at der bliver tilføjet en anden shadow-root, hvis elementet tilsluttes igen.
5. Adskil layoutet med en HTML-skabelon
At indlede alt inden i connectedCallback() bliver akavet, when komponenten vokser. Lad os definere markup'en engens og klone den til hvert kort.
Erstat filen med:
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 er et dokument-fragment. cloneNode(true) kopiér hele strukturen ind i hvert korts shadow-træ. Skabelonen selv renderes ikke, inden vi kloner og indsætter den.
Denne version ser stort set identisk ud. Forbedringen er arkitektonisk: én skabelon kan betjene mange instanser.
6. Indsæt forskelligt indhold ved hjælp af slots
Et genbrugeligt kort er ikke nyttigt, hvis hver instans har samme overskrift. Erstat kun skabelon-erklæringen øverst i ui-card.js med følgende; behold klassen og registreringskoden fra Step 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>
`;
Nu erstat <ui-card></ui-card> i 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>
Forventet result — Step 6
Det navngivne slot modtager elementet mærket slot="title". Det unavngivne slot modtager paragraphen. Action-slottet modtager linket. Et slots fallback-tekst vises, hvis intet er tildelt det.
Layoutet leveres i komponenten; de faktiske ord og links forbliver i sidens HTML. Dette især nyttigt for CMS-indhold. Erstat /tutorial med et rigtigt destinations-sted i dit projekt.
7. Opret en fremhævet variant med CSS
Inden for skabelonens <style>-block, tilføj:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Så erstat det enkelt kort i index.html med to kort:
<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>
Forventet result — Step 7
Dette er en særligt nyttig funktion af :host(): det stiler komponenten baseret på attributter af det brugerdefinerede element. Hvis JavaScript senere ændrer variant, opdateres CSS automatisk. Ingen attributeChangedCallback() er påkrævet for en rent CSS-drevet ændring.
8. Tilføj en lukke-knap og en offentlig begivenhed
Lad os gøre kortet interaktivt. Inden for skabelonens <article>, tilføj denne knap før overskriften:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Tilføj disse regler til skabelonens 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;
}
Erstat connectedCallback() i klassen med:
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();
});
}
I index.html, tilføj dette script før </body>:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Åbn browserens console og click ×. Kortet forsvinder, og console viser meddelelsen.
Begivenheden giver et offentligt integrationspunkt: den omgivende applikation behøver ikke at vide noget om kortets interne knap. bubbles gør begivenheden bobler; composed tillader krydsning af en shadow-grænse, hvor det er relevant. Her oprindes begivenheden på selve host-elementet.
9. Afslut den endelige version: kopiér og brug
Du kan nu erstatte hele indholdet af components/ui-card.js med den konsoliderede version. Den tilføjer CSS-tilpasning og eksporterede dele, mens den beholder adfærden bygget i tidligere trin.
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);
}
I modsætning til en hurtig demo, forsøger denne version ikke at tilføje shadow-root to gange, indsætter ikke mistænkt indhold med innerHTML, og afhænger ikke af et framework. Strengen er udvikler-kontrolleret; interpolér aldrig mistænkt brugerinput i den.
10. Stil det fra hosting-webstedet
Shadow DOM er ikke tiltænkt at gøre tilpasning umuligt. Det opfordrer dig til at definere et intentionelt styling-interface.
I css/main.css, tilføj:
ui-card {
--card-border: #cbd5e1;
--card-title-color: #0f766e;
}
ui-card::part(container) {
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}
De brugerdefinerede egenskaber arves af shadow-træet og kontrollerer de værdier, vi udstillede. part="container"-attributten lader ekstern CSS målrette et valgt internt element med ::part(container).
Hvis du har brug for et andet fremhævet baggrund, brug --card-featured-background. Dette er foretrukket frem for at tvinge forbrugere til at afhænge af den præcise interne DOM-struktur.
11. Genbrug kortet i WordPress, Joomla eller almindelig HTML
Kopiér ui-card.js ind i mål-webstedet og indlæs det som et JavaScript-modul:
<script type="module" src="/assets/js/ui-card.js"></script>
Så brug <ui-card> i sidens markup. I WordPress, registrer assets gennem temaets eller pluginets understøttede script-indlæsning API'er, med modul-understøttelse approprieret til din WordPress-version. I Joomla, brug Web Asset Manager til at registrere og indlæse modulet. Spred ikke hardkodede script-tags i produktionstempler.
For et CMS-genereret kort, render titlen, paragraphen og linket som slatted HTML. Undslip indhold og attributter ifølge CMS' output-regler.
Praktisk fordel: et Joomla-modul og et WordPress-block kan begge outputte den samme brugerdefinerede tag, mens de deler en komponent-implementation. Hvert CMS forbliver ansvarligt for at hente og undslippe sit eget indhold.
12. Tilgængelighed, SEO og progressiv forbedring
Brug native HTML-kontroller inde i komponenter, hvad enten det er muligt. Vores lukke-handling bruger et rigtigt button, som leverer tastatur-aktiveringssemantik, og et aria-label fordi × alene ikke er beskrivende.
Hvis en bruger lukker et kort med tastatur-fokus, overvej, hvor fokus skal gå næste i et mere komplekst interface. Dialoger, menuer og comboboxes har brug for meget mere tilgængelighedsadfærd end dette eksempel.
Hold vigtigt indhold i meningsfuld light-DOM-markup, hvor det er muligt. Hvis JavaScript fejler, vil browseren ikke opgradere <ui-card>; de slatted overskrift og paragraph forbliver i dokumentet, selvom komponentens styled shell og lukke-knap ikke vil eksistere.
For søgemaskiner, antag ikke at kun-JavaScript-indhold indekseres identisk i every crawler. Kritisk indhold bør være tilgængeligt i den indledende HTML eller gennem en egnet renderingstrategi.
Shadow DOM har også begrænsninger: almindelige dokument-CSS-selektorer stiler ikke interne nogle, og nogle ARIA-ID-relationer kan ikke krydse shadow-grænser. Design komponent-API'er med disse begrænsninger i tanken.
13. Er Web Components altid hurtigere?
Ikke nødvendigvis. Web Components undgår at kræve et bestemt framework-runtime, men ydelse afhænger af mængden af JavaScript, DOM-kompleksitet, renderingsfrekvens og applikationsarkitektur.
Et kort er et god kandidat. Hundreder af komplekse elementer med unødvendig DOM-genopbygning kan stadig være langsomme. Genbrug skabeloner, undgå gentagen fuld rendering, og mål reel ydelse.
For en stor applikation allerede bygget omkring et frameworks state-management og routing, kan det være enklere at bruge det frameworks egne komponenter. Web Components skiner, when et stabilt UI-element skal krydse framework- eller CMS-grænser.
14. Fejlfinding
| Symptom | Likely cause | What to check |
|---|---|---|
| Kortet er tomt | Modulen indlæste ikke | DevTools-console, URL, server MIME-type |
customElements.define kaster |
Ugyldigt eller duplikat navn | Bindestregel-krav og registrerings-beskyttelse |
| CSS anvendes ikke inde i kortet | Shadow DOM-grænse | Brug brugerdefinerede egenskaber, :host, eller ::part |
| Indhold vises på forkert sted | Slot-navn mismatch | Sammenlign slot="title" med <slot name="title"> |
| Klik på lukke gør intet | Skabelon-knap mangler | Inspekter shadow-træ og console |
| Komponent fejler, when flyttet | Initialisering kører to gange | Beskyttelse af shadow-root oprettelse |
| Link fører til 404 | Eksempel-URL blev ikke erstat | Brug en eksisterende destination |
Husk at connectedCallback() kan køre mere end én gang. Beskyttelsen i vores endelige eksempel holder initialiseringen én gang; mere avancerede komponenter måske skal tilføje og fjerne eksterne observatører eller globale event-listeners i deres forbindelseslivscyklus.
15. Når skal du bruge Web Components?
Vælg dem, when en komponent har brug for et genbrugeligt, dokumenteret HTML-interface på tværs af flere websites, frameworks eller CMS-miljøer. Kort, notifikationer, produkt-widgets og små interaktive værktøjer er good kandidater.
Spring abstraktionen over, få linjer af almindelig HTML og CSS allerede løser problemet. Og genopret ikke native controls without en stærk årsag.
En nyttig test: ville en anden applikate have fordel af at bruge dette element, selvom den ikke ved, how det er implementeret? Hvis ja, et Web Component er værd at overveje.
Konklusion
Du har bygget et virkeligt genbrugeligt komponent, ikke bare läst om en browser-API. Det har en brugerdefineret tag, scoped styling, konfigurerbart indhold, en fremhævet variant, og en begivenhed, som anden code kan lytte til.
Start med én komponent, der gentagne gange vises i dine projekt. Giv den et små offentligt API, test den i mere end ét layout, og hold dens afhængigheder minimale.
Den langtidsværdi af Web Components er ikke, at de erstatter hvert framework. Det er, at de lader nyttige interface-elementer overleve det framework eller CMS, der først hostede dem.