Web Components: Rakenna uudelleenkäytettäviä UI‑komponentteja Vanilla JavaScriptilla
Opettele Web Components -vaiheittain rakentamalla uudelleenkäytettävää UI‑korttia Custom Elements-, Shadow DOM-, HTML Templates-, slots- ja JavaScript modules -käyttöä käyttäen. Ei vaadi kehyttä tai build‑työkaluja.
Web-komponentit: rakenna uudelleenkäytettäviä käyttöliittymäkomponentteja puhtaalla JavaScriptilla
Kuvittele, että luot kortin verkkosivustollesi ja käytät sitä sitten WordPress-teemassa, Joomla-laajennuksessa tai itsenäisessä sovelluksessa kirjoittamatta sitä uudelleen jokaista ympäristöä varten.
Tämä on Web-komponenttien lupaus: selaimen natiiviot työkalut uudelleenkäytettävien HTML-elementtien rakentamiseen. Esimerkissä, jonka rakennamme, ei tarvita Reactia, Vuea, npm-paketteja eikä bundleriä.
Tämän opetusohjelman lopussa sinulla on toimiva <ui-card>-komponentti, jossa on mukautettava sisältö, eristetyt tyylit, featured-variantti, dismiss-painike ja julkinen tapahtuma. Rakennamme sen pieninä vaiheina, jotta näet, mitä kukin teknologia tuo tähän mukaan.
Mitä rakennat
Valmis komponenttisi tukee seuraavaa 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>
Visuaalinen esikatselu — standardi- ja featured-kortit
Tämä esikatselu on suunnittelun tavoite, ei kuvakaappaus jostakin epäolennaisesta kirjastosta. Reproduoimme sen alla olevalla koodilla.
1. Ymmärrä neljä peruspalikkaa
Custom Elements antaa meille mahdollisuuden rekisteröidä uuden HTML-tagin ja sen JavaScript-käyttäytymisen. Shadow DOM antaa elementille oman sisäisen DOMinsa ja rajatut tyylinsä. HTML templates ja slots antavat meille mahdollisuuden käyttää rakennetta uudelleen samalla kun lisäämme eri sisältöä jokaiseen ilmentymään. ES Modules antaa meille mahdollisuuden ladata komponentti tavallisesta JavaScript-tiedostosta.
Nämä ovat erillisiä ominaisuuksia. Custom Element ei tarvitse käyttää Shadow DOMia, etkä tarvitse kehystä voidaksesi käyttää mitään näistä.
2. Luo projektitiedostot
Luo tämä rakenne editorissasi:
web-components-demo/
├── index.html
├── components/
│ └── ui-card.js
└── css/
└── main.css
Laita tämä index.html-tiedostoon:
<!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>
Lisää sivun tason tyylit css/main.css-tiedostoon:
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äynnistä paikallinen HTTP-palvelin projektikansiosta, esimerkiksi:
python -m http.server 8000
Käy osoitteessa http://localhost:8000. Otsikko ilmestyy, mutta kortilla ei ole vielä näkyvää sisältöä. Käytä HTTP-palvelinta sen sijaan, että avaisit index.html-sivuston file://:lla: selaimen moduulien lataussäännöt voivat estää paikallisten tiedostojen tuonnin.
3. Rekisteröi ensimmäinen Custom Element
Luo components/ui-card.js:
class UiCard extends HTMLElement {
connectedCallback() {
this.textContent = 'Hello from a Web Component!';
}
}
customElements.define('ui-card', UiCard);
Päivitä sivu. Sinun pitäisi nyt nähdä:
Odotettu tulos — Vaihe 3
HTMLElement tarjoaa normaalin DOM-käyttäytymisen. connectedCallback() suoritetaan, kun elementti yhdistetään dokumenttiin. customElements.define() yhdistää luokan HTML-tagiin.
ui-card-kohtaan tuleva yhdysmerkki vaaditaan autonomisten Custom Element -nimien kohdalla. Palautusfunktio voi suorittua uudelleen, jos elementti irrotetaan ja liitetään takaisin, mikä merkitsee, kun lisäämme alustuslogiikkaa.
4. Anna kortille oma suunnittelu Shadow DOMilla
Korvaa ui-card.js seuraavalla:
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);
Odotettu tulos — Vaihe 4
Avaa DevTools, tarkastele <ui-card> ja laajenna #shadow-root (open). Näet sisäisen article-elementin ja tyylitiedoston.
Toisin kuin tavallisilla dokumentin valitsimilla, globaali CSS, kuten article { border: none }, ei yleensä yllä tähän shadow-puuhun. Periytyvät ominaisuudet ja CSS custom properties voivat silti ylittää rajan. Shadow DOM kapseloi esityksen; se ei ole tietoturva-hiekkalaatikko.
if (this.shadowRoot)-suoja estää toisen shadow rootin liittämisen, jos elementti yhdistetään uudelleen.
5. Eristä asettelu HTML-templatella
Kaiken upottaminen connectedCallback()-luokan sisään muuttuu kankeaksi komponentin kasvaessa. Määritellään merkintä kerran ja kloonataan se jokaista korttia varten.
Korvaa tiedosto seuraavalla:
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 on dokumentin fragmentti. cloneNode(true) kopioi koko rakenteen jokaiseen kortin shadow-puuhun. Template itse ei renderöidy, ennen kuin kloonaamme ja lisäämme sen.
Tämä versio näyttää lähes identtiseltä. Parannus on arkkitehtoninen: yksi template voi palvella monta ilmentymää.
6. Lisää eri sisältöä käyttäen slotsia
Uudelleenkäytettävä kortti ei ole hyödyllinen, jos jokaisella ilmentymällä on sama otsikko. Korvaa vain template-määrittely ui-card.js-tiedoston alussa seuraavalla; säilytä luokka ja rekisteröintikoodi Vaiheesta 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>
`;
Korvaa nyt <ui-card></ui-card> index.html-tiedostossa:
<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>
Odotettu tulos — Vaihe 6
Nimetty slot vastaanottaa elementin, joka on merkitty slot="title". Nimetön slot vastaanottaa kappaleen. Toiminto-slot vastaanottaa linkin. Slotin fallback-teksti ilmestyy, jos sille ei ole määritetty mitään.
Asettelu elää komponentissa; varsinaiset sanat ja linkit pysyvät sivun HTML:ssä. Tämä on erityisen hyödyllistä CMS-sisällölle. Korvaa /tutorial oikealla kohteella projektissasi.
7. Luo featured-variantti CSS:llä
Lisää templaten <style>-lohkon sisälle:
:host {
display: block;
}
:host([variant="featured"]) article {
background: #eff6ff;
border-color: #93c5fd;
}
Korvaa sitten index.html-tiedostossa yksittäinen kortti kahdella kortilla:
<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>
Odotettu tulos — Vaihe 7
Tämä on erityisen hyödyllinen :host()-ominaisuus: se tyylittelee komponentin custom elementin attribuuttien perusteella. Jos JavaScript muuttaa variant myöhemmin, CSS päivittyy automaattisesti. attributeChangedCallback() ei tarvita puhtaasti CSS-pohjaiseen muutokseen.
8. Lisää dismiss-painike ja julkinen tapahtuma
Tehdään kortista interaktiivinen. Lisää tämä painike ennen otsikkoa templaten <article>-luokan sisälle:
<button class="dismiss" type="button" aria-label="Dismiss card">
×
</button>
Lisää nämä säännöt templaten CSS:ään:
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;
}
Korvaa connectedCallback() luokassa seuraavalla:
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();
});
}
Lisää index.html-tiedostoon tämä skripti ennen </body>-sulkua:
<script type="module">
document.addEventListener('card-dismissed', () => {
console.log('A card was dismissed.');
});
</script>
Avaa selaimen konsoli ja napsauta ×. Kortti katoaa ja konsoli näyttää viestin.
Tapahtuma tarjoaa julkisen integraatiopisteen: ympäröivä sovellus ei tarvitse tietää mitään kortin sisäisestä painikkeesta. bubbles tekee tapahtumasta bubble-tyyppisen; composed sallii shadow-rajan ylittämisen, jos se on sovellettavissa. Tässä tapahtuma syntyy itse host-elementillä.
9. Valmis lopullinen versio: kopioi ja käytä
Voit nyt korvata components/ui-card.js-tiedoston koko sisällön tällä yhdistetyllä versiolla. Se lisää CSS-mukauttamisen ja vietävät osat samalla kun se säilyttää aiemmissa vaiheissa rakennetun käyttäytymisen.
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);
}
Toisin kuin nopea demo, tämä versio ei yritä liittää shadow rootia kahdesti, ei lisää ei-luotettua sisältöä innerHTML-toiminnolla eikä nojaa kehykseen. Template-merkkijono on kehittäjän hallinnassa; älä koskaan interpoloi ei-luotettua käyttäjän syötettä siihen.
10. Tyylittele se isännöivästä verkkosivustosta
Shadow DOMia ei ole tarkoitettu tekemään mukauttamista mahdottomaksi. Se kannustaa sinua määrittelemään tarkoituksellisen tyylittelyrajapinnan.
Lisää css/main.css-tiedostoon:
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 periytyvät shadow-puuhun ja ohjaavat niitä arvoja, jotka paljastimme. part="container"-attribuutti antaa ulkoisen CSS:n kohdistaa valitun sisäisen elementin ::part(container):n avulla.
Jos tarvitset eri featured-taustan, käytä --card-featured-background. Tämä on parempi kuin kuluttajien pakottaminen riippumaan täsmälleen sisäisestä DOM-rakenteesta.
11. Käytä korttia uudelleen WordPressissä, Joomlassa tai puhtaassa HTML:ssä
Kopioi ui-card.js kohdeverkkosivustoon ja lataa se JavaScript-moduulina:
<script type="module" src="/assets/js/ui-card.js"></script>
Käytä sitten <ui-card> sivun merkinnässä. WordPressissä rekisteröi assets teeman tai laajennuksen tuettujen skriptin lataus-API:en kautta, käyttäen WordPress-versiosi mukaista moduulitukea. Joomlassa käytä Web Asset Manageria moduulin rekisteröintiin ja lataamiseen. Älä hajauta kovia koodattuja skriptitagneja tuotantotemplaateissa.
CMS:n generoitua korttia varten, renderöi otsikko, kappale ja linkki slottedattuna HTML:nä. Suodata sisältö ja attribuutit CMS:n tulostussääntöjen mukaisesti.
Käytännön hyöty: sekä Joomla-moduuli että WordPress-lohko voivat tuottaa saman custom tagin samalla kun jakavat yhden komponenttitoteutuksen. Kukin CMS vastaa edelleen oman sisältönsä noutamisesta ja suodattamisesta.
12. Saavutettavuus, SEO ja progressiivinen parantaminen
Käytä natiiveja HTML-säätimiä komponenttien sisällä aina kun mahdollista. Dismiss-toimintomme käyttää oikeaa button-painiketta, joka tarjoaa näppäimistöaktivaation semantiikan, ja aria-label, koska × yksinään ei ole kuvaava.
Jos käyttäjä dismissaa kortin näppäimistöfokuksella, harkitse, mihin fokus siirtyy seuraavaksi monimutkaisemmassa käyttöliittymässä. Dialogeilla, valikoilla ja comboboxeilla tarvitaan paljon enemmän saavutettavuuskäyttäytymistä kuin tässä esimerkissä.
Pidä tärkeä sisältö merkityksellisessä light-DOM-merkinnässä, kun käytännöllistä. Jos JavaScript epäonnistuu, selain ei päivitä <ui-card>-elementtiä; slottedattu otsikko ja kappale pysyvät dokumentissa, vaikka komponentin tyylitelty kuori ja dismiss-painike eivät synnykään.
Hakukoneille, älä oleteta, että JavaScriptillä tuotettua sisältöä indeksoidaan identtisesti jokaisessa crawlerissa. Kriittisen sisällön tulisi olla saatavilla alussa olevassa HTML:ssä tai sopivan renderöintistrategian kautta.
Shadow DOMilla on myös rajoituksia: tavalliset dokumentin CSS-valitsimet eivät tyylittele sisäisiä solmuja, ja jotkin ARIA ID -yhteydet eivät voi ylittää shadow-rajoja. Suunnittele komponenttien API:t näiden rajoitusten mielessä.
13. Ovatko Web-komponentit aina nopeampia?
Ei välttämättä. Web-komponentit välttävät tietyn framework runtime -ympäristön vaatimisen, mutta suorituskyky riippuu JavaScriptin määrästä, DOMin monimutkaisuudesta, renderöintitaajuudesta ja sovelluksen arkkitehtuurista.
Pieni kortti on hyvä ehdokas. Sadoilla monimutkaisilla elementeillä, joissa on tarpeetonta DOM-uudelleenrakentamista, suorituskyky voi silti olla hidas. Käytä templateja uudelleen, vältä toistuvaa koko renderöintiä ja mittaa todellista suorituskykyä.
Suurelle sovellukselle, joka on jo rakennettu frameworkin tilanhallinnan ja reitityksen ympärille, kyseisen frameworkin omien komponenttien käyttö voi olla yksinkertaisempaa. Web-komponentit loistavat, kun vakaa UI-elementti tarvitsee ylittää frameworkin tai CMS:n rajat.
14. Ongelmien vianetsintä
| Oire | Todennäköinen syy | Mitä tarkistaa |
|---|---|---|
| Kortti on tyhjä | Moduuli ei latautunut | DevTools-konsoli, URL, palvelimen MIME-tyyppi |
customElements.define heittää virheen |
Virheellinen tai duplikaatti nimi | Yhdysmerkkivaatimus ja rekisteröintisuoja |
| CSS ei sovellu kortin sisällä | Shadow DOM -raja | Käytä custom propertiesia, :host tai ::part |
| Sisältö ilmestyy väärään paikkaan | Slotin nimen epätäsmäävyys | Vertaile slot="title" ja <slot name="title"> |
| Dismissin napsauttaminen ei tee mitään | Templaten painike puuttuu | Tarkastele shadow-puuta ja konsolia |
| Komponentti epäonnistuu siirrettäessä | Alustus suoritetaan kahdesti | Suojaa shadow rootin luonti |
| Linkki johtaa 404:een | Esimerkkiosoitetta ei korvattu | Käytä olemassa olevaa kohdetta |
Muista, että connectedCallback() voi suorittua useammin kuin kerran. Suojamme lopullisessa esimerkissä pitää alustuksen kertaluontoisena; monimutkaisemmat komponentit saattavat joutua liittämään ja poistamaan ulkoisia tarkkailijoita tai globaaleja tapahtumakuuntelijoita liittymisjakskunsa aikana.
15. Milloin kannattaa käyttää Web-komponentteja?
Valitse ne, kun komponentti tarvitsee uudelleenkäytettävän, dokumentoidun HTML-rajapinnan useilla verkkosivuilla, frameworkeissa tai CMS-ympäristöissä. Kortit, ilmoitukset, tuote-widgetit ja pienet interaktiiviset työkalut ovat hyviä ehdokkaita.
Ohita abstraktio, kun muutama rivi tavallista HTML:ää ja CSS:ää ratkaisee ongelman jo. Äläkä luo natiiveja säätimiä uudelleen ilman vahvaa syytä.
Hyödyllinen testi: hyötyisikö toinen sovellus tämän elementin käytöstä tietämättä, miten se toteutettiin? Jos kyllä, Web-komponentti on harkinnan arvoinen.
Johtopäätös
Olet rakentanut todellisen uudelleenkäytettävän komponentin, etkä vain lukenut selaimen API:sta. Sillä on custom tag, rajatut tyylit, mukautettava sisältö, featured-variantti ja tapahtuma, jota muu koodi voi kuunnella.
Aloita yhdellä komponentilla, joka ilmestyy toistuvasti projekteissasi. Anna sille pieni julkinen API, testaa sitä useammassa kuin yhdessä asettelussa ja pidä sen riippuvuudet minimaalisina.
Web-komponenttien pitkän aikavälin arvo ei ole siinä, että ne korvaavat jokaisen frameworkin. Se on siinä, että ne antavat hyödyllisten käyttöliittymäelementtien elää pidempään kuin se framework tai CMS, joka ensin isännöi niitä.