ウェブコンポーネント

どのようなものか

ウェブコンポーネントは、英語ではweb componentsや大文字を使ったWeb
Componentsと書き、制作者が独自のHTML要素を定義できるブラウザー機能群
の一般的な呼び名です。ページでは、その要素を他のタグと同じように使い
ます。標準は各部分をそれぞれの名前で扱います。HTML
Standardのカスタム要素、`template`要素と`slot`要素、DOM
Standardのシャドーツリーです。総称は2014年7月24日付のW3C作業部会ノー
ト_Introduction to Web
Components_の題名にもなっていますが、W3Cはその後この文書の維持を打ち
切り、参照すべきでない文書としています。

カスタム要素は、`HTMLElement`を継承するJavaScriptクラスで定義し、
`customElements.define()`で名前を登録します。その定義はHTMLパーサー
に要素の構築方法と変更への反応を伝えます。それ以降は、マークアップ、
`document.createElement()`、`new`で要素を作れます。名前は小文字の
ASCII英字で始まり、大文字のASCII英字を含まず、ハイフンを含まなければ
なりません。ハイフンは独自の名前を言語自体から区別します。HTML
Standardは、HTML、SVG、MathMLにはハイフンを含む名前の要素を今後追加
しないと定めています。

種類は2つあります。標準自体の例である`<flag-icon
country="nl">`のような自律型カスタム要素は、組み込みの意味を持たない
通常の要素から始めます。カスタマイズされた組み込み要素は、既存の要素
を拡張します。`HTMLButtonElement`を継承するクラスを`{
extends: "button" }`で登録し、`<button
is="plastic-button">`として使うと、フォーカスの動作、フォーム送信、
`disabled`属性など、ボタンをボタンとして成り立たせるすべての機能を保
てます。

シャドーツリーは、ホストと呼ばれる要素に取り付ける独立したノードの木
です。DOM
Standardはホスト側の通常の木をライトツリーと呼びます。
`attachShadow()`でopenまたはclosedモードのシャドールートを作り、ホス
トの`shadowRoot`プロパティーがそれを返すのはopenモードだけです。シャ
ドーツリー内の`slot`要素は、ホスト自身の子を表示する位置を示します。
割り当てられたノードを表示し、なければ自分自身の内容を表示します。名
前付きスロットは、`slot`属性にその名前を持つ子を受け取ります。
`template`要素は、表示されず、スクリプトで複製できるHTML断片を保持し
ます。`shadowrootmode`属性を持つ`template`は宣言的シャドールートを表
すため、シャドーツリーをマークアップへ直接書くこともできます。

なぜ重要なのか

以前は独自に作ったタグに用途はほとんどありませんでした。HTML
Standardも、そのような要素を無効で実用性に乏しかったものとして振り
返っています。カスタム要素は文書の正式な一員です。パーサーが構築し、
DOMメソッドが作成し、属性が変わったときやページへ出入りするときの動
作をクラスが決めます。

定義が先に到着している必要はありません。パーサーが既に作った要素も、
その名前の定義が登録されるとカスタム要素になります。HTML
Standardはこれをアップグレードと呼びます。それまでは`span`に似た未定
義要素として扱われ、中の文字とリンクはそのまま表示されます。標準は、
アップグレードによってカスタム要素のコンテンツを段階的に拡張できると
明記しています。

カスタム要素はフォームやアクセシビリティツリーにも参加できます。クラ
スで`static formAssociated =
true`を設定して`attachInternals()`を呼ぶと、`ElementInternals`オブ
ジェクトが得られます。その`setFormValue()`で要素の値を設定すると、
フォームは他のコントロールと同じように送信します。同じオブジェクトで
ARIAの既定ロールと既定状態を設定でき、ページの制作者が`role`属性や対
応する`aria-*`属性で上書きしない限り、それらが適用されます。また、ス
タイルシートの`:state()`疑似クラスで照合する独自状態も保持できます。

