[FEE-105] Web Components 與自訂元素
INFO
Web Components 是一組瀏覽器原生 API,讓你定義可重用、封裝的 HTML 元素。Custom Elements、Shadow DOM、HTML Templates 與 Slots 協同運作,提供不需任何框架依賴的元件化開發。它們是平台對元件架構的解答,如今每個主流框架都提供與它們的互通性。
背景
可重用 UI 元件的概念早於 Web。桌面工具集,如 Tk、MFC 與 Swing,在 1990 年代就提供了元件模型,而在 Web 上,這個模式最早透過 jQuery 插件出現。AngularJS(2010)、React(2013)與 Vue(2014)之後各自推出了自己的元件模型,但為某個框架打造的元件若沒有包裝器(wrapper)就無法移植到另一個框架,而且在這段歷史的每個階段,大多數網站其實都沒有使用這些框架:不搭配任何元件函式庫的伺服器端渲染 HTML,仍是主流做法。Web 平台的回應是標準化一個原生元件模型,讓任何框架,或不使用框架,都能以它為目標:設計系統團隊可以把 <date-picker> 實作為一次性的 Custom Element,並在 React、Vue、Angular 與純 HTML 應用程式中重複使用,而不必為每個框架各自維護一份獨立的移植版本。
關鍵規範如下:
| API | 用途 | 規範 |
|---|---|---|
| Custom Elements | 定義具有生命週期回呼的新 HTML 標籤 | WHATWG HTML Living Standard |
| Shadow DOM | 封裝的 DOM 子樹與範圍樣式 | WHATWG DOM Standard |
| HTML Templates | 透過 <template> 的惰性標記片段 | WHATWG HTML Living Standard |
| Slots | 從 light DOM 投射內容到 shadow DOM | WHATWG HTML / DOM Standard |
這裡的 light DOM,指的是消費者巢狀在自訂元素標籤內的一般標記,有別於 shadow root 內部封裝的樹狀結構。
時間線
| 年份 | 里程碑 |
|---|---|
| 2011 | Alex Russell 在 Fronteers 大會提出 Web Components |
| 2013 | Chrome 在 flag 下發布 Custom Elements v0 與 Shadow DOM v0 |
| 2014 | Polymer 0.5,Google 基於 Web Components 建構的函式庫 |
| 2016 | Custom Elements v1 與 Shadow DOM v1 規範定案 |
| 2018 | Firefox 發布 Custom Elements v1 與 Shadow DOM v1 |
| 2020 | Edge(Chromium)發布完整 Web Components 支援;所有主流瀏覽器對齊 |
| 2023 | Declarative Shadow DOM 在 Chrome、Safari 發布;shadowrootmode 屬性標準化 |
| 2024 | Declarative Shadow DOM 達到 Baseline(Firefox 發布支援);Lit 3.x 穩定版 |
上表使用的 Baseline,是 Web 平台由 WebDX Community Group 定義的互通性訊號:當每個主流瀏覽器引擎,Chromium、Firefox 與 WebKit,都提供支援時,一項功能就達到 Baseline。
視覺對比
Web Component 解剖圖
Web Component 結合四個平台 API 形成單一可重用元素。Custom Element 定義標籤及其行為。Shadow DOM 提供封裝的 DOM 子樹與範圍樣式。Templates 與 Slots 啟用從消費者的 light DOM 到元件 shadow DOM 的內容投射。CSS 封裝保持樣式隔離,同時 ::part()、::slotted() 和 CSS custom properties 為消費者提供受控的樣式接口。
範例
自訂元素基礎
Custom Elements 讓你註冊新的 HTML 標籤。自主自訂元素(Autonomous custom elements) 繼承 HTMLElement 並定義全新行為,如下方範例所示。自訂內建元素(Customized built-in elements) 透過 is 屬性繼承既有元素,例如 HTMLButtonElement;瀏覽器支援不一致,Safari 未實作,因此大多數函式庫都避免使用。
每個自訂元素最多會經歷五個生命週期回呼:
| 回呼 | 觸發時機 |
|---|---|
constructor() | 元素建立或升級時。先呼叫 super()。不要存取屬性或子元素。 |
connectedCallback() | 元素插入 DOM 時。可安全讀取屬性、取得資料、設置事件監聽器。 |
disconnectedCallback() | 元素從 DOM 移除時。清理監聽器、觀察者、計時器。 |
attributeChangedCallback(name, oldValue, newValue) | 被觀察的屬性改變時。需要靜態 observedAttributes getter。 |
adoptedCallback() | 元素移動到新文件時(如透過 document.adoptNode())。實務上罕見。 |
以下範例會實際運用這些回呼。
1. 帶有 Shadow DOM 的基本自訂元素
attachShadow({ mode: 'open' }) 會建立一個獨立的 DOM 子樹,也就是 shadow root,並附加到該元素(即 shadow host)上。Shadow root 內的樣式不會外洩,頁面外部的樣式也不會滲入,繼承屬性與 CSS 自訂屬性則是例外。open 模式讓外部 JavaScript 可以透過 element.shadowRoot 讀取 shadow root;closed 模式則會讓這個屬性回傳 null。實務上幾乎總是應該選擇 open:closed 會破壞 DevTools 的檢查功能,卻不提供真正的安全性,因為 shadow 內容依然會渲染,也依然可以透過其他 API 存取。
<user-badge name="Alice" role="admin"></user-badge>
<script>
class UserBadge extends HTMLElement {
static observedAttributes = ['name', 'role'];
constructor() {
super();
this.attachShadow({ mode: 'open' });
}
connectedCallback() {
this.render();
}
attributeChangedCallback() {
// 當觀察的屬性改變時重新渲染
if (this.shadowRoot) this.render();
}
render() {
const name = this.getAttribute('name') || 'Unknown';
const role = this.getAttribute('role') || 'user';
this.shadowRoot.innerHTML = `
<style>
:host {
display: inline-flex;
align-items: center;
gap: 0.5rem;
padding: 0.25rem 0.75rem;
border-radius: 9999px;
font-family: system-ui, sans-serif;
font-size: 0.875rem;
border: 1px solid #ccc;
}
:host([role="admin"]) {
border-color: #4A90D9;
background: #EBF3FB;
}
.dot {
width: 8px;
height: 8px;
border-radius: 50%;
background: #5BA55B;
}
span { font-weight: 600; }
</style>
<span class="dot" part="indicator"></span>
<span part="name">${name}</span>
<small>(${role})</small>
`;
}
}
customElements.define('user-badge', UserBadge);
</script>此範例展示:使用 customElements.define() 註冊自訂元素、使用 observedAttributes 搭配 attributeChangedCallback 實現響應式屬性變化、Shadow DOM 樣式封裝、:host() 條件式 host 樣式,以及 part 屬性作為外部樣式接口。
從外部設定 Shadow DOM 樣式
上面使用的 part 屬性(part="indicator"、part="name")是從元件外部設定 shadow tree 樣式的六種機制之一:
| 機制 | 作用對象 | 範例 |
|---|---|---|
| CSS custom properties | 繼承進入 shadow DOM | my-card { --card-bg: #fff; } |
::part() | Shadow DOM 內具有 part 屬性的元素 | my-card::part(header) { color: blue; } |
::slotted() | 被 slot 的 light DOM 子元素(僅最上層) | ::slotted(h2) { font-size: 1.5rem; } |
:host | 從內部設定 shadow host 樣式 | :host { display: block; } |
:host() | 條件式 host 樣式 | :host([disabled]) { opacity: 0.5; } |
:host-context() | 基於祖先上下文的 host 樣式 | :host-context(.dark) { background: #333; } |
2. 使用 slots 的內容投射
<template> 元素持有惰性 HTML,在透過 JavaScript 複製之前不會被渲染。具名 slot 會投射特定的子元素;預設(未命名)slot 則接收所有未指定的子元素。
<template id="info-panel-template">
<style>
:host {
display: block;
border: 1px solid #ddd;
border-radius: 8px;
overflow: hidden;
font-family: system-ui, sans-serif;
}
header {
background: #f5f5f5;
padding: 0.75rem 1rem;
border-bottom: 1px solid #ddd;
}
.body { padding: 1rem; }
footer {
background: #fafafa;
padding: 0.5rem 1rem;
border-top: 1px solid #ddd;
font-size: 0.875rem;
color: #666;
}
::slotted(h2) { margin: 0; font-size: 1.125rem; }
::slotted(p) { margin: 0.5rem 0 0; }
</style>
<header><slot name="header"></slot></header>
<div class="body"><slot></slot></div>
<footer><slot name="footer">Default footer text</slot></footer>
</template>
<script>
class InfoPanel extends HTMLElement {
constructor() {
super();
const template = document.getElementById('info-panel-template');
this.attachShadow({ mode: 'open' })
.appendChild(template.content.cloneNode(true));
}
}
customElements.define('info-panel', InfoPanel);
</script>
<!-- 使用方式 -->
<info-panel>
<h2 slot="header">Server Status</h2>
<p>All systems operational.</p>
<p>Last checked: 2 minutes ago.</p>
<span slot="footer">Updated every 60 seconds</span>
</info-panel>此範例展示:使用 <template> 作為元件標記、具名 slots(header、footer)與預設 slot 的內容投射、::slotted() 設定投射內容的樣式,以及 <slot> 元素內的回退內容(當未指派內容時顯示「Default footer text」)。
3. 帶有 ElementInternals 的表單關聯自訂元素
預設情況下,自訂元素不會參與表單的提交、驗證或重置。ElementInternals API 改變了這一點。attachInternals() 會回傳一個物件,提供 setFormValue(value) 來設定提交值、setValidity(flags, message, anchor) 透過 constraint validation API 進行自訂驗證、reportValidity() 觸發瀏覽器的驗證 UI、internals.role 與 internals.ariaLabel 等 ARIA 委派屬性,以及透過 internals.states.add('checked') 設定自訂狀態,並以 :state(checked) 偽類暴露給 CSS。
<form id="demo-form">
<star-rating name="rating" required>Rating</star-rating>
<button type="submit">Submit</button>
</form>
<script>
class StarRating extends HTMLElement {
static formAssociated = true;
static observedAttributes = ['value'];
constructor() {
super();
this.internals = this.attachInternals();
this.attachShadow({ mode: 'open' });
this._value = 0;
}
connectedCallback() {
this.shadowRoot.innerHTML = `
<style>
:host { display: inline-flex; align-items: center; gap: 0.5rem; }
.stars { display: inline-flex; cursor: pointer; }
.star { font-size: 1.5rem; color: #ccc; transition: color 0.15s; }
.star.active { color: #f5a623; }
.star:hover, .star:hover ~ .star { color: #f5c66a; }
label { font-size: 0.875rem; font-family: system-ui, sans-serif; }
:host(:state(invalid)) .stars { outline: 2px solid red; border-radius: 4px; }
</style>
<label><slot></slot></label>
<span class="stars" role="radiogroup">${
[1, 2, 3, 4, 5].map(n =>
`<span class="star" role="radio" aria-label="${n} star${n > 1 ? 's' : ''}" data-value="${n}">★</span>`
).join('')
}</span>
`;
this.shadowRoot.querySelector('.stars').addEventListener('click', (e) => {
const star = e.target.closest('.star');
if (!star) return;
this.value = Number(star.dataset.value);
});
// 設定初始驗證狀態
if (this.hasAttribute('required')) {
this.internals.setValidity(
{ valueMissing: true },
'Please select a rating.',
this.shadowRoot.querySelector('.stars')
);
}
}
get value() { return this._value; }
set value(v) {
this._value = v;
this.internals.setFormValue(v > 0 ? String(v) : null);
// 更新驗證狀態
if (this.hasAttribute('required') && v === 0) {
this.internals.setValidity(
{ valueMissing: true },
'Please select a rating.',
this.shadowRoot.querySelector('.stars')
);
this.internals.states.delete('valid');
this.internals.states.add('invalid');
} else {
this.internals.setValidity({});
this.internals.states.delete('invalid');
this.internals.states.add('valid');
}
// 更新視覺狀態
this.shadowRoot.querySelectorAll('.star').forEach((star, i) => {
star.classList.toggle('active', i < v);
star.setAttribute('aria-checked', i < v ? 'true' : 'false');
});
}
formResetCallback() {
this.value = 0;
}
formStateRestoreCallback(state) {
this.value = Number(state) || 0;
}
}
customElements.define('star-rating', StarRating);
document.getElementById('demo-form').addEventListener('submit', (e) => {
e.preventDefault();
const data = new FormData(e.target);
console.log('Rating:', data.get('rating')); // "1" 到 "5"
});
</script>此範例展示:static formAssociated = true 選擇加入表單參與、attachInternals() 進行表單整合、setFormValue() 設定提交值、setValidity() 搭配自訂驗證訊息、透過 internals.states 暴露為 CSS :state(invalid) 的自訂狀態,以及表單生命週期回呼(formResetCallback、formStateRestoreCallback)。
4. 使用 adoptedStyleSheets 在多個實例間共享樣式
上述所有範例都是把 <style> 標籤注入到 shadowRoot.innerHTML 中,這代表瀏覽器每個元素實例都會重新剖析一次該樣式表。adoptedStyleSheets(constructable stylesheets)只需剖析一次 CSSStyleSheet,就能在所有採用它的 shadow root 之間共享:
const cardStyles = new CSSStyleSheet();
cardStyles.replaceSync(`
:host { display: block; border: 1px solid #ccc; border-radius: 8px; padding: 1rem; }
:host([variant="highlight"]) { border-color: #4A90D9; }
`);
class MyCard extends HTMLElement {
constructor() {
super();
const shadow = this.attachShadow({ mode: 'open' });
shadow.adoptedStyleSheets = [cardStyles];
shadow.innerHTML = '<slot></slot>';
}
}
customElements.define('my-card', MyCard);以 200 個 <my-card> 實例來說,這代表 cardStyles 只需剖析一次,就能在全部 200 個 shadow root 之間共享,而不是為完全相同的 <style> 區塊各自剖析 200 次。adoptedStyleSheets 也可以接受多個樣式表,元件還能透過修改共享的 CSSStyleSheet(例如呼叫 cardStyles.replace(newCss))一次更新所有實例。
最佳實踐
標籤名稱必須(MUST)包含連字號。 每個自訂元素名稱必須包含至少一個連字號(例如 my-button、app-header)。這是瀏覽器的強制規定,用以區分自訂元素與內建 HTML 元素。應避免(AVOID)使用單字名稱;瀏覽器會靜默地將其視為未知的內建元素,而非自訂元素。
為每個驅動渲染的屬性宣告 observedAttributes。 靜態 observedAttributes getter 是元素與瀏覽器屬性變更通知系統之間的契約。必須(MUST)在此宣告所有響應式屬性;attributeChangedCallback 只會對列出的名稱觸發。應(SHOULD)將列表保持最小化:只包含變更需要進行 DOM 或狀態更新的屬性。
在發布前審慎決定 Shadow DOM 邊界。 Shadow DOM 是單向門:之後新增或移除它會對使用 CSS 選擇器或遍歷元素內部的 JavaScript 的消費者造成破壞性變更。應(SHOULD)對沒有外部樣式需求的自完備元件使用 Shadow DOM。對於屬於設計系統的元件,應(SHOULD)透過 CSS custom properties 和 ::part() 暴露樣式接口。避免(AVOID)使用 closed 模式;它在不提供真正安全性的情況下會破壞 DevTools 的檢查功能。
對任何參與表單的元素使用 ElementInternals。 自訂元素預設不參與表單提交、驗證或重置。必須(MUST)設定 static formAssociated = true 並呼叫 attachInternals() 來選擇加入。應(SHOULD)實作 formResetCallback 和 formStateRestoreCallback 以匹配原生 input 的行為。避免(AVOID)攔截 submit 事件作為適當表單關聯的替代方案。
保持 slot 組合淺層且明確。 具名 slots(slot="header"、slot="footer")使元素的組合 API 明確,並防止意外的內容投射。應(SHOULD)為不同的內容區域使用具名 slots,並為主體內容使用單一未命名的預設 slot。避免(AVOID)超過一層的 slot 巢狀;被 slot 的內容是用 ::slotted() 設定樣式,而這個選擇器只會匹配頂層的被 slot 子元素,不包含其後代。
設計思維
為什麼平台標準化了元件
上方時間線中的每個框架都各自發明了自己的元件模型,而且彼此不可移植。Web Components 為這些框架提供了一個共同的基線,而不是取代它們:透過 customElements.define() 註冊的自訂元素,可以在任何渲染 HTML 的環境中運作,包括 React、Vue、Angular、Svelte、伺服器端渲染的 HTML、CMS 主題、email 模板,或不需建置步驟的純 .html 檔案。
與框架的共存
Web Components 和框架不是競爭技術。它們佔據不同的利基:
Lit(Google,約 5KB)是原生 API 上的薄包裝,加入響應式屬性(reactive properties)、使用 tagged template literals 的宣告式模板,以及高效 DOM 更新。Lit 元件就是自訂元素:它們繼承 LitElement,而 LitElement 繼承 HTMLElement。
Stencil(Ionic)是一個編譯器,從 TypeScript + JSX 撰寫格式產生標準自訂元素。輸出不依賴框架。
Vue 提供 defineCustomElement() 將任何 Vue 元件包裝為自訂元素,包含 SFC 樣式和 slot 映射。
Angular Elements 使用 createCustomElement() 將 Angular 元件包裝為自訂元素。
React 過去對 Web Components 的支援有限:React 18 及更早版本會把無法辨識的 props 設為字串屬性,而非物件屬性,也無法綁定自訂事件,因此開發者只能改用以 ref 為基礎的包裝器。React 19 修正了這兩個問題,新增了客戶端與伺服器端的屬性設定,以及原生的 on<EventName> 自訂事件監聽器,如今已通過完整的 Custom Elements Everywhere 測試套件。
何時使用 Web Components
Web Components 擅長橫向共享(horizontal sharing):跨不同框架或在框架之外使用的元件。
| 使用場景 | Web Components | 框架元件 |
|---|---|---|
| 設計系統(Design systems) 供使用不同框架的團隊共用 | 首選,到處都能運作 | 每個團隊需要框架專屬的包裝器 |
| 微前端(Micro-frontends) | 很好的選擇,每個微前端可使用任何內部技術 | 需要特定執行時期的 shell |
| CMS 小工具、可嵌入元件 | 理想,消費者不需框架依賴 | 需要打包框架執行時期 |
| 應用程式內部(路由、狀態、複雜 UI) | 過度,框架提供更好的開發者體驗 | 首選,響應式狀態、工具鏈、生態系統 |
| 效能敏感的列表、表格 | 中性:搭配 adoptedStyleSheets(範例 4)可避免每個實例的 Shadow DOM 額外開銷 | 框架 virtual DOM 可批次更新 |
這個決定取決於上下文。一個為五個團隊(使用三種不同框架)建構元件的設計系統團隊,有充分理由使用 Web Components。一個建構單一 React 應用程式的產品團隊則沒有。
深入探討
自訂元素的升級生命週期
當 HTML 解析器遇到像 <my-badge> 這樣的未知標籤時,它會建立一個沒有自訂行為的普通 HTMLElement 實例。該元素存在於 DOM 中,但處於**未定義(undefined)**狀態:它沒有已註冊的類別,因此不會執行任何生命週期回呼,也沒有 shadow root。
customElements.define('my-badge', MyBadge) 將 registry 從 undefined 轉移到已定義(defined)狀態。瀏覽器隨後對 DOM 中已存在的每個匹配元素同步執行升級演算法(upgrade algorithm)。在升級過程中,元素的原型鏈被替換為已註冊的類別,constructor 主體執行(此時元素的屬性和子元素已存在),元素進入**已升級(upgraded)**狀態。
connectedCallback 在升級完成之後觸發,而非當解析器第一次遇到標籤時。這個區別很重要:如果呼叫 customElements.define() 的腳本以非同步方式載入(作為延遲載入或動態匯入的模組),會有一個時間窗口,在此期間元素存在於 DOM 中但沒有自訂行為。在這個時間窗口內,使用者可能看到未設定樣式或空白的內容。
對於伺服器端渲染(SSR)的 HTML,這個時序是渲染模型的核心。伺服器輸出元素的標記,瀏覽器解析並顯示它(可能透過 Declarative Shadow DOM 提供初始的視覺結構),當腳本到達時,自訂元素類別才升級該元素。元素在 JavaScript 載入之前就已渲染:相對於解析過程,升級是非同步進行的。
customElements.whenDefined() 是任何依賴元素升級後才執行的程式碼的正確模式:
// 等待 'user-badge' 被定義後解析(現有元素的升級與 define() 同步執行)
await customElements.whenDefined('user-badge');
const badges = document.querySelectorAll('user-badge');
badges.forEach(badge => badge.refresh());此方法回傳一個 Promise,在 customElements.define() 被呼叫後以建構函式解析。這比 DOMContentLoaded(在延遲腳本執行之前觸發)更安全,比全域 load 事件更精確。當協調依賴自訂元素行為可用性的頁面初始化邏輯時,應使用它。
以下是四個概念性的生命週期階段:undefined(解析器遇到未知標籤)→ defined(類別已註冊)→ upgraded(升級演算法執行,constructor 執行)→ connected(插入後觸發 connectedCallback)。注意:HTML 規範並不將「defined」和「upgraded」區分為獨立的可觀察狀態;升級是作為 define() 的一部分同步執行的。理解這些階段可防止在元素升級之前就讀取元素屬性或呼叫元素方法所導致的錯誤。
Declarative Shadow DOM(宣告式 Shadow DOM)
傳統上,Shadow DOM 需要 JavaScript 呼叫 attachShadow()。Declarative Shadow DOM(DSD)改為透過帶有 shadowrootmode 屬性的 <template>,直接從靜態 HTML 附加 shadow root:
<my-card>
<template shadowrootmode="open">
<style>
:host { display: block; border: 1px solid #ccc; padding: 1rem; }
</style>
<slot></slot>
</template>
<p>This content is projected into the slot.</p>
</my-card>DSD 對伺服器端渲染的 Web Components 而言是必要的。沒有它,shadow DOM 內容就無法成為初始 HTML 載荷的一部分;頁面必須等待 JavaScript 執行後,元件才能渲染。
Scoped Custom Element Registries(範圍限定的自訂元素登錄檔)
兩個各自獨立版控的元件函式庫,若同時在一個頁面中,都可能嘗試定義 <x-button>。預設情況下,第二次呼叫 customElements.define() 會拋出錯誤,因為登錄檔(registry)是整個文件共用的全域物件。Scoped Custom Element Registries 讓 shadow root 可以附加到自己的登錄檔,而不是全域登錄檔,藉此解決這個問題:
const registry = new CustomElementRegistry();
registry.define('x-button', XButtonV2);
const shadow = host.attachShadow({
mode: 'open',
customElementRegistry: registry,
});在該 shadow root 內渲染的元素,會依照這個範圍限定的登錄檔來解析 <x-button>,因此 v2 版元件可以和全域登錄的 v1 版 <x-button>,或頁面其他地方另一個範圍限定登錄檔中的 <x-button>,同時共存。此舉消除了先前的命名衝突限制:這個限制曾迫使共用頁面的團隊在所有函式庫之間協調自訂元素名稱,或是將名稱版本化為 x-button-v2。範圍限定登錄檔已於 Chrome 與 Edge 146(2026 年 3 月)預設隨附;尚未原生支援的瀏覽器則有 polyfill 可用。
Custom Elements Manifest
Custom Elements Manifest(custom-elements.json)是一個社群標準檔案格式,用來描述套件的自訂元素:其屬性(attributes)、特性(properties)、方法、事件、slots、CSS 自訂屬性和 CSS parts。schema 版本為 2.1.0。
工具使用此 manifest 進行:
- IDE 支援:在 HTML 和模板語法中提供自動完成、懸停文件、未知標籤警告
- 文件生成:Storybook、API 文件檢視器
- 框架包裝器:自動生成 React/Vue/Angular 包裝器
@custom-elements-manifest/analyzer(來自 Open Web Components)從原始碼生成 manifest。套件會在 package.json 中宣告 manifest 位置:
{
"customElements": "custom-elements.json"
}常見錯誤
1. 未在 constructor 中呼叫 super()
// 錯誤:缺少 super() 呼叫
class MyElement extends HTMLElement {
constructor() {
this.data = [];
}
}影響: 瀏覽器會拋出 ReferenceError:「Must call super constructor in derived class before accessing 'this'」。元素無法被實例化。
修正: 始終將 super() 作為 constructor 的第一個語句:
class MyElement extends HTMLElement {
constructor() {
super();
this.data = [];
}
}2. 在 constructor 中操作 DOM
// 錯誤:在 constructor 中存取屬性和子元素
class MyElement extends HTMLElement {
constructor() {
super();
this.textContent = this.getAttribute('label'); // 屬性可能尚不存在
this.appendChild(document.createElement('div')); // 在某些升級場景下會拋出錯誤
}
}影響: 當解析器建立元素時,屬性和子元素可能尚不可用。createElement 路徑和解析器升級路徑行為不同,導致結果不一致。規範明確禁止在 constructor 中檢查屬性或新增子元素。
修正: 將 DOM 操作延遲到 connectedCallback():
class MyElement extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' }); // attachShadow 在 constructor 中是允許的
}
connectedCallback() {
const label = this.getAttribute('label') || 'Default';
this.shadowRoot.innerHTML = `<span>${label}</span>`;
}
}3. 忘記呼叫 customElements.define()
<!-- 錯誤:class 已定義但從未註冊 -->
<my-widget>Content here</my-widget>
<script>
class MyWidget extends HTMLElement {
connectedCallback() {
this.textContent = 'Widget loaded';
}
}
// 缺少:customElements.define('my-widget', MyWidget);
</script>影響: 瀏覽器將 <my-widget> 視為 HTMLUnknownElement。不會觸發任何生命週期回呼。元素出現在 DOM 中但沒有自訂行為。控制台沒有錯誤;它會靜默失敗。
修正: 始終在定義 class 之後註冊元素:
customElements.define('my-widget', MyWidget);注意:標籤名稱必須包含連字號(-)以區分自訂元素與內建 HTML 元素。
4. 誤以為 ARIA ID 參照能跨越 shadow 邊界
<!-- 錯誤:#hint 存在於 light DOM 中,而參照它的元素 -->
<!-- 卻位在元件的 shadow root 內 -->
<my-input>
<span id="hint">Must be 8+ characters</span>
</my-input>
<script>
class MyInput extends HTMLElement {
connectedCallback() {
this.attachShadow({ mode: 'open' }).innerHTML = `
<input aria-describedby="hint" />
`;
}
}
customElements.define('my-input', MyInput);
</script>影響: aria-describedby 和 aria-labelledby、aria-activedescendant 一樣,都只會在單一 tree scope 內解析 id 參照。#hint 位於 light DOM,與包含 <input> 的 shadow root 屬於不同的 tree scope,因此輔助技術會把這個參照當成該 id 不存在,描述文字就這樣被靜默捨棄。這是 Shadow DOM 最為人知的無障礙陷阱,也直接影響範例 3 的表單控制項使用情境:ElementInternals 會設定 host 的角色與可存取名稱,但無法讓某個 tree scope 中的 id 被另一個 tree scope 解析。
修正: 把被參照的元素移到與參照它的元素相同的 shadow root 內。若無法這麼做,可在支援的環境中改用元素參照屬性(element-reflection property)來反映這層關係,例如 internals.ariaDescribedByElements = [hintElement],而不是使用 id 字串;或是持續關注 Reference Target 提案(shadowrootreferencetarget),該提案截至 2026 年仍屬實驗性質,正在 Chromium 與 WebKit 中進行原型開發。在其中一項技術廣泛落地之前,應將以 IDREF 為基礎的 ARIA 關係保持在單一 tree scope 內。
延伸閱讀
參考資料
- WHATWG HTML Living Standard -- Custom Elements -- 自訂元素定義、生命週期回呼、表單關聯自訂元素和 CustomElementRegistry API 的權威規範
- MDN: Web Components -- Custom Elements、Shadow DOM、Templates 和 Slots 的完整參考與指南
- MDN: Using Custom Elements -- 定義與使用自主和自訂內建元素的實用指南
- MDN: Using Shadow DOM -- attachShadow()、open 與 closed 模式及 shadow DOM 概念指南
- MDN: Using Templates and Slots -- template 元素與具名/預設 slot 內容投射指南
- MDN: ElementInternals -- 表單關聯、自訂驗證、ARIA 委派和自訂狀態的 API 參考
- web.dev: Custom Elements v1 -- 自訂元素撰寫的實用指南與範例及最佳實踐
- web.dev: Declarative Shadow DOM -- 使用 shadowrootmode 屬性進行 Web Components 伺服器端渲染的指南
- Lit Documentation -- Lit 文件,一個用於建構具有響應式屬性和宣告式模板的 Web Components 的輕量函式庫
- Custom Elements Manifest -- 用於在 custom-elements.json 中描述自訂元素 metadata 的社群標準 schema(v2.1.0)
- WebKit: ElementInternals and Form-Associated Custom Elements -- WebKit 對 ElementInternals API 和表單參與的說明
- Nolan Lawson: Shadow DOM and Accessibility -- The Trouble with ARIA -- 說明為何 ARIA IDREF 屬性無法跨越 shadow tree 邊界,並整理各種因應方式
- Igalia: Solving Cross-root ARIA Issues in Shadow DOM -- 跨 shadow root ARIA 關係的 Reference Target 提案現況
- Chrome for Developers: Make Custom Elements Behave with Scoped Registries -- 介紹每個 shadow root 各自擁有 CustomElementRegistry 的 API,以及它所解決的命名衝突問題
- Frontend Masters: Constructable Stylesheets and adoptedStyleSheets -- One Parse, Every Shadow Root -- 說明 adoptedStyleSheets 如何讓單一份已剖析的樣式表在所有 shadow root 實例間共享
- Custom Elements Everywhere -- 追蹤各框架(包括 React)自訂元素屬性與事件支援情況的相容性測試結果
- React Blog: React v19 -- React 19 版本說明,涵蓋自訂元素屬性與事件處理的變更