Webb & utveckling

Web Components: Bygg återanvändbara UI-komponenter med vanlig JavaScript

Web Components: Build Reusable UI Components with Vanilla JavaScript

Lär dig Web Components steg för steg genom att bygga ett återanvändbart UI-kort med Custom Elements, Shadow DOM, HTML-mallar, slots och JavaScript-moduler. Inga ramverk eller build-verktyg krävs.

Web Components: Bygg återanvändbara UI-komponenter med vanillis JavaScript

Tänk dig att du skapar ett kort för din webbplats och sedan kan använda det i ett WordPress-tema, en Joomla-tillägg eller en fristående applikation utan att behöva skriva om det för varje miljö.

Detta är löftet med Web Components: verktyg inbyggda i webbläsaren som låter dig bygga återanvändbara HTML-element. För exemplet vi ska bygga behöver du varken React, Vue, npm-paket eller en bundler.

I slutet av den här handledningen kommer du att ha en fungerande <ui-card>-komponent med anpassningsbart innehåll, isolerade stilar, en variant med utseende, en avvisningsknapp och en offentlig händelse. Vi bygger den i små steg så att du kan se vad varje teknik bidrar med.

Vad du kommer att bygga

Vår färdiga komponent kommer att stödja följande 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>

Visuell förhandsvisning – standardkort och kort med utseende

Visuell förhandsvisning av standardkort och kort med utseende för Web Component

Den här förhandsgranskningen är designmålet, inte en skärmdump av en unrelated bibliotek. Vi återskapar den med hjälp av koden nedan.

1. Förstå de fyra byggstenarna

Custom Elements låter oss registrera en ny HTML-tagg och dess JavaScript-beteende. Shadow DOM ger elementet sitt eget interna DOM och scoped stilar. HTML-mallar och slots låter oss återanvända struktur samtidigt som vi kan infoga olika innehåll i varje instans. ES-moduler låter oss ladda komponenten från en vanlig JavaScript-fil.

Dessa är separata funktioner. En Custom Element behöver inte använda Shadow DOM, och du behöver inte ett ramverk för att använda någon av dem.

2. Skapa projektsfilerna

Skapa följande struktur i din editor:

web-components-demo/
├── index.html
├── components/
│   └── ui-card.js
└── css/
    └── main.css

Lägg detta 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>

Lägg till sidnivåstilar i 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 från projektkatalogen, till exempel:

python -m http.server 8000

Besök http://localhost:8000. Rubriken visas, men kortet har inget synligt innehåll ännu. Använd en HTTP-server istället för att öppna index.html med file://, eftersom webbläsarens modulinläsningsregler kan blockera lokala filimport.

3. Registrera ditt första Custom Element

Skapa components/ui-card.js:

class UiCard extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from a Web Component!';
  }
}

customElements.define('ui-card', UiCard);

Uppdatera sidan. Du bör nu se:

Förväntat resultat – Steg 3

Första anpassade elementutdata

HTMLElement tillhandahåller normalt DOM-beteende. connectedCallback() körs när elementet ansluts till dokumentet. customElements.define() associerar klassen med HTML-taggen.

Bindestreck i ui-card är obligatoriskt för autonoma Custom Element-namn. Callback kan köras igen om elementet kopplas bort och återinfogas, vilket är viktigt när vi lägger till initialiseringslogik.

4. Ge kortet sin egen design med Shadow DOM

Ersätt 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);

Förväntat resultat – Steg 4

Styled card inside Shadow DOM

Öppna DevTools, inspektera <ui-card> och expandera #shadow-root (open). Du kommer att se det interna artiklet och stilargensheetet.

Till skillnad från vanliga dokumentselector, når global CSS som article { border: none } normalt inte detta shadow-träd. Ärvda egenskaper och CSS-custom-properties kan dock fortfarande korskoppla gränsen. Shadow DOM kapslar in presentation; det är inte en säkerhetssandbox.

if (this.shadowRoot)-skyddet förhindrar att en andra shadow-root fästs om elementet ansluter igen.

5. Separera layouten med en HTML-mall

Att bädda in allt i connectedCallback() blir besvärligt när en komponent växer. Låt oss definiera markeringen en gång och klona den för varje kort.

Ersätt 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 är ett dokumentfragment. cloneNode(true) kopierar hela strukturen till varje korts shadow-träd. Själva mallen renderas inte förrän vi klonar och infogar den.

