Web Components 的 customElements.whenDefined 怎么处理组件先渲染后注册：升级时机与失败分支

页面骨架和组件脚本经常不是同时到达：HTML 里已经有了 ，但网络慢时它还只是一个未知元素。解决这个竞态的关键不是反复查询 DOM，而是让初始化等待 customElements.whenDefined('profile-card')，并把“已注册”和“脚本加载失败”分开处理。

先渲染后注册并不是异常：元素会在定义完成后自动升级。需要等待组件能力时，用 whenDefined() 等注册完成，再执行依赖组件方法的代码；等待本身不会替你处理脚本加载失败。

问题现场：卡片先出现，增强逻辑却偶尔不执行

假设服务端直接输出了一个 。为了拆分首屏脚本，组件定义被延后加载。此时浏览器已经完成 HTML 解析，页面里能查到这个 unknown element，但 customElements.get('profile-card') 仍然返回 undefined。

这不是节点丢失。浏览器保留它的标签名和属性，等注册表出现同名定义后再升级；真正容易出错的是初始化代码马上调用组件方法，或者把“脚本没加载”和“组件还没注册”混成一种状态。

动手验证：先确认元素处于哪个阶段

把下面的探针放在页面入口，能观察到“节点存在”和“构造函数已注册”是两件事：

const card = document.querySelector('profile-card');
console.log(card !== null); // 节点可能已经存在
console.log(customElements.get('profile-card')); // 注册前是 undefined

customElements.whenDefined('profile-card').then(() => {
  console.log(customElements.get('profile-card'));
});

whenDefined接收合法的自定义元素名并返回 Promise。如果名字已经注册，Promise 会很快兑现；如果尚未注册，它会等到对应的 customElements.define 调用发生。这个承诺对应的是注册表状态，不是网络请求状态。

定位原因：注册完成后，已有节点才会升级

组件脚本可以这样写：

class ProfileCard extends HTMLElement {
  connectedCallback() {
    this.textContent = `用户 ${this.getAttribute('user-id')}`;
  }
}

customElements.define('profile-card', ProfileCard);

customElements.whenDefined('profile-card').then(() => {
  document.querySelector('profile-card')?.focus();
});

这里的调用链是：customElements.define写入注册表，浏览器升级页面中已有的 profile-card，随后组件的 connectedCallback运行；whenDefined的回调适合放必须等组件能力出现的动作。它不会重新创建一个节点，也不需要手动替换原标签。

修复方案：把注册等待和脚本加载放进两个分支

如果组件脚本是动态加载的，建议让加载 Promise 负责网络结果，让 whenDefined负责注册结果：

async function ensureProfileCard() {
  const registered = customElements.get('profile-card');
  if (!registered) {
    await import('/components/profile-card.js');
  }

  await customElements.whenDefined('profile-card');
  return customElements.get('profile-card');
}

ensureProfileCard()
  .then(() => document.querySelector('profile-card')?.removeAttribute('aria-busy'))
  .catch((error) => {
    document.querySelector('profile-card')?.setAttribute('data-state', 'load-failed');
    console.error(error);
  });

第二张图把这两个状态分开：whenDefined成功后才进入 connectedCallback依赖的动作；动态导入失败则走 load-failed，不会一直把用户留在等待状态。

两个容易忽略的边界

重复 define 不是安全的重试

同一个注册表中，customElements.define('profile-card', ProfileCard)只能成功一次。热更新、重复执行入口脚本或两个模块都负责注册时，第二次定义会抛出异常。入口可以先用 customElements.get()判断，但更重要的是明确“谁拥有注册责任”，不要用捕获异常掩盖两个版本的组件同时存在。

whenDefined 不会替你兜底超时

如果脚本既没有成功加载，也没有调用 define，等待 Promise 就没有兑现时机。需要可恢复的页面可以给动态导入加超时和错误 UI；不要把无限等待误判成“组件还在升级”。

复查结果：用三个状态确认竞态已经收敛

刷新慢网速环境后，依次检查：节点是否已经存在；customElements.get('profile-card')是否返回构造函数；组件是否完成 connectedCallback中的可见更新。若第三步没有发生，再回头看动态导入错误，而不是继续增加 DOM 查询定时器。

相关问题

未知的自定义元素会立刻报错吗？

通常不会因为元素尚未定义就阻止 HTML 解析；它会先作为未知元素存在，待注册后再升级。真正的脚本语法错误或模块加载失败仍需单独处理。

什么时候直接调用 customElements.get？

只需要判断当前是否已注册时直接调用即可；要等待未来注册完成，则使用 whenDefined，并把它和脚本加载的失败分支配合起来。

小结

把“元素已在 DOM 中”“元素已注册”“组件已完成连接”看成三个阶段，先后顺序就清楚了。customElements.define负责注册并触发已有节点升级，whenDefined负责等待注册承诺，动态导入的错误处理则负责给用户一条可恢复路径。