Web Components 是唯一真正跨框架复用的原生方案，依托浏览器原生支持的 Custom Elements 和 Shadow DOM，无需构建工具或框架绑定，可在 React、Vue、Svelte 及纯 HTML 中直接使用；其核心在于组件注册后标签即被解析实例化，且必须用短横线命名、在 connectedCallback 中处理逻辑、显式声明 observedAttributes 响应属性变化。
Web Components 是唯一能真正跨框架复用的原生方案
浏览器原生支持的 Custom Elements + Shadow DOM 是目前唯一不依赖构建工具、不绑定特定框架、且能在 React/Vue/Svelte 甚至纯 HTML 页面中直接使用的组件化机制。它不是“模拟组件”，而是被规范定义、被所有现代浏览器稳定实现的标准能力。关键在于：组件注册后，my-button 这类标签在任何上下文里都会被解析并实例化，无论宿主页面用不用框架。
常见错误现象：
- 把
<my-card></my-card>直接写进 HTML 却没调用customElements.define()—— 浏览器当普通未知标签忽略，DOM 中存在但无行为 - 在 Shadow DOM 内部硬编码样式却忘了用
adoptedStyleSheets或动态插入<style></style>—— 样式不生效，组件看起来是空的 - 组件名不含短横线（如
button或MyButton）——customElements.define()抛出DOMException: Failed to execute 'define' on 'CustomElementRegistry'
实操建议：
- 必须用短横线命名：
nav-bar✅，navbar❌，NavBar❌ - 构造函数里只能做初始化，不能异步 fetch 或 await —— 后续逻辑放
connectedCallback中 - 若需响应属性变更，必须显式声明
observedAttributes并实现attributeChangedCallback - 想让全局 CSS 能穿透进 Shadow DOM？设
attachShadow({ mode: 'open' })，别用'closed'
React/Vue/Svelte 中复用 Web Components 的坑 框架对自定义元素的支持程度不同，但都允许直接使用，只是数据流和事件处理方式要适配。
使用场景中要注意：
- React 里传布尔属性要用
disabled={true}，不能写disabled（否则值为字符串"disabled"） - Vue 模板中绑定事件要用
@click.native（Vue 3 中可省略 .native，但 Vue 2 必须加） - Svelte 中监听自定义事件需用
on:custom-event，而非on:click（后者只捕获原生事件）
参数差异：
立即学习“前端免费学习笔记（深入）”；
- Web Components 接收属性靠
getAttribute()，所以传数字/对象必须序列化：<my-chart data='{"series": [1,2,3]}'></my-chart> - 框架组件传 props 是 JS 值，Web Components 只能拿到字符串，需要手动
JSON.parse()或类型转换 -
slot内容在框架中会被当作子节点透传，但若框架做了 Fragment 优化（如 React 18 的Fragment），可能破坏 slot 分发结构
不要用 iframe 实现“跨框架组件”iframe 看似隔离、看似独立，但它不是组件化，而是进程级隔离。它带来的是不可逾越的边界：样式无法继承、事件无法冒泡、JS 上下文完全割裂、SEO 几乎失效、滚动行为错位、无障碍支持断裂。
常见错误现象：
- 用
iframe src="header.html"替代页头复用 —— 搜索引擎爬虫看不到内容，屏幕阅读器无法连贯读取 - 在 iframe 内嵌 React 组件，再试图从父页面调用其方法 —— 需要 postMessage + 跨源策略配置，复杂度指数上升
- 把整个
nav-bar包进 iframe，结果移动端点击区域失效或缩放异常
性能与兼容性影响：
- 每个
iframe启动独立渲染进程，内存占用翻倍，低端设备卡顿明显 - iOS Safari 对 iframe 内滚动有特殊限制，常导致 touchmove 失效
-
iframe加载完成时间不可控，父页面无法准确判断“组件已就绪”
构建时预处理仅适用于静态站点
像 posthtml-include 或 html-loader 这类工具，是在打包阶段把 header.html 插入到每个页面里，最终输出的是纯 HTML。它解决了“写一次、多处用”的问题，但本质仍是静态拼接，没有运行时封装能力。
容易踩的坑：
- 开发时改了
header.html，但没触发重新构建 —— 浏览器缓存旧版本，本地看不到更新 - 使用相对路径引入片段：
<include src="./partial/footer.html"></include>，但构建工具未配置 base path，导致路径解析失败 - 某些预处理器不支持嵌套 include，三层以上复用会报错或静默忽略
适用边界很明确：
- 适合文档站、营销页、CMS 静态导出等无需交互的场景
- 不适合含状态、需响应用户操作、或依赖运行时数据注入的组件（比如带搜索框的导航栏）
- 无法解决样式泄漏问题 —— 所有片段共享全局 CSS，一个
.btn改了，全站按钮都变样
真正跨框架的组件化，核心不在“怎么塞进去”，而在“怎么隔离开”。Web Components 提供的是封装契约，而不是加载技巧。多数人卡在第一步：没意识到 customElements.define() 必须执行，且必须早于组件标签出现在 DOM 中 —— 这个时机问题，比语法细节更常导致组件白屏。
