构建基于自定义元素的ui库，核心是统一命名规则、属性接口、事件命名和shadow dom策略四点契约；需用customelements.get()守卫避免重复注册；attributechangedcallback仅响应html属性变更；shadow dom必须用open模式；避开extends内置扩展兼容性陷阱；契约对齐比组件实现更重要。
直接说结论：构建基于自定义元素的 UI 库，核心不是写多少组件，而是统一契约——命名规则、属性接口、事件命名、Shadow DOM 使用策略这四点没对齐，my-button 和 cool-toggle 就永远没法在一个项目里被当“一套”用。
customElements.define() 的注册守卫必须加
浏览器不允许多次注册同名元素，否则抛出 DOMException: Failed to execute 'define' on 'CustomElementRegistry': the name "x-input" has already been used。开发环境热重载、测试多轮执行、微前端多模块共存时极易触发。
- 每次注册前先查
customElements.get('x-input')，返回非null就跳过 - 不要在模块顶层无条件调用
customElements.define()，封装成函数并由使用者显式触发更安全 - 如果用 ES Modules 动态导入，需确保同一模块不会被重复
import两次（注意 bundler 的 tree-shaking 行为）
attributeChangedCallback 只响应 HTML 属性变更
这是最容易误判的点：el.checked = true 不会触发 attributeChangedCallback，只有 el.setAttribute('checked', '') 或初始 HTML 中的 <x-toggle checked></x-toggle> 才会。想做到 JS 属性与 HTML 属性同步，得自己补逻辑。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 在
static get observedAttributes()中显式列出要监听的属性，漏写=收不到回调 -
oldValue在首次初始化时是null，别直接===判断；newValue总是字符串，布尔属性如disabled传null表示移除，传空字符串或"true"都算存在 - 需要双向同步时，在 setter 中手动调用
this.setAttribute()，例如：set disabled(v) { this.toggleAttribute('disabled', v); }
Shadow DOM mode 必须选 'open'，且不能省略
用 this.attachShadow({ mode: 'closed' }) 看似更“隔离”，但实际会让调试、自动化测试、甚至父组件通过 querySelector 访问内部节点完全失效——这不是安全，是自废武功。
- 一律用
{ mode: 'open' }，这是可维护性的底线 - 不要在
constructor外调用attachShadow，否则可能被多次执行（比如被继承类反复调用） - Shadow DOM 内部样式必须写在
<style></style>标签里，外部 CSS 无法穿透；若需主题变量，得靠 CSS 自定义属性 +:host传递
自定义内置元素（extends）的兼容性陷阱
像 customElements.define('my-button', MyButton, { extends: 'button' }) 这种写法，虽然能复用原生语义和表单行为，但 Safari 直到 2026 年 6 月仍不支持 { extends } 参数（仅支持 is="" 语法，且需配合 <button is="my-button"></button>），Chrome 和 Firefox 支持良好。
- 除非明确只跑在 Chrome/Firefox 环境，否则避开
extends选项，改用独立自定义元素（如<my-button></my-button>）更稳妥 - 若坚持用内置扩展，必须提供降级 fallback：检测
customElements.get('my-button')是否为undefined，再动态替换为普通<button></button>并迁移事件绑定 - 所有依赖表单提交、焦点管理、无障碍属性（
aria-）的行为，都要在独立元素中手动实现，不能假设浏览器自动继承
真正卡住团队落地的，从来不是“怎么写一个按钮”，而是“所有人对 disabled 是布尔属性还是字符串、change 事件是否带 detail、插槽命名用 slot="icon" 还是 slot="prefix" 达成一致”。契约比代码更难对齐，也更值得花时间写进 README 和 CI 检查里。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
