Web Components 自定义元素如何可靠升级：customElements.define、connectedCallback 与重复注册处理

页面模板先输出了 ，组件脚本却因为按需加载晚了几百毫秒。这个标签不会因此永久失效：脚本调用 customElements.define 后，浏览器会把已经存在的未知元素升级成自定义元素实例。麻烦在于，升级和重新插入都可能进入 connectedCallback，如果初始化代码没有边界，价格格式化会重复绑定，甚至把旧节点上的监听器越积越多。

可靠做法是把“注册一次”和“连接时刷新”分开：先用 customElements.get 防重复注册，再让 connectedCallback 只负责可重复执行的渲染，并用 isConnected 保护异步回调。

先把“未知标签”升级路径看清楚

自定义元素名必须包含连字符，例如 price-badge。HTML 解析器遇到它时，若注册表里还没有定义，页面先保留一个普通的未知元素；等模块加载后，customElements.define("price-badge", PriceBadge) 才把这批已有节点接入类定义。之后新建的同名元素也直接使用该类。

这条路径适合 SSR、分片加载和微前端场景，但不要把构造函数当成“元素已经在页面上”的信号。构造阶段只做字段初始化，读取外部尺寸、绑定 DOM 关系等动作放到 connectedCallback 更稳。

class PriceBadge extends HTMLElement {
  constructor() {
    super();
    this._ready = false;
  }

  connectedCallback() {
    this.render();
  }

  render() {
    const value = this.getAttribute("value") ?? "--";
    this.textContent = `¥${value}`;
  }
}

if (!customElements.get("price-badge")) {
  customElements.define("price-badge", PriceBadge);
}

注册保护要挡住哪些重复加载

开发环境的热更新、两个入口同时加载同一个模块，都会让注册代码运行两次。第二次直接调用 customElements.define，浏览器会因为同名定义已存在而拒绝注册。这个错误通常不是组件本身写错，而是模块边界没有做到幂等。

把注册封装成一个小函数即可。customElements.get 返回已注册的构造函数时，直接复用它；返回空值时才定义。注意不要只依赖全局布尔变量，因为不同打包入口可能各自拥有一份模块状态。

function registerPriceBadge() {
  const registered = customElements.get("price-badge");
  if (registered) {
    return registered;
  }
  customElements.define("price-badge", PriceBadge);
  return PriceBadge;
}

registerPriceBadge();

让 connectedCallback 经得起移除和重新插入

WHATWG 明确提醒，connectedCallback 可能调用多次。比如列表虚拟化把节点暂时移出文档，或拖拽排序先断开再插回，都会造成新的连接回调。适合放进去的是“根据当前属性重绘”这类可重复动作；只需发生一次的监听器、观察器则应有明确的安装标记，并在 disconnectedCallback 中清理。

class PriceBadge extends HTMLElement {
  connectedCallback() {
    if (!this._onClick) {
      this._onClick = () => this.setAttribute("active", "");
      this.addEventListener("click", this._onClick);
    }
    this.render();
  }

  disconnectedCallback() {
    if (this._onClick) {
      this.removeEventListener("click", this._onClick);
      this._onClick = null;
    }
  }
}

这里的关键不是让回调只进一次，而是让每一次进入和退出都能把资源状态恢复到可预测的结果。若组件没有事件监听器或观察器，简单的 render() 反而更合适，不必为了“生命周期完整”增加额外状态。

异步更新要在回调返回前确认节点仍然连接

自定义元素经常会在连接后发起价格或库存请求。请求返回时，元素可能已经被列表刷新移除。此时继续修改 DOM 不一定马上报错，但会把旧实例当成当前界面，造成调试时很难追踪的脏状态。

async refreshPrice() {
  const response = await fetch("/api/price?sku=demo");
  const data = await response.json();
  if (!this.isConnected) {
    return;
  }
  this.setAttribute("value", data.price);
  this.render();
}

isConnected 只回答“此刻是否连接到文档”，不替代请求取消，也不代表业务数据仍属于当前商品。如果接口成本高，应进一步使用 AbortController 在断开时取消请求；只是需要防止旧回调写入时，连接检查已经是一道便宜的保险。

上线前用三组场景验收组件

• 先写 HTML 再加载模块：确认已有 price-badge 最终执行了 connectedCallback 并显示 ¥ 前缀。
• 让两个入口同时加载：确认 customElements.get 分支阻止第二次定义，控制台没有同名注册异常。
• 连接、移除、重新插入各一次：确认点击监听器没有叠加，异步返回后用 isConnected 拦住已移除实例。

相关问题

为什么自定义元素名必须带连字符？

这是自定义元素与原生 HTML 标签的命名边界，像 price-badge 这样的名字可以被注册，单词标签则不应拿来占用原生命名空间。

connectedCallback 能不能只执行一次？

不能假设它只执行一次。应让连接逻辑可重复，或用实例字段保护一次性监听器，并在断开回调中清理。

customElements.get 返回的是什么？

如果名称已经注册，它返回对应的构造函数；没有注册时返回空值。注册封装可以据此实现幂等加载。

把注册、连接、断开和异步返回拆成四个可验证的边界后，Web Components 才真正适合被多个入口共同加载。组件升级不是一次偶然的浏览器魔法，而是一条可以通过日志和场景测试稳定验收的生命周期路径。