陷阱一：constructor 里读不到属性和子节点#

这是第一个会让人困惑的地方。自定义元素的 constructor 在两种时机被调用：

1. 注册之后，解析器遇到对应标签，创建元素时；
2. 元素已经在 DOM 里，之后才调用 customElements.define() 时，浏览器逐个「升级」它们。

第一种情况下，constructor 执行时起始标签才刚被解析，属性和子节点都还没就位。第二种情况下，属性和子节点都在，但规范同样不允许你在 constructor 里读取它们。规范的要求很直接：构造函数里不得检查属性、不得检查子节点、不得添加属性或子节点。

所以 constructor 只适合做两件事：初始化内部状态，以及创建 Shadow Root 和其中的静态结构。

1
class CopyButton extends HTMLElement {
2
  static observedAttributes = ["value"];
3

4
  #value = "";
5
  #status = null;
6
  #abort = null;
7

8
  constructor() {
9
    super();
10
    // 创建 shadow root、写入静态结构是允许的
11
    const root = this.attachShadow({ mode: "open" });
12
    root.innerHTML = `
13
      <button type="button" part="button">
14
        <slot name="label">复制</slot>
15
      </button>
16
      <span part="status" role="status"></span>
17
    `;
18
    this.#status = root.querySelector('[part="status"]');
19
  }
20
}

注意 attachShadow 只能调用一次，第二次会抛 NotSupportedError。这一点会在第五节的声明式 Shadow DOM 里变成一个真实的兼容性问题。

陷阱二：connectedCallback 可能执行很多次#

框架里「挂载」通常只有一次。自定义元素不是：节点被移动到另一个父节点时，会先触发 disconnectedCallback，再触发一次 connectedCallback。列表排序、拖拽、把元素从一个容器挪到另一个容器，都会让它重新连接。

意味着 connectedCallback 必须幂等。不要在里面对全局状态做「加一」这类操作，也不要在里面无条件地添加事件监听。

1
connectedCallback() {
2
  // 已经连接过就直接返回；节点被移动时会再次进入这里
3
  if (this.#abort) return;
4
  this.#abort = new AbortController();
5
  document.addEventListener("copy", this.#onCopy, {
6
    signal: this.#abort.signal,
7
  });
8
}
9

10
disconnectedCallback() {
11
  this.#abort?.abort();
12
  this.#abort = null;
13
}

AbortController 的 signal 很适合这个场景：卸载时一次性移除所有监听，不用逐个记住引用。

另外两个相关的细节：

• disconnectedCallback 不保证在页面关闭时触发。 不要把它当成「保存状态」的时机，用户直接关标签页时它可能根本不执行。持久化应该放在明确的用户动作里。
• 解析期间 connectedCallback 早于子节点解析完成。 元素在起始标签处就被插入文档，此时 this.children 往往是空的。需要等待子节点时，用 queueMicrotask 之后的时机，或者监听 slot 的 slotchange。

陷阱三：注册顺序决定回调顺序#

如果元素先出现在 DOM 里、之后才注册，升级过程是固定顺序的：

1. 调用 constructor；
2. 对元素上已有的每个 observedAttributes 中的属性，逐个调用 attributeChangedCallback，此时 oldValue 是 null；
3. 调用 connectedCallback。

而如果是先注册、解析器再创建元素，顺序变成：constructor → 逐个 attributeChangedCallback（属性解析到时触发）→ connectedCallback。两种情况里 attributeChangedCallback 都早于 connectedCallback，所以「在 connected 时读取属性」是安全的，但「在 connected 时假设属性已经全部到齐」则不一定——如果属性是通过 JS 在之后设置的，回调会随后到来。

还有一个默认样式问题#

自定义元素没有浏览器默认样式，它的 display 是 inline。很多「组件没显示出来」的问题，最后都是忘了写 display：

1
copy-button {
2
  display: inline-block;
3
}

或者写在组件内部：

1
:host {
2
  display: inline-block;
3
}

后者只在 Shadow Root 存在时生效。如果脚本加载失败，元素就退回成一个没有样式的 inline 盒子。这个问题在第五节会有一个更好的解法。

为了避免脚本加载期间的闪烁，可以配合 :defined：

1
@media (scripting: enabled) {
2
  copy-button:not(:defined) {
3
    visibility: hidden;
4
  }
5
}

把「隐藏未定义元素」限制在脚本可用的环境里，这样脚本被禁用时内容仍然是可见的，而不是永远藏起来。

布尔属性要按「存在」判断#

HTML 的布尔属性语义是「存在即真」，disabled="false" 依然是禁用状态。所以不要写 this.getAttribute("disabled") === "true"：

1
get disabled() {
2
  return this.hasAttribute("disabled");
3
}
4

5
set disabled(next) {
6
  this.toggleAttribute("disabled", Boolean(next));
7
}

命名映射要手动维护#

attribute 习惯用 kebab-case（max-length），property 习惯用 camelCase（maxLength）。两者不会自动对应，需要自己写映射：

1
static observedAttributes = ["max-length"];
2

3
attributeChangedCallback(name, _old, next) {
4
  if (name === "max-length") this.maxLength = next;
5
}

这也是 Lit 这类库存在的主要理由之一：它们把属性声明、类型转换和反射规则收敛成了一份声明式配置。是否值得引入，取决于你有多少个组件要维护。

穿不过去的#

