customElements.define() 必须在 HTML 解析前同步执行，否则元素失活；observedAttributes 必须显式声明且严格匹配属性名；connectedCallback 仅首次挂载触发，滚动复用需手动重置；继承原生元素须调用 super() 且标签名必须含连字符。

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

customElements.define() 必须在 HTML 解析前执行，否则元素永远“失活” 浏览器解析 HTML 时遇到 这类标签，会立刻按 处理——它不会等 JS 加载完再决定是否“升级”。一旦错过时机，这个节点就再也收不到 connectedCallback、attributeChangedCallback，也不响应任何自定义行为。 常见错误现象：<ds-button></ds-button> 渲染出来就是个空壳，控制台没日志，点击无反应；Vite 动态导入的组件里调用 customElements.define()，首屏加载时元素不渲染。 实操建议：

• 所有 customElements.define() 必须收口到一个同步执行的入口文件（如 components/index.js），且通过 <script defer> 或模块顶层 import 加载
• 构建工具要确保自定义元素类不被拆进 import() 分支：Webpack 中可加 module.rules.exclude = /node_modules/；Vite 中避免在 defineAsyncComponent 或 dynamic import 内注册
• SSR 场景下必须包裹 if (typeof window !== 'undefined')，否则 Node.js 环境直接报 ReferenceError: customElements is not defined

attributeChangedCallback 不触发？先核对 observedAttributes attributeChangedCallback 不是通用监听器，它只响应你在 static get observedAttributes() 里**显式声明**的属性名，且大小写、连字符、拼写必须和 HTML 属性完全一致。 常见错误现象：写了 <ds-input data-value="abc">，但回调从不执行；改了 el.setAttribute('value', 'xyz')，却收到 name === 'data-value' 的回调——因为实际监听的是 'data-value'，不是 'value'。 实操建议：

• 静态 getter 必须返回字符串数组：static get observedAttributes() { return ['data-value', 'disabled']; }
• 属性名严格匹配 HTML 写法：data-user-id → 监听 'data-user-id'，不是 'userId' 或 'user-id'
• 首次挂载时需手动读取初始值：this.getAttribute('data-value') 放在 connectedCallback 或 constructor（注意：constructor 中不能操作 DOM）
• property 和 attribute 同步需手动维护：在 setter 里调用 this.setAttribute('data-value', val)

connectedCallback 只触发一次，滚动列表里别指望它“重活” connectedCallback 仅在元素**首次真正挂载到主 DOM 树**时运行。虚拟滚动、无限加载、Tab 切换后重新显示——这些场景下元素可能被反复移入移出，但 connectedCallback 不会重复执行。 常见错误现象：列表项用了 <product-card>，滚动到底部新卡片加载出来，但样式错乱、事件没绑定、数据没初始化。 实操建议：

• 把初始化逻辑（事件绑定、数据获取、DOM 操作）放在 connectedCallback，但不要假设它每次都会调用
• 滚动/复用场景需主动池化或状态重置：比如在 disconnectedCallback 里清理定时器、取消请求，但别全信它一定触发——得加双保险（例如结合 IntersectionObserver 或手动 reset 方法）
• 避免在 constructor 中操作 DOM：此时元素尚未插入文档，this.shadowRoot 可能为 null，this.innerHTML 会被后续挂载覆盖

extends='button' 类型的自定义元素，super() 和 is 属性容易踩坑 继承原生元素（如 HTMLButtonElement）时，constructor 必须调用 super()，否则原生语义、表单提交、键盘焦点等行为全部丢失；而使用 is 属性（如 <button is="loading-button">）在 IE 中完全不支持，现代项目若需兼容旧环境，只能退回到 autonomous 元素 + 手动模拟语义。 常见错误现象：自定义按钮无法回车触发、不能被 form 自动收集、tabindex 失效；<button is="loading-button"> 在 Safari 或旧版 Chrome 中直接报错或无反应。 实操建议：

• 继承类必须调用 super()，且不能在 constructor 中操作 DOM（包括 this.attachShadow()）
• 交互逻辑统一放 connectedCallback，比如 this.addEventListener('click', ...)
• 自定义标签名必须含连字符：my-button 合法，mybutton 或 MyButton 会直接报错 Failed to execute 'define' on 'CustomElementRegistry': The name must contain a dash.
• 如需语义兼容性，优先用 autonomous 元素（如 <loading-button>），再通过 ARIA 属性补足角色与状态

关键点不在“能不能写”，而在“什么时候生效、谁来触发、谁来兜底”。很多 bug 表面是回调没跑，根源其实是注册时机错了、属性名写串了、或者以为 connectedCallback 是“每次挂载都触发”的误解。真实产品里，最常被忽略的是 disconnectedCallback 的不可靠性——它可能根本不会被调用，所以清理逻辑必须有 fallback。