HTML自定义元素开发流程：从设计到发布

自定义元素要绕过框架直接运行，原生 Web Components 确实可以做到。但在开发过程中最常出现的问题——注册失败、属性不响应、样式失效——基本都集中在三个关键环节：constructor 里 attachShadow 的时机、observedAttributes 的声明、标签名的连字符规则。这三个问题不解决，后续逻辑再完善也无法正常运行。

以下逐一详细说明。

constructor 必须调用 attachShadow()，否则报错：Failed to execute 'attachShadow' on 'Element'

浏览器规范明确规定：this.attachShadow() 只能在 constructor 中首次调用。如果在 connectedCallback 中才执行，HTML 解析器早已将子节点（例如文本、）放入 light DOM，此时再调用 attachShadow 会违反规范，导致报错。

• constructor 中只应执行三件事：调用 super()、执行 this.attachShadow({ mode: 'open' })、初始化私有字段或默认属性。
• 不要在 constructor 中读取 this.textContent 或写入 this.innerHTML = ''——前者返回空值，后者会污染 light DOM。
• 所有需要访问子节点、计算尺寸、触发重排的操作，都应放在 connectedCallback 中执行。

attributeChangedCallback 不触发？先检查 static get observedAttributes()

HTML 属性的变化并不会自动同步到 JS 属性，也不会触发重绘。即便写了 this.size = newValue，如果类中没有声明 static get observedAttributes() 并返回 ['size']，回调依然不会执行——这个错误非常隐蔽。

• 拼写必须完全一致：'disabled' 与 'Disabled' 不同，大小写敏感。
• 首次渲染时已有的属性（例如 ），attributeChangedCallback 不会触发——需要在 connectedCallback 中手动同步一次。
• oldValue 和 newValue 始终为字符串类型，数值型需要手动转换：parseInt(newValue) 或 parseFloat(newValue)。

样式必须注入 shadowRoot，外部 CSS 对 shadow 内部无效

Shadow DOM 天然隔离样式， 或全局的 button { background: blue } 对 shadow 内部没有影响。

• 可行方案：直接使用 注入到 shadow，例如 shadow.innerHTML = 'OK'。
• 或者创建 style 元素并 append：const style = document.createElement('style'); style.textContent = '...'; shadow.appendChild(style);。
• 如需外部控制主题色，可以使用 CSS 自定义属性：:host([theme="dark"]) { --bg-color: #333; }，然后在 shadow 内部使用 var(--bg-color)。

customElements.define() 报 DOMException？检查标签名是否包含且仅包含一个连字符

customElements.define() 对标签名有硬性要求：必须包含且仅包含一个连字符（-），不能以数字开头，也不能是保留字（例如 html、script、div）。

• my-button 合法（小写、含单个连字符、非保留名）。
• my_button 下划线不被识别。
• mybutton 或 MyButton 都会抛出 DOMException: Failed to execute 'define' on 'CustomElementRegistry': "mybutton" is not a valid custom element name。
• x-button 可用，但建议使用语义化名称，例如 date-picker、nav-menu。

最容易忽略的其实是初始属性同步和连字符命名——前者导致“HTML 中写了 value=123，JS 中却读不到”，后者直接让组件注册失败，连报错信息都看不到。只有这两个问题不卡住，其他逻辑才能正常执行。