• 普通选择器。 外部的 .card button 选不到 shadow 内部的 <button>，document.querySelector 也一样。
• id 的作用域。 shadow 内部的 id 和外部的 id 互不冲突，label[for] 也指不过去。
• 事件目标。 从外部监听时，event.target 会被重定向为宿主元素。

最后一条值得展开。点击组件内部的按钮，外部监听器看到的 event.target 是 <copy-button>，不是内部的 <button>：

1
document.querySelector("copy-button").addEventListener("click", (event) => {
2
  console.log(event.target); // <copy-button>
3
  console.log(event.composedPath()[0]); // 内部真正的 <button>
4
});

这是有意的设计：内部结构属于组件的实现细节，不应该泄漏给外部。需要知道真实目标时，用 composedPath()。另外，只有 composed: true 的事件才能穿出 shadow 边界，click、focus 这类 UI 事件默认是 composed 的，自定义事件则需要自己声明。

能穿过去的#

• 继承的 CSS 属性。 color、font-family、line-height 这些会继承进 shadow 内部。
• CSS 自定义属性。 --brand-color 可以穿透边界，这是设计系统向组件传 token 的主要通道。
• ::part()。 组件用 part="button" 暴露内部节点，外部用 ::part(button) 定制。
• ::slotted()。 只能选中 slot 的直接子节点，不能再往下深入。

这里的常见误解是：放进 slot 的元素「属于组件」。实际上它们仍然在 light DOM 里，样式由外部文档决定。::slotted() 只能在组件内部写，而且只能触及直接子节点，所以它更像一个有限的钩子，而不是完整的样式入口。

1
/* 组件内部：暴露 part，并用自定义属性作为主题入口 */
2
:host {
3
  display: inline-flex;
4
  gap: 0.5rem;
5
  --copy-accent: #2563eb;
6
}
7

8
button {
9
  color: var(--copy-accent);
10
  border: 1px solid currentColor;
11
}
12

13
::slotted(svg) {
14
  width: 1em;
15
  height: 1em;
16
}

1
/* 外部：可以改 part 的样式，也可以覆盖自定义属性 */
2
copy-button::part(button) {
3
  border-radius: 6px;
4
}
5

6
copy-button {
7
  --copy-accent: #7c3aed;
8
}

如果组件内部还有嵌套的 shadow 树，需要 exportparts 把内层的 part 再导出一次，否则外部只能看到最外层的 part。

焦点与可访问性#

如果组件内部包了一个输入框，点击宿主元素时焦点不会自动进去。attachShadow({ mode: "open", delegatesFocus: true }) 可以让宿主获得焦点时把焦点转交给内部第一个可聚焦元素。

但 delegatesFocus 只解决焦点转移，不解决语义。一个自制的下拉框不会因为长得像 <select> 就拥有它的键盘行为。ARIA 角色、aria-expanded、方向键处理仍然要自己实现，这部分工作量经常被低估。

客户端不能再 attachShadow#

DSD 之后，connectedCallback 执行时 this.shadowRoot 已经存在。如果构造函数里还是无条件 attachShadow，就会抛 NotSupportedError。正确的写法是复用已经存在的 root：

1
class CopyButton extends HTMLElement {
2
  constructor() {
3
    super();
4
    // DSD 已经创建过 shadow root；没有时才自己建
5
    const root = this.shadowRoot ?? this.attachShadow({ mode: "open" });
6
    this.#hydrate(root);
7
  }
8

9
  #hydrate(root) {
10
    const button = root.querySelector("button");
11
    const status = root.querySelector('[part="status"]');
12
    button?.addEventListener("click", () => this.#copy(status));
13
  }
14
}

注意这里的事件绑定发生在构造函数里。升级时子节点可能还没解析完，但 DSD 的 shadow 内容在解析器创建 shadow root 时就已经写入了，所以 querySelector 能拿到。对于没有 DSD 的普通路径，constructor 里只有你自己写入的结构，同样拿得到。真正拿不到的只有 light DOM 里的子节点。

浏览器支持与降级#

DSD 的支持情况是：Chrome 90+、Safari 16.4+、Firefox 123+。到 2026 年，主流浏览器都已经可用，但如果你的用户群里还有旧版浏览器，需要准备降级方案。

两种常见做法：

1. 保留客户端渲染路径。 也就是上面那段 this.shadowRoot ?? this.attachShadow(...)，加上一个在解析后把普通 <template> 转换成 shadow root 的 polyfill。
2. 不依赖 shadow 的静态降级。 用 @media (scripting: none) 或 :not(:defined) 给未升级状态一套可用的普通样式，保证最坏情况下内容仍然可读。

抓取与序列化#

Shadow DOM 里的文本不在文档的普通 DOM 树里。搜索引擎主流实现会执行脚本并展开 shadow 内容，但不要假设所有抓取器、所有摘要工具都能看到它。对 SEO 关键的正文，不要放进组件的 shadow 里。

同样，host.innerHTML 不会包含 shadow root 的内容，做快照、做 HTML 对比、做端到端断言时都要意识到这一点。

无障碍不能省#

表单控件是交互密度最高的组件，键盘操作和屏幕阅读器支持必须逐项验证：Tab 能进入、方向键能调整、aria-valuenow 这类状态会更新、错误文案和控件有 aria-describedby 关联。ElementInternals 也提供了设置 ARIA 角色的入口，但角色只是起点，行为要自己实现。