Web・開発

Web Components: Vanilla JavaScriptで再利用可能なUIコンポーネントを構築

Web Components: Build Reusable UI Components with Vanilla JavaScript

Web Componentsを段階的に学び、Custom Elements、Shadow DOM、HTML Templates、slots、JavaScript modulesを使って再利用可能なUIカードを構築します。フレームワークやビルドツールは不要です。

Web Components:バニラJavaScriptで再利用可能なUIコンポーネントを構築する

ウェブサイト用のカードを作成し、それをWordPressのテーマ、Joomlaの拡張機能、またはスタンドアロンアプリケーションで使用できるようにし、それぞれの環境に合わせて再記述する必要がないと想像してみてください。

それがWeb Componentsが約束するものです。これは、ブラウザに組み込まれたツールで、再利用可能なHTML要素を構築できます。このチュートリアルで構築する例では、React、Vue、npmパッケージ、またはバンドラは必要ありません。

このチュートリアルの終わりには、カスタマイズ可能なコンテンツ、孤立したスタイル、フィーチャーバリアント、削除ボタン、およびパブリックイベントを備えた動作する<ui-card>コンポーネントが得られます。各テクノロジーが何に貢献するかを把握できるように、小さなステップで構築していきます。

構築するもの

完成したコンポーネントは、次の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>

ビジュアルプレビュー — 標準カードとフィーチャーカード

Web Componentカードの標準カードとフィーチャーカードのビジュアルプレビュー

このプレビューは、デザインの目標であり、無関係なライブラリのスクリーンショットではありません。以下のコードを使用して再現します。

1. 4つの構築ブロックを理解する

カスタムエレメントは、新しいHTMLタグとそのJavaScriptの動作を登録できます。Shadow DOMは、要素に独自の内部DOMとスコープ付きのスタイルを提供します。HTMLテンプレートとスロットは、構造を再利用しながら、各インスタンスに異なるコンテンツを挿入できます。ESモジュールは、通常のJavaScriptファイルからコンポーネントを読み込むことができます。

これらは独立した機能です。カスタムエレメントはShadow DOMを使用する必要がなく、フレームワークなしでこれらの機能をすべて使用できます。

2. プロジェクトファイルを作成する

エディタに次の構造を作成します。

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

これを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>

ページレベルのスタイルを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;
}

プロジェクトディレクトリからローカルHTTPサーバーを実行します。例えば:

python -m http.server 8000

http://localhost:8000にアクセスします。見出しは表示されますが、カードにはまだ目に見えるコンテンツがありません。HTTPサーバーを使用し、index.htmlをfile://で開くのは避けましょう。ブラウザのモジュール読み込みルールがローカルファイルインポートをブロックする可能性があります。

3. 最初のCustom Elementを登録する

components/ui-card.jsを作成します。

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

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

ページを更新します。次が表示されるはずです:

ステップ3の期待される結果

最初のCustom Elementの出力

HTMLElementは通常のDOM動作を提供します。connectedCallback()は、要素がドキュメントに接続されたときに実行されます。customElements.define()は、クラスとHTMLタグを関連付けます。

ui-cardのハイフンは、自動的なCustom Element名に必要です。コールバックは、要素が切り離されて再挿入された場合に再度実行される可能性があります。これは、初期化ロジックを追加する際に重要です。

4. Shadow DOMでカードに独自のデザインを与える

ui-card.jsを次のように置き換えます。

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

ステップ4の期待される結果

Shadow DOM内のスタイリングされたカード

DevToolsを開き、<ui-card>を検査し、#shadow-root (open)を展開します。内部のarticleとstylesheetが表示されます。

通常のdocumentセレクターとは異なり、グローバルCSS(article { border: none }など)は通常、このシャドウトリーに到達できません。継承されたプロパティとCSSカスタムプロパティは、境界をまたぐことができます。Shadow DOMはプレゼンテーションをカプセル化しますが、セキュリティサンドボックスではありません。

if (this.shadowRoot)ガードは、要素が再接続された場合に2番目のシャドールートをアタッチするのを防ぎます。

5. HTMLテンプレートでレイアウトを分離する

connectedCallback()内にすべてを埋め込むと、コンポーネントが大きくなるにつれて不便になります。マークアップを1回定義し、各カードにクローンして使用しましょう。

ファイルを次のように置き換えます。

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はドキュメントフラグメントです。cloneNode(true)は、すべての構造を各カードのシャドウトリーにコピーします。テンプレート自体は、クローンして挿入するまでレンダリングされません。

