customElements.whenDefined 传入无效标签名为什么直接报错

我在接入 Web Components 的占位菜单时，曾把接口返回的字符串直接传给 customElements.whenDefined()。只要字符串不是合法的自定义元素名，代码就会立刻抛出 SyntaxError，而不是返回一个“永远等不到”的 Promise。

原因很明确：whenDefined(name) 先检查 name 是否符合自定义元素名称规则。名称合法但还没有注册时，才会进入等待；名称已经注册时，返回的 Promise 会立即完成。

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

先把 SyntaxError 和“尚未注册”分开

这两个现象在日志里很容易被混为一谈。下面的调用使用了不带连字符的 menuitem，异常发生在调用表达式本身，后面的 .catch() 并不能把它当成一个普通的等待失败来处理。

try {
  // 这里的名称不符合自定义元素名称规则，会同步抛出 SyntaxError。
  const ready = customElements.whenDefined("menuitem");
  await ready;
} catch (error) {
  // 记录 name，便于区分名称错误和组件尚未注册。
  console.error("等待自定义元素失败", { name: "menuitem", error });
}

如果名称是合法的 menu-item，但页面暂时还没有调用 customElements.define()，则 whenDefined() 返回 Promise 并保持 pending，直到该名称被定义。也就是说，SyntaxError 说明输入契约不成立，不是注册时序慢。

自定义元素名为什么要有连字符

自定义元素不是随便给 HTML 标签换个名字。名称需要符合 HTML 自定义元素名称规则，最容易记住的实践约束是使用小写并包含连字符，例如 menu-item、user-card。连字符可以把应用自定义元素与现有 HTML 元素名称区分开。

因此，下面几类输入要谨慎处理：

这里的重点不是手写一套替代浏览器规范的正则，而是不要把未经约束的业务字段直接交给 API。最终的合法性仍由平台 API 判断。

把名称规范化放在等待函数之前

如果名称来自配置、服务端数据或组件清单，可以先做轻量的输入清理，再调用 whenDefined()。清理函数不负责猜测用户意图：发现缺少连字符时直接报错，比偷偷拼接一个连字符更容易定位问题。

function assertCustomElementName(value) {
  // 只去除首尾空白，不替换名称内部字符，避免掩盖配置错误。
  const name = String(value ?? "").trim();

  // 这是业务层的快速提示，最终规则仍交给 CustomElementRegistry。
  if (!name || !name.includes("-") || name !== name.toLowerCase()) {
    throw new TypeError(`非法自定义元素名: ${name || ""}`);
  }
  return name;
}

async function waitForElement(name) {
  // 先完成输入边界处理，再进入浏览器提供的定义等待。
  const validName = assertCustomElementName(name);
  return customElements.whenDefined(validName);
}

这段代码只做了适合业务配置的前置筛选：空值、大小写和连字符问题会更早暴露。它没有把筛选结果当成规范的完整实现，所以即使筛选通过，也要允许浏览器在 whenDefined() 内继续抛出标准异常。

注册域和等待域要使用同一个名称

customElements.define() 与 customElements.whenDefined() 必须围绕同一个规范化名称协作。注册时名称写成 user-card，等待时却从配置里取出 usercard，就不是“注册还没完成”，而是两套不同的名字。

class UserCard extends HTMLElement {
  connectedCallback() {
    // 用最小内容标记组件已接入，避免把示例写成完整 UI。
    this.textContent = "用户卡片已定义";
  }
}

// 注册名与等待名保持同一个常量，减少字符串漂移。
const elementName = "user-card";
customElements.define(elementName, UserCard);

async function revealMenu() {
  // 已定义的名称会让 Promise 很快完成；未定义则继续等待。
  await customElements.whenDefined(elementName);
  document.querySelector("[data-menu-placeholder]")?.remove();
}

按场景选择处理方式

在实际项目里，我会先判断输入来自哪里，再决定是否等待：

• 名称写死在组件代码中：直接复用常量，最少一层转换。
• 名称来自模板扫描：先用 :not(:defined) 找到未定义元素，再对去重后的 localName 调用 whenDefined()。
• 名称来自服务端或用户配置：先做空值、大小写和连字符等业务边界处理，再让平台 API 做最终判断。
• 名称不合法：保留原始值并返回配置错误，不要用重试掩盖 SyntaxError。

如果页面只是等待一组菜单子元素，可以使用 Promise 聚合，但前提仍是集合中的每个名称都合法：

async function waitForMenuParts(container) {
  // 去重 localName，避免同一种元素重复创建等待 Promise。
  const names = new Set(
    [...container.querySelectorAll(":not(:defined)")]
      .map((element) => element.localName),
  );

  // 合法名称等待定义；非法名称应在这里暴露为配置错误。
  await Promise.all([...names].map((name) => customElements.whenDefined(name)));
}

落地前的检查清单

1. 日志中是否记录了传入 whenDefined() 的原始名称？
2. 名称是否包含连字符，并且没有把原生标签名当作自定义元素名？
3. define() 与 whenDefined() 是否复用了同一个常量或同一个规范化结果？
4. 是否把非法输入当成配置错误，而不是无限重试或等待超时？
5. Promise 聚合前是否先完成名称去重和边界处理？

归根结底，customElements.whenDefined() 报 SyntaxError 时，应优先检查传入的标签名，而不是怀疑组件加载速度。合法名称对应的是注册时序问题；无效名称对应的是输入契约问题，修复位置也完全不同。

常见追问

whenDefined 会因为元素还没注册而抛 SyntaxError 吗？

不会。名称合法但未注册时，通常得到 pending Promise；名称不符合自定义元素命名规则时，才会因为输入非法抛出 SyntaxError。

已经 define 的元素还需要等待吗？

可以等待。对已经定义的名称，返回的 Promise 会立即完成，统一等待逻辑比在每个调用点重复查询注册表更简单。

能不能把缺少连字符的名字自动改成合法名字？

不建议。自动改名会让注册名、DOM 标签名和配置名产生漂移；更稳妥的做法是拒绝原始输入并给出具体配置错误。