直接写 <div class="header"> 会埋雷，因将样式契约硬编码进结构层，导致协作断点、语义缺失、复用受阻、构建工具失效；Web Components 通过 customElements.define() 和 Shadow DOM 实现真正解耦。
为什么直接写 <div class="header"> 会埋雷
这不是语法错误，而是协作断点。当你在 HTML 里写 class="header"，等于把样式契约硬编码进结构层——CSS 文件里改了 .header 的 padding，但某页漏加 class 或拼错成 class="hedear"，视觉就崩了；更糟的是，设计师想统一换字体，你得 grep 全项目找所有 class="header"，再逐个确认是否该被影响。
常见错误现象：class="btn-primary" 在登录页和支付页表现不一致，因为两处 CSS 来源不同（一个来自 layout.css，一个来自内联 <style>），优先级打架导致 hover 效果失效。
- 语义缺失：用
<div class="header">替代<header>，既无法被屏幕阅读器识别，也让 CSS 选择器失去上下文约束（比如header h1比.header h1更安全） - 复用受阻：组件被复制到新页面时，class 名可能冲突（
.modal被另一套框架覆盖），或遗漏依赖的 CSS 文件，直接白屏 - 构建工具失效：Vite 或 Webpack 的 CSS tree-shaking 只能处理 import 链路，对散落在 HTML 中的 class 名无能为力
customElements.define() 是唯一能切断 HTML/CSS 硬耦合的机制
别被“外部 CSS 文件”骗了——只要 HTML 还依赖 class 名去触发样式，耦合就没解除。customElements.define() 提供的是运行时边界：它让浏览器把 <my-header> 当作原生元素对待，内部 DOM 和样式自动隔离。
关键动作不是“注册”，而是必须搭配 attachShadow({ mode: "open" })。否则你写的 <my-header></my-header> 只是空标签，样式仍走全局流，document.querySelector(".logo") 还能轻易捅穿你的“封装”。
立即学习“前端免费学习笔记（深入）”；
- 名称必须含短横线（
"my-header"✅，"myheader"❌），否则浏览器拒绝注册 -
<template>内不能放<style>，要动态注入：const style = document.createElement("style"); style.textContent = "h1 { color: #333; }"; shadowRoot.appendChild(style); - 禁止用
data-*属性透传行为逻辑，比如<my-header data-theme="dark">—— 正确做法是监听attributeChangedCallback并声明observedAttributes = ["theme"]
用 adoptedStyleSheets 注入第三方 CSS 的坑
想在 Shadow DOM 里用 Bootstrap 或 Tailwind？别往 shadowRoot 里塞 <link rel="stylesheet">，它不会生效。浏览器限制外部样式表穿透 Shadow Boundary，且 <link> 加载是异步的，你 append 完可能样式还没加载完。
正确路径是：先 fetch 第三方 CSS 文本，再用 CSSStyleSheet 实例注入：
const sheet = new CSSStyleSheet();
await sheet.replace("/* 复制粘贴 bootstrap.min.css 内容 */");
shadowRoot.adoptedStyleSheets = [sheet];注意兼容性：adoptedStyleSheets 在 Safari 16.4+、Chrome 73+ 稳定支持，旧版 Safari 必须 fallback 到内联 <style> 字符串拼接。
- 不要动态向
document.head插入<link>—— 它污染全局，且多个组件同时加载会触发重复请求 - 第三方 CSS 里带
!important或高特异性选择器（如body .btn）会失效，因为 Shadow DOM 内部没有body上下文 - 若需响应式，用
@media写在注入的 CSS 字符串里，别指望外部媒体查询穿透
HTML 里还留着 onclick 或 style 属性？解耦已经失败
哪怕用了 Web Components，只要 HTML 里还出现 <button onclick="handleClick()"> 或 <div style="margin: 10px">，视图与逻辑的隔离就形同虚设。这些属性是 DOM 层面的硬引用，JS 可以随时通过 element.getAttribute("onclick") 扫描并篡改，等于留了后门。
真正隔离的组件，交互入口必须收口在类内部：
- 按钮创建后立即绑定：
const btn = this.shadowRoot.querySelector("button"); btn.addEventListener("click", () => this.emit("submit")); - 禁用状态走属性而非 class：
<my-form disabled>触发attributeChangedCallback，内部控制btn.disabled = true - 绝对不用
element.style.xxx = xxx，所有样式变更走 class 切换或 CSS 变量：this.shadowRoot.documentElement.style.setProperty("--bg-color", "#007bff")
最容易被忽略的点：slot 内容的样式控制权。一旦写了 ::slotted(*) { margin: 0; }，你就主动放弃了封装——父组件可以随便塞 <span slot="title" style="color:red">，直接绕过你的设计约束。