このバージョンはほぼ同一に見えます。改善点はアーキテクチャ的です:1つのテンプレートが多くのインスタンスを提供できます。

praticamente スロットを使用して異なるコンテンツを挿入する

再利用可能なカードが、すべてのインスタンスで同じ見出しを持つ場合、役に立ちません。ui-card.jsの上部のテンプレート宣言のみを次のように置き換えます。ステップ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>
`;

次に、<ui-card></ui-card>を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>

ステップ6の期待される結果

名前付きスロットとアクショリンクを持つカード

名前付きスロットは、slot="title"でマークされた要素を受け取ります。無名スロットは、段落を受け取ります。アクションスロットは、リンクを受け取ります。スロットのフォールバックテキストは、何も割り当てられていない場合に表示されます。

レイアウトはコンポーネント内にある一方、実際の単語とリンクはページ内のHTMLに残ります。これは、特にCMSコンテンツに役立ちます。/tutorialをプロジェクトの実際の宛先と置き換えてください。

7. CSSでフィーチャーバリアントを作成する

テンプレートの<style>ブロック内に次を追加します。

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

次に、index.htmlの単一カードを2つのカードに置き換えます。

<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>

ステップ7の期待される結果

標準カードとフィーチャーバリアント

これは:host()の特に有用な機能です:カスタムエレメントの属性に基づいてコンポーネントをスタイリングします。JavaScriptが後でvariantを変更しても、CSSは自動的に更新されます。純粋にCSS駆動の変更にはattributeChangedCallback()は必要ありません。

8. 削除ボタンとパブリックイベントを追加する

カードをインタラクティブにしましょう。テンプレートの<article>内に、このボタンを見出しの前に追加します。

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

テンプレートの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;
}

connectedCallback()をクラス内に置き換えます。

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

index.html内に、</body>の前に次のスクリプトを追加します。

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

ブラウザコンソールを開き、×をクリックします。カードが消え、コンソールにメッセージが表示されます。

イベントはパブリックな統合ポイントを提供します:周囲のアプリケーションは、カードの内部ボタンについて何も知る必要はありません。bubblesはイベントがバブルするようにし、composedは、該当する場合、シャドー境界をまたぐことを許可します。ここでは、イベントはホスト要素自体から発生します。

9. 最終バージョンを完成させる:コピーして使用

これで、components/ui-card.jsのすべての内容を、この統合バージョンに置き換えることができます。これにより、以前のステップで構築された動作を維持しながら、CSSカスタマイズとエクスポートされたパーツが追加されます。

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

クイックデモとは異なり、このバージョンはシャドールートの2回のアタッチを試みず、innerHTMLで信頼できないコンテンツを挿入せず、フレームワークに依存しません。テンプレート文字列は開発者が制御します。信頼できないユーザー入力をそこにインターセプトしないでください。

10. ホストウェブサイトからスタイリングする

Shadow DOMは、カスタマイズを不可能にするためにあるわけではありません。意図的なスタイリングインターフェースを定義することを奨励します。

css/main.cssに次を追加します。

ui-card {
  --card-border: #cbd5e1;
  --card-title-color: #0f766e;
}
ui-card::part(container) {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}

カスタムプロパティはシャドウトリーに継承され、エクスポートした値を制御します。part="container"属性は、外部CSSが選択された内部要素に::part(container)をターゲットにできるようにします。

異なるフィーチャーバックグラウンドが必要な場合は、--card-featured-backgroundを使用します。これは、消費者が正確な内部DOM構造に依存することを強いるよりも好ましいです。

11. WordPress、Joomla、またはプレーンHTMLでカードを再利用する

ui-card.jsをターゲットウェブサイトにコピーし、JavaScriptモジュールとして読み込みます。

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

次に、<ui-card>をページマークアップで使用します。WordPressでは、テーマまたはプラグインのサポートされているスクリプト読み込みAPIを通じてアセットを登録し、WordPressバージョンに適したモジュールサポートを使用します。Joomlaでは、Web Asset Managerを使用してモジュールを登録および読み込みます。ハードコードされたスクリプトタグを本番テンプレートに散りばめないでください。

CMS生成のカードの場合、タイトル、段落、リンクをスロット付きHTMLとしてレンダリングします。コンテンツと属性をCMSの出力ルールに従ってエスケープします。

実用的なメリット:JoomlaモジュールとWordPressブロックは、両方が同じカスタムタグを出力し、1つのコンポーネント実装を共有できます。各CMSは、独自の数値をフェッチしてエスケープする責任を負います。

12. アクセシビリティ、SEO、およびプログレッシブエンハンスメント

可能な限り、コンポーネント内にネイティブHTMLコントロールを使用してください。削除アクションには、実際のbuttonを使用します。これにより、キーボードアクティベーションセマンティクスが提供され、aria-labelも使用します。×だけでは説明的ではないためです。

キーボードフォーカスでカードを削除する場合、より複雑なインターフェースでフォーカスがどこに移動すべきかを検討してください。ダイアログ、メニュー、コンボボックスは、この例よりもはるかに多くのアクセシビリティ動作を必要とします。

重要なコンテンツは、実用的な範囲で意味のあるlight-DOMマークアップに保持してください。JavaScriptが失敗した場合、ブラウザは<ui-card>をアップグレードしません。スロット付きのヘッダーと段落はドキュメントに残りますが、コンポーネントのスタイリングされたシェルと削除ボタンは存在しません。

検索エンジンについては、JavaScriptのみのコンテンツがすべてのクローラーで同じようにインデックスされるとは仮定しないでください。重要なコンテンツは、初期HTMLまたは適切なレンダリング戦略を通じて利用可能である必要があります。

Shadow DOMにも制限があります:通常のdocument CSSセレクターは内部ノードをスタイリングできず、一部のARIA ID関係はシャドー境界をまたぐことができません。これらの制約を考慮してコンポーネントAPIを設計してください。

13. Web Componentsは常に高速ですか?

必ずしもそうではありません。Web Componentsは、特定のフレームワークランタイムを必要としませんが、パフォーマンスはJavaScriptの量、DOMの複雑さ、レンダリング頻度、およびアプリケーションのアーキテクチャに依存します。

小さなカードは良い候補です。不要なDOM再構築を伴う数百の複雑な要素はまだ遅くなる可能性があります。テンプレートを再利用し、繰り返しフルレンダリングを避け、実際の性能を測定してください。

すでにフレームワークのステート管理とルーティングを中心に構築された大規模なアプリケーションでは、そのフレームワークの独自のコンポーネントを使用する方が簡単かもしれません。Web Componentsは、安定したUI要素がフレームワークやCMSの境界をまたぐ必要がある場合に威力を発揮します。

14. トラブルシューティング

症状 考えられる原因 確認すべき点
カードが空である モジュールが読み込まれていない DevToolsコンソール、URL、サーバーのMIMEタイプ
customElements.defineがスローされる 無効または重複した名前 ハイフン要件と登録ガード
CSSがカード内に適用されない Shadow DOMの境界 カスタムプロパティ、:host、または::partを使用する
コンテンツが間違った場所に表示される スロット名の不一致 slot="title"と<slot name="title">を比較する
削除ボタンをクリックしても何も起こらない テンプレートのボタンが欠落している シャドートリーを検査し、コンソールを確認する
コンポーネントが移動すると失敗する 初期化が2回実行される シャドールート作成をガードする
リンクが404になる 例のURLが置き換えられていない 既存の宛先を使用する

connectedCallback()は複数回実行できる可能性があることを覚えておいてください。私たちの最終的な例では、ガードにより初期化が1回だけ行われます。より複雑なコンポーネントでは、コネクションライフサイクル中に外部オブザーバーやグローバルイベントリスナーのアタッチと削除を行う必要がある場合があります。

15. Web Componentsを使用すべきなのはいつですか?

コンポーネントが複数のウェブサイト、フレームワーク、またはCMS環境で再利用可能で、ドキュメント化されたHTMLインターフェースを必要とする場合に、それを選択してください。カード、通知、製品ウィジェット、小さなインタラクティブツールは良い候補です。

数行の通常のHTMLとCSSで問題を解決できる場合は、抽象化をスキップしてください。また、強い理由がない限り、ネイティブコントロールを再現しないでください。

有用なテスト:別のアプリケーションが、この要素をその実装方法を知らずに利用できるでしょうか?もしそうなら、Web Componentを検討する価値があります。

結論

あなたは、ブラウザAPIについて読むだけでなく、実際のコンポーネントを構築しました。これは、カスタムタグ、スコープ付きスタイリング、構成可能なコンテンツ、フィーチャーバリアント、および他のコードがリスンできるイベントを持っています。

プロジェクト内で繰り返し現れる1つのコンポーネントから始めましょう。小さなパブリックAPIを与え、複数のレイアウトでテストし、依存関係を最小限に抑えてください。

Web Componentsの長期的な価値は、あらゆるフレームワークを置き換えることではありません。それらは、最初にホストしたフレームワークやCMSを超えて有用なインターフェース要素を存続させることを可能にします。

公式リファレンス