customElements.define报错“name must contain a hyphen”是因为浏览器强制要求自定义元素名必须含至少一个短横线（-），如my-button✅，而mybutton、MyButton、-toggle❌均非法，这是为避免与未来HTML原生标签冲突的硬性语法校验。
customElements.define 为什么总报错“name must contain a hyphen”
这不是浏览器故意刁难，而是硬性语法校验——所有自定义元素名必须含且仅含一个或多个短横线（-），且不能在开头或结尾。写成 mybutton、MyButton、-toggle 或 toggle- 全部非法。
常见踩坑点：
-
data-table合法，datatable直接抛DOMException: The element name must contain a hyphen - 大小写不敏感，但惯例全小写 + 连字符：
ds-input✅，DS-Input❌（虽不报错，但破坏一致性） - 注册前务必加守卫：
if (!customElements.get('ds-input')) { customElements.define('ds-input', DSInput); }，否则热重载或多次加载时直接中断脚本
attributeChangedCallback 为何不触发？检查这三处
这个回调不是“监听所有属性变化”的万能钩子，它只响应你显式声明 + HTML 层变更的组合。JS 层直接赋值如 el.disabled = true 完全无效。
必须确认：
立即学习“前端免费学习笔记（深入）”；
-
static get observedAttributes()返回的是字符串数组，比如return ['disabled', 'value', 'loading']，漏写value就收不到它的变更 - 属性名严格匹配：写成
'Disabled'或'data-value'都不会触发 - 初始 HTML 中的属性会触发一次回调，但
oldValue是null，别写oldValue === null判断，用oldValue !== newValue更安全 - 布尔属性（如
checked）的newValue是字符串"true"或null，需手动转布尔：input.checked = newValue !== null
connectedCallback 是唯一安全的 DOM 操作入口
constructor 里调 this.shadowRoot.querySelector 必然返回 null —— 此时 shadowRoot 虽已 attach，但内部结构还没渲染完；disconnectedCallback 里操作节点则可能已移除。
所有真实 DOM 绑定必须放在这里：
- 事件监听器统一在
connectedCallback中绑定，比如this.shadowRoot.querySelector('button').addEventListener('click', ...) - 若需支持外部 JS 调用方法（如
el.reset()），该方法体内不能依赖shadowRoot，除非先判空：if (this.shadowRoot) { ... } - 避免在
connectedCallback里重复初始化（如多次 append 子节点），加标记位或用!this._initialized控制
Shadow DOM 的样式穿透和变量传递怎么破
你在 :root 定义的 --primary-color 在 shadowRoot 内部用 var(--primary-color) 不生效，不是 bug，是设计——Shadow DOM 天然是样式边界。
可行解法只有两个：
- 显式透传：父级通过
style属性或 CSS 自定义属性注入，组件内用:host { --primary-color: var(--primary-color, #007bff); }接收并向下传递 - 放弃穿透幻想，把主题色作为属性传入：
<ds-button primary-color="#0056b3"></ds-button>，然后在attributeChangedCallback里动态更新style标签 - 绝对不要在 shadowRoot 内写
body * { ... }或全局选择器，它只作用于影子树内部，且极易被误用导致性能问题
真正健壮的 UI 框架，不是靠堆功能，而是靠守住这些边界：命名不越界、属性变更不幻觉、DOM 操作不抢跑、样式不越权。剩下就是把每个组件的 observedAttributes 列表、formAssociated 开关、internals 桥接逻辑抠清楚——没捷径，但每一步都算数。
