HTML自定义元素开发：构建可复用的功能模块-html教程-PHP中文网

customelements.define() 必须在 dom 就绪后调用且标签名含短横线，否则静默失败或抛 domexception；类须继承 htmlelement 并调用 super()；connectedcallback 是安全操作 dom 的唯一时机；slot 需 light dom 子节点透传且 shadowroot 不能为 closed 模式。

html自定义元素开发：构建可复用的功能模块

customElements.define() 必须在 DOM 就绪后调用，否则注册失败；自定义标签名必须含短横线（如 my-card），否则抛出 DOMException: The name "mycard" is not a valid custom element name。

为什么 `customElements.define()` 会静默失效或报错

常见现象是写了 customElements.define('my-button', MyButton)，但页面里用 <my-button></my-button> 完全没渲染，控制台也无报错——实际是注册时机错了。

在中立即执行，DOM 还未解析，document 处于不完整状态，注册会被忽略或失败
重复注册同一名字（比如多次加载同一组件脚本），触发 DOMException: the name "my-button" has already been used
类未继承 HTMLElement，或继承了但没调用 super()，导致实例化时崩溃，注册看似成功实则无效
标签名不含短横线（如 mybutton 或 MyButton），浏览器直接拒绝注册，不是警告而是硬性拦截

`connectedCallback` 不执行？检查是否漏了生命周期前提

很多开发者把逻辑全塞进 constructor，结果发现样式没生效、slot 不渲染、事件监听器没绑上——因为 connectedCallback 才是元素真正挂载到 DOM 的入口点。

Wechat Article Html

将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 HTML，微信编辑器可直接渲染，无需额外适配。支持标题、段落、列表、粗体、行内代码、表格、引用块、代码块、配图的完整转换。

下载

constructor 只负责初始化实例和创建 shadowRoot，此时元素尚未插入文档，this.querySelector 返回 null
connectedCallback 是唯一能安全操作 DOM、绑定事件、读取子元素或外部属性的地方
如果组件被 display: none 或 hidden 属性包裹，它仍会触发 connectedCallback；但移出视口不影响，只要在 DOM 树中就算“已连接”
注意：该钩子可能被多次调用（如元素被移除又重新 append），所以内部逻辑需幂等，避免重复 append 同一节点或监听器

Shadow DOM 内部的 `<slot></slot>` 为什么不显示内容

写了 this.shadowRoot.innerHTML = '<div><slot></slot></div>'，但 HTML 中写 <my-card>Hello</my-card> 却什么也不显示——根本原因是没启用插槽分发机制。

<slot></slot> 不是占位符，它是内容分发出口，但前提是：父级元素（即自定义元素自身）必须允许内容透传；若用了 innerHTML 赋值却没保留原始子节点，内容就丢了
正确做法是在 connectedCallback 中显式调用 this.appendChild(this.shadowRoot.querySelector('slot').parentNode)？不对——更简单：别清空元素内容，用 shadowRoot 承载样式和结构，让 <slot></slot> 自动接收 light DOM 子节点
如果用了 mode: 'closed'，shadowRoot 为 null，<slot></slot> 根本无法工作，且调试时 DevTools 看不到内部结构
命名插槽（如 <slot name="header"></slot>）必须匹配外部 <div slot="header">...</div>，大小写敏感，slot="Header" 不会命中

如何让自定义元素真正参与表单提交

很多 <my-input></my-input> 组件看着像输入框，但放在 <form></form> 里 submit 时拿不到值——这不是样式问题，是没接入表单基础设施。

必须在类定义中声明 formAssociated: true，否则 this.attachInternals() 会报错
this.internals = this.attachInternals() 要在 constructor 中调用，不能拖到 connectedCallback
值同步不能靠 this.value = ...，而要调用 this.internals.setFormValue(...)，否则 form.elements 和 FormData 都无法捕获
验证状态（如 setValidity）、自定义错误消息、重置行为都需要通过 this.internals 控制，直接操作子 <input> 不会影响表单校验链

最容易被忽略的是：自定义表单元素的 name 属性不会自动透传给内部 <input>，必须手动同步；还有 Safari 对 attachInternals() 的支持虽已稳定，但某些旧版 iOS WebKit 仍存在 setFormValue 延迟触发的问题，建议加一层防抖或事件队列兜底。