HTML组件可维护性瓶颈在于变更影响不可追溯，需用data-module与data-version固化DOM层契约；Custom Elements应将初始化收束至constructor和connectedCallback；模板必须用<template>而非display:none的div；语义化标签是无障碍与JS查询的双重契约。
HTML组件的可维护性瓶颈，从来不在标签怎么写，而在于“谁改了哪部分、改了之后谁会崩”这件事没人能立刻说清。真正的抽象，不是把代码藏得更深，而是让边界更硬、契约更明。
data-module + data-version 是最轻量但最有效的接口声明
别指望靠文件名或目录结构来约束协作——人在改代码时根本不会打开文件树确认路径。必须把模块身份固化在 DOM 层：
-
data-module值要全局唯一且语义明确，比如data-module="product-card"，不能是data-module="card"（冲突风险高） -
data-version必须随每次破坏性变更递增，比如从"1.3"升到"2.0"，CI 流程里可校验该值是否匹配文档中的接口契约 - JS 查找时用
document.querySelectorAll('[data-module="product-card"][data-version="2.0"]')，比靠类名或层级健壮得多 - 设计师或外包改 HTML 时，只要不碰带
data-module的根元素，就不会误伤逻辑锚点
自定义元素（Custom Elements）不是万能，但 constructor + connectedCallback 是接口落地的关键时刻
Web Components 真正的价值，不是让你多写一个 <product-card> 标签，而是把“组件初始化”的责任从散落的 JS 文件收束到一个明确定义的入口：
-
constructor()里只能做最小初始化：创建 Shadow Root、设置innerHTML或克隆<template>，**禁止发请求、绑事件、读 DOM 尺寸** -
connectedCallback()才是真正“挂载完成”的信号，此时才能安全执行fetch()、addEventListener()、getBoundingClientRect() - 如果组件依赖外部数据，**不要在
connectedCallback里硬编码 URL**，而是通过attributeChangedCallback()监听data-api-endpoint这类属性变化 - 避免在
connectedCallback中直接操作全局 CSS 变量——Shadow DOM 隔离后它不生效；改用this.shadowRoot.querySelector('slot').style.setProperty('--color', value)
HTML 模板复用必须走 <template>，而不是 display:none 的 div
用 <div style="display:none"> 包模板看似简单，实则埋雷：
立即学习“前端免费学习笔记（深入）”；
- 它参与样式计算和布局，哪怕不可见，也会触发重排（reflow），尤其在含复杂 CSS 的页面中影响性能
-
innerHTML读取时会包含所有已解析的子节点，如果模板里有<script>或<style>，它们可能已被浏览器执行或加载，导致重复执行或 404 -
<template>是浏览器原生的惰性容器：内容不渲染、不解析脚本、不加载资源、不触发事件，JS 用content.cloneNode(true)取出时才是干净原始状态 - 务必给
<template>加id或data-template-for="product-card"，否则多人协作时容易出现“这个 template 到底是谁在用”的混乱
语义化标签不是装饰，是无障碍树与 JS 查询的双重契约
用 <nav> 替代 <div class="nav"> 的意义，远不止于“看起来更规范”：
- 屏幕阅读器会自动将
<nav>识别为 navigation region，而class="nav"对辅助技术完全透明 -
document.querySelector('nav')比document.querySelector('.nav')更稳定——类名可能被 CSS-in-JS 动态覆盖或 BEM 命名变更，标签名不会 -
<main>在同一页面中必须唯一，浏览器会据此优化焦点管理与历史滚动恢复，JS 也可用document.querySelector('main')安全定位主体内容区 - 嵌套结构如
<article> <section> <header>不仅利于 SEO，还让element.closest('article')这类向上查找逻辑更可靠，减少对脆弱层级计数的依赖
最难的部分不是写对第一个 customElements.define()，而是让所有人——包括没碰过 JS 的设计师、刚入职的实习生、甚至未来三年后的自己——在修改任意一行 HTML 时，都能一眼判断：“这段能不能动？动了会影响谁？” 接口不是写给机器看的，是写给人看的约束。一旦松动，模块化就退化成一堆带注释的 div。
