Scoped Custom Element Registries 解决什么：组件注册范围与冲突边界

当页面同时装入两个 Web Components 组件库时，最容易遇到的不是样式覆盖，而是标签名已经被占用：组件库 A 和组件库 B 都想注册 ，第二次 define() 直接失败。Scoped Custom Element Registries 解决的正是这个边界问题：为不同组件子树提供独立的自定义元素命名空间。

如果多个团队需要在同一页面共存同名自定义元素，可以为每套组件创建独立的 CustomElementRegistry，再把它绑定到 ShadowRoot 或指定子树；它隔离的是元素定义，不是完整的 JavaScript、CSS 或安全沙箱。

本文要点：全局 window.customElements 只有一个共享注册表；新的注册表可以各自定义同名标签；采用时必须保留能力检测与降级路径。

为什么全局注册表会让组件互相撞名

传统写法把所有组件放进 window.customElements。这个注册表按标签名保存定义，因此下面两段来自不同库的代码并不能同时成立：

customElements.define('ui-card', CardFromLibraryA);
// 另一个库仍然使用同一个页面全局注册表
customElements.define('ui-card', CardFromLibraryB);
// Uncaught NotSupportedError: name has already been used

问题不在两个类是否实现相同，也不在它们来自哪个打包文件，而在定义集合共享了同一个名字。微前端、旧版组件与新版组件并行迁移时，如果只能改名，就会把内部标签、样式选择器和模板一起改动，成本很高。

Scoped Custom Element Registries 改变了什么

WHATWG HTML 标准为 CustomElementRegistry 增加了构造器。调用 new CustomElementRegistry() 会得到一个独立注册表，它有自己的定义集合，与全局注册表及其他 scoped 注册表分开。

这意味着“标签名唯一”从整张页面收窄为“在所属注册表内唯一”。同一个 ui-card 可以分别属于 A、B 两个注册表，浏览器在创建元素时根据它所属的文档、ShadowRoot 或元素子树查找定义。

这个能力适合解决组件组合和版本并行问题，但不能替代隔离运行环境：两个组件仍然可能通过事件、共享状态或宿主 API 互相影响；Shadow DOM 的样式封装也不等于脚本权限隔离。

把注册表绑定到 ShadowRoot：最小隔离写法

最清晰的落点是 ShadowRoot。每个组件宿主拥有自己的注册表，两个子树都可以使用 ，而不用抢占全局名字：

class CardA extends HTMLElement {
  connectedCallback() { this.textContent = '来自组件库 A'; }
}
class CardB extends HTMLElement {
  connectedCallback() { this.textContent = '来自组件库 B'; }
}

const registryA = new CustomElementRegistry();
registryA.define('ui-card', CardA);
const registryB = new CustomElementRegistry();
registryB.define('ui-card', CardB);

const shadowA = document.querySelector('#library-a').attachShadow({
  mode: 'open', customElementRegistry: registryA
});
const shadowB = document.querySelector('#library-b').attachShadow({
  mode: 'open', customElementRegistry: registryB
});
shadowA.innerHTML = '';
shadowB.innerHTML = '';

这里的关键不是变量名，而是 attachShadow() 的 customElementRegistry 选项。注册表与 ShadowRoot 建立绑定后，子树里的自定义元素按该注册表解析。两个 ui-card 可以拥有不同构造器，同时页面全局注册表不必知道它们。

元素级绑定与模板场景怎么选

除了 ShadowRoot，还可以把注册表直接交给一个元素：

const registry = new CustomElementRegistry();
registry.define('ui-badge', class extends HTMLElement {});

const subtree = document.createElement('section', {
  customElementRegistry: registry
});
subtree.innerHTML = '内部标签';
document.body.append(subtree);

元素级绑定适合动态创建、离屏拼装或需要整体搬移的组件子树。若使用声明式 Shadow DOM，模板可以声明 shadowrootcustomelementregistry，之后由对应注册表调用 initialize() 与这棵树建立关联。离屏文档也可以用同样的方式承载一套独立定义。

要注意绑定是长期边界：规范明确规定节点的注册表初始化后不能随意改换。不要先把一棵树交给全局注册表，再期待后续切换到 scoped 注册表能够重新解释已有标签。

兼容性与渐进采用清单

Interop 2026 已将 Scoped custom element registries 列为跨浏览器互操作改进方向；Chrome 与 Edge 146 起已默认提供该能力，但跨浏览器项目仍应把它当作需要检测的增强能力。上线前可按下面的策略落地：

1. 先检测 CustomElementRegistry 构造器，并在目标浏览器矩阵中确认 attachShadow 的注册表选项可用。
2. 支持 scoped 注册表时，让每个组件库在自己的 ShadowRoot 或元素子树内注册，保持内部标签名稳定。
3. 不支持时，使用带组织前缀的全局标签名，或继续由组件宿主统一协调全局注册，避免静默回退成两个不同实现。
4. 把注册表边界写进组件文档：哪些标签只在子树内解析、哪些公共元素仍使用全局定义，以及宿主如何传递事件和数据。

最小的能力检测可以作为入口保护：

const canScopeRegistry = typeof CustomElementRegistry === 'function';
if (canScopeRegistry) {
  // 创建并绑定独立注册表
} else {
  // 使用带前缀的全局 customElements 定义
}

这项能力真正带来的结果是“组件定义可以局部命名”。当需求只是解决同名冲突时，它比全量改名更平滑；当需求还包含脚本权限、网络访问或业务状态隔离时，仍要另选 iframe、进程级或应用架构层面的方案。

相关问题

Scoped Custom Element Registries 会自动隔离 CSS 吗？不会。注册表负责自定义元素定义的查找；CSS 是否封装取决于 Shadow DOM、样式策略和宿主页面的具体实现。

同名组件可以直接放在普通 light DOM 中吗？不能仅凭两个注册表就让普通 light DOM 自动拥有两套解析规则，必须把注册表绑定到支持该边界的 ShadowRoot、元素子树或文档。

它能解决两个版本组件库并行加载吗？可以解决标签定义的命名冲突，但共享事件、数据对象和宿主 API 的兼容性仍需组件团队自行约定。

参考：web.dev Interop 2026、WHATWG HTML Custom elements、Chrome for Developers：scoped registries。