自定义元素的可维护性取决于生命周期组织、接口声明和DOM契约约束；constructor仅用于初始化，禁止DOM操作；connectedCallback是挂载完成信号，适合发起请求、绑定事件、读取尺寸；data-module与data-version提供稳定DOM锚点；Shadow DOM需注意样式隔离与调试限制。
自定义元素本身不自动提升可维护性，它只是提供了一种封装机制；真正起作用的是你如何组织生命周期、声明接口、约束 DOM 契约。
constructor 里只能做初始化，别碰 DOM 或属性
很多组件一注册就报错或属性读不到，根源是把本该延迟的操作塞进了 constructor。这个函数只在元素实例化时同步执行，此时它还没插入 DOM，也没有 attribute 值可读——HTML 解析器还没把属性挂上去。
-
constructor中允许：super()、this.attachShadow({ mode: 'open' })、声明私有字段（如this._count = 0）、绑定方法（this.handleClick = this.handleClick.bind(this)） -
constructor中禁止：this.getAttribute('value')、this.innerHTML = '...'、this.querySelector、fetch()、任何依赖尺寸或父级的计算 - 初始属性值必须靠
connectedCallback+ 手动遍历this.attributes或用static get observedAttributes()配合attributeChangedCallback同步
connectedCallback 是“挂载完成”的唯一信号
这是组件真正可用的起点。只有这时，元素已插入文档流，所有 attribute 已就位，子节点可访问，样式已计算，DOM 尺寸可读取。
- 在这里发起数据请求（
fetch(this.getAttribute('data-api-endpoint'))） - 在这里绑定事件监听器（
this.shadowRoot.querySelector('button').addEventListener(...)） - 在这里读取布局信息（
this.getBoundingClientRect()） - 但注意：如果组件依赖外部状态（如主题色、语言），别硬编码逻辑，应监听
attributeChangedCallback或通过CustomEvent响应全局变化
data-module + data-version 比标签名更可靠
customElements.define('product-card', ProductCard) 注册成功不代表线上能稳定运行。多人协作中，HTML 被改、JS 被删、样式被覆盖，靠标签名定位极易失效。
立即学习“前端免费学习笔记（深入）”；
- 给自定义元素根节点加
data-module="product-card"和data-version="2.1"，作为 DOM 层契约锚点 - JS 查找统一用
document.querySelectorAll('[data-module="product-card"][data-version="2.1"]')，避免依赖类名或层级 - 设计师改 HTML 时只要不动带
data-module的外层容器，就不会破坏 JS 锚点 - CI 流程可校验
data-version是否与文档中接口定义一致，防止“文档写 2.0，线上跑 1.9”
Shadow DOM 隔离是双刃剑
它确实阻止样式污染，但也切断了你惯用的调试路径：全局 CSS 重置无效、父级选择器无法穿透、:host-context() 兼容性差、CSS 自定义属性需显式透传。
- 不要在 shadow 内写
body { color: red }——body不在 shadow 中，这条规则根本没作用 - 想让外部控制字体大小？在 host 上设
:host { --font-size: 1rem; }，内部用font-size: var(--font-size) - 想复用现有 CSS 工具类？得手动把
.btn-primary的关键声明复制进 shadow style，或用adoptedStyleSheets导入 - 调试时别只看 Elements 面板里的 shadow root，记得切换到 Styles 面板右上角的 “Show user agent shadow DOM” 查看原生行为
最难的不是写出一个能跑的 my-button，而是让团队所有人知道：改它的 HTML 结构要升 data-version，改它的属性接口要同步文档，改它的 shadow 内样式要验证无障碍对比度——可维护性藏在这些约定里，不在语法糖中。