チームにとって、部品を自己完結させるのはシャドーツリーです。ページの
通常のセレクターは内部のシャドーツリーへ入り込まず、外側から装飾でき
る部分はコンポーネント自身が決めます。ただし継承値とカスタムプロパ
ティーは内部へ届き、スロットへ配置したライトツリーの内容にはページの
セレクターが引き続き適用されます。複数のライブラリーがページを共有す
る場合、HTML
Standardは`new
CustomElementRegistry()`で作るスコープ付きレジストリーを用意していま
す。これにより、ライブラリー同士で名前を調整しなくても、それぞれの要
素を共存させられます。

実際の活用例

商品カードを例にすると、各部分の連携が分かります。ページはコンテンツ
を通常のマークアップとして持ち、名前付きスロットに入れる要素へ`slot`
属性を付けます。

```html
<product-card>
  <span slot="name">Oak stool</span>
  <a href="/shop/oak-stool/">See the details</a>
</product-card>
<script type="module" src="product-card.mjs"></script>
```

モジュールが要素を定義します。テンプレートは1回だけ作られ、各カード
のopenモードのシャドールート内へ、それぞれ複製を配置します。

```js
const template = document.createElement("template");
template.innerHTML = `
  <h2 part="title"><slot name="name">Unnamed product</slot></h2>
  <slot></slot>
`;

class ProductCard extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: "open" });
    root.append(template.content.cloneNode(true));
  }
}

if (!customElements.get("product-card")) {
  customElements.define("product-card", ProductCard);
}
```

ページは、コンポーネントが公開する1つのパーツを通じて題名を装飾しま
す。

```css
product-card::part(title) {
  font-size: 1.25rem;
}
```

`product-card.mjs`が実行される前、カードは未定義要素で、読者には商品
名とリンクが通常のインラインコンテンツとして見えます。モジュールが動
くと`define()`がクラスを登録し、既にページ内にあるカードがアップグ
レードされます。コンストラクターはシャドールートを取り付け、テンプ
レートの内容の複製を入れます。`span`は`name`というスロットへ割り当て
られ、見出しの中に現れます。リンクには`slot`属性がないため、名前のな
い既定スロットに入ります。名前のないカードには代わりに、スロット自身
の内容である「Unnamed
product」（名前のない商品）が表示されます。`customElements.get()`に
よる確認は、別のバンドルから同じモジュールの2つ目のコピーが届いたと
きに、`define()`が例外を投げるのを防ぎます。

共有部品は、使われて初めて役に立ちます。このサイトのポートフォリオに
も、その事例があります。iOS 26の「Liquid
Glass」デザインシステムは、新しい画面ごとに少しずつ違うボタン、バッ
ジ、カードを作り直すUIが出発点です。その結果、変更のたびに5つの個別
実装を触る状態になっていました。記録された解決策は、すべての画面で組
み合わせて使う正規の部品群です。Card、Label、Button、
GlassIconButton、DirectoryGridなどを揃え、手作りのバッジやチップを拒
否して正規部品を案内するlint規則も設けました。そのページは部品がカス
タム要素かどうかを述べていません。ただし、部品ごとの定義を1つにし、
レビュー担当者の記憶でなくツールで徹底する方針は共通です。カスタム要
素レジストリーは、同じ名前の2つ目の定義を拒否することで前半を守りま
す。

問題が起きるところ

ハイフン付きの名前でロールを代用する。 HTML
Standardは、「自律型カスタム要素には特別な意味はなく、その子を表す」
と説明しています。例の`taco-button`は必要な作業を示します。ボタンと
して動くには、`tabindex`、ARIAロール`button`、アクセシブルな名前、
`aria-disabled`、EnterとSpaceをクリックに変えるキーハンドラー、無効
状態のスタイルが必要です。それでもカスタム要素は既定のフォーカス動作
を宣言できず、`tabindex="0"`がそのプラットフォームのボタン動作に一致
しないこともあります。既存の要素を基にするなら、標準は組み込み要素の
拡張によって、制作者と利用者の双方の負担を減らせると説明しています。
自律型要素では、各ページへ設定を任せるのではなく、`ElementInternals`
で既定ロールと状態を設定します。

