customElements.define 必须在首次渲染前执行，否则未注册标签会被当作 HTMLUnknownElement，导致生命周期钩子不触发、事件失效、Shadow DOM 不挂载；推荐在应用入口同步注册并避免 tree-shaking。
customElements.define 必须在首次渲染前执行
浏览器遇到未注册的自定义标签（如 <ds-button>）时，会当作 HTMLUnknownElement 渲染，此时生命周期钩子不会触发，事件监听失效，Shadow DOM 也不会挂载——所有功能直接降级为静态 HTML。
常见错误是把注册逻辑写在某个组件的 mounted 或 useEffect 里，等页面 DOM 已经解析完毕才注册，导致首屏元素无法响应。
- 推荐做法：在应用入口最顶部（如
main.js或index.html的<script>标签内）同步执行所有customElements.define() - 若用模块打包，确保注册代码不被 tree-shaking 掉；可显式导出一个
initCustomElements()函数并在入口调用 - 检查是否生效：打开 DevTools → Elements 面板，右键目标节点 → “Reveal in Elements panel”，看其 constructor 是否为对应类名，而非
HTMLUnknownElement
属性传参只接受字符串和布尔值
自定义元素的 attributeChangedCallback 只能捕获字符串或布尔属性变更。传对象、数组或函数会导致 SSR 渲染失败、服务端直出为空，且属性值序列化后丢失类型信息。
比如 <ds-table config='{"page":1}'> 是合法的，但 config={ { page: 1 } } 在 JSX 中会被 React 当作 prop 透传，绕过 attribute 机制，导致 attributeChangedCallback 不触发。
立即学习“前端免费学习笔记（深入）”；
- 复杂配置统一走
data-前缀或显式 JSON 字符串：<ds-table data-config='{"page":1,"size":20}'>，然后在类中JSON.parse(this.getAttribute('data-config')) - 布尔属性（如
disabled）注意判断：newValue !== null才代表 true，null表示移除，不能直接用!!newValue - 避免在构造函数里读取
this.getAttribute()—— 此时属性尚未初始化，应统一在connectedCallback或attributeChangedCallback中处理
Shadow DOM 封装与样式穿透的边界控制
Shadow DOM 是隔离样式的核心，但团队协作中最常出问题的是“该穿透时不穿透，不该穿透时乱穿透”。比如外部想改按钮背景色，却因没预留 CSS 自定义属性而只能 fork 源码。
真正可控的定制方式只有两种：CSS 自定义属性 + ::slotted，其他选择器（如 :host > button）一旦嵌套层级变化就失效。
- 必须在
:host中暴露高频变量，例如：:host { --ds-button-bg: #007bff; --ds-button-color: white; } -
::slotted(*)只用于控制插槽内容样式，不要在里面写业务逻辑样式；子元素样式一律写在 shadow 内部，禁止用:host ::slotted(.icon)这类深层穿透 - 关闭模式（
{ mode: 'closed' }）会让shadowRoot不可访问，调试困难；企业项目建议统一用open，靠文档约束而非技术封锁
与 Vue/React 等框架共存时的事件通信陷阱
自定义元素发出的 CustomEvent 在 Vue 中默认不会自动绑定到 @click 这类简写语法上，React 更不会将 onchange 映射到 change 事件——它们只认标准 DOM 事件。
比如 <ds-select @change="handle"> 在 Vue 中收不到事件，因为 ds-select 发的是 select-change，不是原生 change。
- 事件名必须用 kebab-case（短横线分隔），且避开原生事件名（如
click、input），推荐统一前缀：ds-change、ds-submit - Vue 用户需手动绑定：
<ds-select @ds-change="handle">；React 用户用onDsChange（注意大小写转换规则） - 需要双向绑定时，不要依赖
v-model自动推导，明确用:value.sync或onDsChange+valueprop 控制
attributeChangedCallback，所有页面里的 <ds-input> 都会同步响应；漏写一个 static get observedAttributes()，下游连调试都找不到入口。 