Denna version ser nästan identisk ut. Förbättringen är arkitektonisk: en mall kan tjäna många instanser.

6. Infoga olika innehåll med hjälp av slots

Ett återanvändbart kort är inte användbart om varje instans har samma rubrik. Ersätt endast malldeklarationen högst upp i ui-card.js med följande; behåll klassen och registreringskoden från steg 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>
`;

Ersätt nu <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>

Förväntat resultat – Steg 6

Kort med namngivna slots och åtgärdslänk

Den namngivna sloten tar emot elementet markerat slot="title". Den namnlösa sloten tar emot stycket. Action-sloten tar emot länken. En slots fallback-text visas om inget tilldelas till den.

Layouten bor i komponenten; de faktiska orden och länkarna förblir på sidans HTML. Detta är särskilt användbart för CMS-innehåll. Ersätt /tutorial med en riktig destination i ditt projekt.

7. Skapa en variant med utseende med CSS

Inuti mallens <style>-block, lägg till:

:host {
  display: block;
}
:host([variant="featured"]) article {
  background: #eff6ff;
  border-color: #93c5fd;
}

Ersätt sedan det enda kortet i index.html med två 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>

Förväntat resultat – Steg 7

Standardkort och kort med utseende

Detta är en särskilt användbar funktion av :host(): den styler komponenten baserat på attributen hos det anpassade elementet. Om JavaScript ändrar variant senare, uppdateras CSS automatiskt. Ingen attributeChangedCallback() behövs för en rent CSS-drivna förändring.

8. Lägg till en avvisningsknapp och en offentlig händelse

Låt oss göra kortet interaktivt. Inuti mallens <article>, lägg till denna knapp före rubriken:

<button class="dismiss" type="button" aria-label="Dismiss card">
  ×
</button>

Lägg till dessa regler i mallens 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;
}

Ersätt 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, lägg till detta skript före </body>:

<script type="module">
  document.addEventListener('card-dismissed', () => {
    console.log('A card was dismissed.');
  });
</script>

Öppna webbläsarkonsolen och klicka på ×. Kortet försvinner och konsolen visar meddelandet.

Händelsen tillhandahåller en offentlig integrationspunkt: den omgivande applikationen behöver inte veta något om kortets interna knapp. bubbles gör händelsen bubblande; composed tillåter att den korsar en shadow-gräns där det är tillämpligt. Här uppstår händelsen på värdelementet självt.

9. Slutlig version: kopiera och använd

Du kan nu ersätta hela innehållet i components/ui-card.js med den här konsoliderade versionen. Den lägger till CSS-anpassning och exporterade delar samtidigt som den behåller beteendet som byggdes i tidigare steg.

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);
}

Till skillnad från en snabb demo, försöker denna version inte fästa shadow-root två gånger, infogar inte otrovärdigt innehåll med innerHTML, och förlitar sig inte på ett ramverk. Mallsträngen är utvecklarkontrollerad; interpolera aldrig otrovärdig användarinmatning i den.

10. Stylera den från den värdande webbplatsen

Shadow DOM är inte menad för att göra anpassning omöjligt. Den uppmuntrar dig att definiera en avsiktlig stylinggränssnitt.

I css/main.css, lägg till:

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 anpassade egenskaparna ärvds av shadow-trädet och styr värdena vi exponerade. part="container"-attributet låter extern CSS rikta in sig på ett valt internt element med ::part(container).

Om du behöver en annan utseendebakgrund, använd --card-featured-background. Detta är att föredra framför att tvinga konsumenter att bero på den exakta interna DOM-strukturen.

11. Återanvänd kortet i WordPress, Joomla eller vanlig HTML

Kopiera ui-card.js till målsidan och ladda den som en JavaScript-modul:

<script type="module" src="/assets/js/ui-card.js"></script>

Använd sedan <ui-card> i sidans HTML. I WordPress, registrera tillgångar genom temats eller pluginens stödja skriptinläsnings-API:er, med modulstöd som passar din WordPress-version. I Joomla, använd Web Asset Manager för att registrera och ladda modulen. Sprid inte hårdkodade skript-taggar genom produktionsmallar.

För ett CMS-genererat kort, rendera titeln, stycket och länken som slotted HTML. Escape innehåll och attribut enligt CMS:s utgångsregler.

Praktiskt fördel: en Joomla-modul och en WordPress-block kan båda visa samma anpassade tagg medan de delar en komponentimplementation. Varje CMS förblir ansvarig för att hämta och escape sitt eget innehåll.

12. Tillgänglighet, SEO och progressiv förbättring

Använd nativa HTML-kontroller inuti komponenter när det är möjligt. Vår avvisningsåtgärd använder en riktig button, som tillhandahåller tangentaktiveringssemantik, och en aria-label eftersom × ensam inte är beskrivande.

Om en användare avvisar ett kort med tangentfokus, överväg var fokuset ska gå sedan i en mer komplex gränssnitt. Dialogrutor, menyer och comboboxer behöver mycket mer tillgänglighetsbeteende än detta exempel.

Håll viktigt innehåll i meningsfull light-DOM-markering där det är praktiskt. Om JavaScript misslyckas, kommer webbläsaren inte att uppgradera <ui-card>; den slotted rubriken och stycket förblir i dokumentet, men komponentens stylade skal och avvisningsknapp kommer inte att existera.

För sökmotorer, anta inte att JavaScript-only innehåll indexeras identiskt i varje crawlare. Kritiskt innehåll bör vara tillgängligt i den initiala HTML eller genom en lämplig rendringsstrategi.

Shadow DOM har också begränsningar: vanliga dokument CSS-selectorer kan inte styla interna noder, och vissa ARIA ID-relationer kan inte korskoppla shadow-gränser. Designa komponent-API:er med dessa begränsningar i åtanke.

13. Är Web Components alltid snabbare?

Inte nödvändigtvis. Web Components undviker att kräva en viss ramverksruntime, men prestanda beror på mängden JavaScript, DOM-komplextet, renderingfrekvens och applikationsarkitektur.

Ett litet kort är en god kandidat. Hundratals komplexa element med onödig DOM-återbyggnad kan fortfarande vara långsamma. Återanvänd mallar, undvik upprepad fullständig rendering, och mät verklig prestanda.

För en stor applikation som redan är byggd runt ett ramverks statushantering och routing, kan det vara enklare att använda det ramverks egna komponenter. Web Components skiner när ett stabilt UI-element behöver korsra ramverks- eller CMS-gränser.

14. Felsökning

Symptom Trolig orsak Vad att kontrollera
Kortet är tomt Modul laddades inte DevTools-konsol, URL, server MIME-typ
customElements.define kastar Ogiltigt eller duplicerat namn Bindestreckrav och registreringsskydd
CSS tillämpas inte inuti kortet Shadow DOM-gräns Använd custom-properties, :host, eller ::part
Innehåll visas på fel plats Slot namn mismatch Jämför slot="title" med <slot name="title">
Att klicka på avvisningsknappen gör inget Mallknapp saknas Inspektera shadow-trädet och konsol
Komponent misslyckas när den flyttas Initialisering körs två gånger Bevaka shadow-root-skapande
Länk leder till 404 Exempel-URL förstes inte ersatt Använd en existerande destination

Kom ihåg att connectedCallback() kan köras mer än en gång. Skyddet i vårt slutliga exempel håller initialiseringen en-gång; mer sofistikerade komponenter kan behöva att ansluta och ta bort externa observatörer eller globala händelselyssnare under sin anslutningslivslängd.

15. När bör du använda Web Components?

Välj dem när en komponent behöver en återanvändbar, dokumenterad HTML-gränssnitt över flera webbplatser, ramverk eller CMS-miljöer. Kort, notifikationer, produktwidgets och små interaktiva verktyg är goda kandidater.

Skippa abstrationen när några rader av vanlig HTML och CSS redan löser problemet. Och återskapa inte native-kontroller utan en stark anledning.

En användbar test: skulle en annan applikation dra nytta av att använda detta element utan att veta hur det implementerades? Om ja, är en Web Component värd att överväga.

Slutsats

Du har byggt en riktigt återanvändbar komponent, inte bara läst om en webbläsar-API. Den har en anpassad tagg, scoped styling, konfigurerbart innehåll, en variant med utseende och en händelse som annan kod kan lyssna till.

Börja med en komponent som uppträder upprepade gånger i dina projekt. Ge den ett litet offentligt API, testa den i mer än en layout, och håll dess beroenden minimala.

Långsiktig värde av Web Components är inte att de ersätter varje ramverk. Det är att de låter användbara gränssnittselement överleva ramverket eller CMS som först värdede dem.

Officiella referenser