customElements.whenDefined 怎么等待一组组件升级后再移除占位

页面先输出一层统一占位内容，再异步注册多个 Web Components，是比较常见的渐进式加载方式。真正容易出错的地方不是调用一次 customElements.whenDefined()，而是同一容器里可能有多个标签、同名标签重复出现，甚至没有任何待升级元素。稳妥的做法是只收集容器内尚未定义的自定义元素，按 localName 去重，用 Promise.all() 等全部注册完成后再移除占位层。

官方参考地址：https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined

先把等待对象限定在占位容器

不要直接把页面上所有自定义元素都拿来等待。占位层只服务于一个容器，因此应从这个容器开始查询。:not(:defined) 能筛出尚未完成自定义元素升级的节点，但结果中也可能包含普通元素，所以后面要根据 localName 是否包含连字符来确认它是合法的自定义元素名。

正在加载组件…
  

这里有两个 user-card，但真正需要等待的是“标签名是否已注册”，不是每个节点各自创建一个等待任务。这样既能表达页面边界，也能避免组件数量增长时无意义地扩大 Promise 数量。

用 Set 去重，再用 Promise.all 等待注册

等待函数可以封装成一个只接收容器和占位节点的异步函数。先把待升级节点映射为 localName，再用 Set 去重；如果集合为空，说明组件已经全部注册，函数可以直接移除占位。若集合非空，则把每个标签交给 customElements.whenDefined()，最后由 Promise.all() 汇总。

// 等待容器内的自定义元素完成注册，然后清理统一占位层
async function removePlaceholderAfterUpgrade(container) {
  const placeholder = container.querySelector('.dashboard-placeholder');
  if (!placeholder) return;

  // 只取尚未定义且确实是自定义元素名的节点
  const pendingTags = new Set(
    [...container.querySelectorAll(':not(:defined)')]
      .map((element) => element.localName)
      .filter((name) => name.includes('-')),
  );

  // 同名标签只等待一次；空集合会让 Promise.all 立即完成
  await Promise.all(
    [...pendingTags].map((tagName) => customElements.whenDefined(tagName)),
  );

  // 异步等待期间节点可能被路由切换移除，先确认仍属于当前容器
  if (placeholder.isConnected && placeholder.parentElement === container) {
    placeholder.remove();
  }
}

const shell = document.querySelector('#dashboard-shell');
if (shell) {
  removePlaceholderAfterUpgrade(shell).catch((error) => {
    // 记录非法标签名等异常，但不阻塞页面其他交互
    console.error('自定义元素升级等待失败', error);
  });
}

whenDefined() 返回的 Promise 在标签已经注册时会立即完成，所以这段代码既适合脚本先执行、组件后注册的场景，也适合组件已经被其他模块注册的场景。Promise.all() 的语义是全部成功才继续；某个标签名不合法或注册流程抛出异常时，应该让错误进入页面自己的降级策略，而不是假装占位已经可以安全移除。

占位移除时要留意三个边界

还要注意，元素“完成升级”只说明浏览器已经找到对应的构造函数并完成自定义元素注册。它不代表组件内部的 fetch()、图片解码、模板渲染或首屏数据已经结束。如果占位层必须等到数据就绪，应让组件派发明确的 ready 事件，或由页面组合一个额外的业务 Promise；不要把 whenDefined() 当成万能的渲染完成信号。

常见问题

为什么不直接对所有节点调用 whenDefined？

同名节点共享一次注册状态，按标签名去重更清晰；直接逐节点等待会制造重复 Promise，也掩盖了“注册按名称发生”的事实。

whenDefined 能等待 Shadow DOM 内容出现吗？

不能。它只等待自定义元素名称被定义。Shadow DOM 内部模板、异步数据和图片状态需要组件自己提供 ready 事件或其他明确协议。

占位层已经被路由切换删除还要处理吗？

要处理，但删除前先检查节点仍连接到当前容器。这样旧页面的异步回调不会误操作新页面，也不会因为重复删除制造无意义异常。

这套写法的核心是把“等待哪些标签”和“组件何时真正可用”拆成两个协议：前者由 whenDefined() 与 Promise.all() 完成，后者交给组件自己的业务状态。占位清理因此可预测，边界也更容易测试。