自定义元素必须处理命名、生命周期、属性同步、Shadow DOM隔离和表单集成五件事，缺一不可；customElements.define()要求类继承HTMLElement、标签含短横线、避免重复注册，且构造函数须调用super()。
自定义元素不是“加个标签就完事”，它要真正封装 UI，必须处理好命名、生命周期、属性同步、Shadow DOM 隔离和表单集成这五件事——漏掉任何一环，组件在真实项目里就会卡住或失效。
customElements.define() 的注册时机和类定义陷阱
注册失败最常见的原因是类没继承 HTMLElement，或者用错语法。浏览器会直接抛 DOMException: The element name must contain a hyphen 或 Failed to execute 'define' on 'CustomElementRegistry'。
-
customElements.define()第二个参数必须是 class，且显式extends HTMLElement；箭头函数、对象字面量、普通函数都不行 - 标签名必须含短横线，
my-button合法，mybutton或MyButton会报错 - 重复注册同一名字会报错，建议加守卫：
if (!customElements.get('my-input')) { customElements.define('my-input', MyInput); } - 构造函数里必须调用
super()，否则实例化失败，后续所有生命周期回调都不会触发
attributeChangedCallback 只监听 HTML 属性变更，不响应 JS 属性赋值
你写 el.checked = true，attributeChangedCallback 完全收不到；只有 el.setAttribute('checked', '') 或初始 HTML 里的 <my-toggle checked></my-toggle> 才触发。这是最常被误解的点。
- 必须在
static get observedAttributes()里显式声明要监听的属性，漏写就等于没监听 -
newValue总是字符串，布尔属性如disabled初始值可能是null，别直接=== 'true'判断 - JS 属性赋值（如
el.value = 'abc'）需要手动同步到内部控件，比如this._input.value = v - 初始 HTML 中的属性值会触发一次回调，但
oldValue是null，不能用于状态比对逻辑
Shadow DOM 模式选 open 还是 closed？调试优先选 open
开发阶段用 mode: 'open'，否则 Chrome DevTools 点不开 shadow root，根本没法查样式、断点或 inspect 元素。
立即学习“前端免费学习笔记（深入）”；
-
closed模式下this.shadowRoot返回null，外部 JS 无法访问，适合发布后防篡改，但极大增加调试成本 - 样式必须内联进 shadow root，
<style></style>是最稳方式；外部<link>不生效，adoptedStyleSheets兼容性差且难维护 - 想让字体、颜色等基础样式透入，靠浏览器默认继承机制就行；布局类属性（
margin、display）不会透入，需显式用:host控制 - 第三方库（如 Chart.js、Leaflet）多数不兼容 Shadow DOM 渲染，遇到 canvas 或 map 容器失败，优先考虑 light DOM + 命名空间 CSS
表单控件必须走 formAssociated: true + attachInternals() 路线
只渲染一个 <input> 在 Shadow DOM 里，<form> 提交时它的值根本不会被收集——因为浏览器不认识这个自定义标签参与表单。
- 必须设
static formAssociated = true，这是启用表单集成的开关，缺了就白搭 - 构造函数里调用
this.attachInternals()获取ElementInternals实例，否则setFormValue()会报错 - 要在
connectedCallback里监听子<input>的事件（如input、change），并调用this.internals.setFormValue()同步值 - 必须实现
formDisabledCallback和formResetCallback，否则fieldset[disabled]或form.reset()会失效
真正难的不是写出来，而是让自定义元素在表单里 behave like native、在无障碍工具里被正确识别、在无 JS 环境下 fallback 合理——这些细节藏在 formAssociated、internals 和原生语义桥接里，绕不开。