コンストラクターですべてを処理する。 HTML
Standardはカスタム要素のコンストラクターに規則を定めています。引数な
しの`super()`を最初に呼びます。アップグレードではなく新規作成された
要素には属性も子もないため、それらを調べてはいけません。また、要素自
身に属性や子を追加してはいけません。この規則を破ると、パーサーやDOM
メソッドで作れない要素になる場合があります。コンストラクターでは初期
状態、既定値、イベントリスナー、シャドールートを用意し、データ取得と
描画は`connectedCallback`へ移します。

`connectedCallback`が1回しか動かないと思い込む。
複数回動く場合があります。既定では、要素を移動すると
`disconnectedCallback`の後に`connectedCallback`が動き、削除して挿入
し直したかのように状態を初期化します。1回だけ必要な準備はフラグで守
り、`disconnectedCallback`では、`connectedCallback`が開始した処理を
元に戻します。`moveBefore()`による移動で状態を保ちたい場合は、
`connectedMoveCallback`を定義します。本体が空でも、存在するだけで既
定の2つのコールバックに代わります。

同じ名前を2回定義する。
`customElements.define()`は、名前またはクラスが登録済みなら
`NotSupportedError`を投げ、ハイフンがない、大文字を含むなど無効な名
前なら`SyntaxError`を投げます。定義前に`customElements.get()`で確認
し、他と共存する必要のあるライブラリーには専用のスコープ付きレジスト
リーを与えます。

closedモードを保護機能と考える。
closedモードはホストの`shadowRoot`プロパティーからルートを隠します。
また、そのclosedモードのシャドーツリーの外にあるリスナーから見たイベ
ントの合成パスでは、内部のノードを隠します。CSS
Shadow
Partsは、シャドーツリーは意図的にセキュリティ境界ではなく、ページ制
作者の便宜のためだけのものだと明記しています。部品に秘密を入れず、
closedモードは施錠手段としてではなく、外側のコードへの影響で選びま
す。

使えない要素で`attachShadow()`を呼ぶ。 DOM
Standardがシャドールートを認めるのは、有効なカスタム要素名を持つ要素
と、限られた組み込み要素だけです。後者には`div`、`section`、`p`、
`span`などが含まれますが、`button`は含まれません。カスタマイズされた
組み込みボタンで呼ぶと、`NotSupportedError`になります。既にルートを
持つ要素でも動作が異なります。そのルートが宣言的で、同じモードなら、
呼び出しは中身をすべて削除し、空になったルートを返します。それ以外は
例外になります。先に既存のシャドールートを確認し、サーバーから宣言的
ルートとして送ったマークアップを消さずに保ちます。

ページのスタイルが内側まで届くと思い込む。 CSS Shadow
Partsはこの境界を装飾上の障壁と呼び、ページ側で装飾したい場合には部
品の装飾を難しくするとも指摘しています。ページが装飾してよい要素を
`part`で公開し、外側から`::part()`で装飾します。部品の中に別の部品が
ある場合、そのパーツをページへ渡すには、内側のホストに`exportparts`
が必要です。色や間隔をページに合わせるには、ホストへ設定したカスタム
プロパティーを読み取ります。継承によってシャドーツリーへ届くためで
す。

スクリプトが動くまでコンテンツが存在しない。
JavaScriptですべてのテキストを書き込む部品は、定義の読み込みが終わる
まで何も読者へ見せず、スクリプトが失敗すれば何も表示しません。商品
カードのようにライトツリーへコンテンツを残してスロットへ割り当て、
アップグレードが既存の内容を拡張するようにします。表示を待つ必要があ
る場合、HTML
Standard自身の例は、`customElements.whenDefined()`が、
`:not(:defined)`に一致するすべての要素について解決するまで隠していま
す。

参考資料

  * HTML Standard：カスタム要素 —
命名規則、コンストラクター要件、アップグレード、フォーム関連要素、
`ElementInternals`を具体例付きで説明します。

  * DOM Standard：シャドーツリー —
シャドールートとホスト、スロットと割り当てられたノード、
`attachShadow()`の手順。

  * HTML Standard：スクリプト — `template`要素の`shadowrootmode`属性
と、`slot`要素。

  * CSS Shadow Parts —
`part`、`exportparts`、`::part()`疑似要素を定める、2025年12月16日付
のW3C作業草案。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/web-components/	engineer.company	70
