自定义元素必须含短横线且经customelements.define()注册，否则仅为未知标签；如未注册或缺短横线，均无法生效。
自定义元素不是 class，别用错地方
很多人看到 custom-element 就想当然当成 CSS 类名或模板占位符来用，结果写成 <div class="my-button"> 还以为是“自定义元素”。真正在 HTML 中注册并生效的自定义元素，必须满足两个硬条件：名字里带短横线（<code>-），且已通过 customElements.define() 注册。没注册的 <user-card></user-card> 在 DOM 中只是个未知标签，浏览器会渲染但不识别语义，JS 也拿不到实例。
常见错误现象：
-
<search-input></search-input>写了但没调用customElements.define('search-input', ...)，控制台无报错但无法响应事件 - 用
<mybutton></mybutton>或<usercard></usercard>—— 缺少短横线，直接被浏览器忽略为非法名称 - 在未支持 Custom Elements v1 的旧版 Safari（
什么时候该用自定义元素，而不是语义化标签
自定义元素不是 <header></header> 或 <main></main> 的替代品，而是对「可复用、有行为、需封装」的 UI 单元做抽象。比如一个带搜索建议、防抖、清空按钮、状态反馈的输入框，用 <search-input></search-input> 就比套一堆 div + class="search-wrapper search-active has-suggestions" 更直白。
判断是否适合封装为自定义元素，看这三点：
- 是否在多个页面/模块中重复出现（如
<date-picker></date-picker>、<status-badge></status-badge>） - 是否包含内聚逻辑（如自动聚焦、键盘导航、本地存储偏好）
- 是否需要统一 API（
.value属性、change事件、disabled反应式控制）
反例：<section class="product-list"></section> 不该改成 <product-list></product-list> —— 它只是结构容器，没交互、无状态、不封装逻辑，强行自定义反而增加维护成本。
命名和属性设计直接影响可读性
自定义元素的标签名和属性名，是别人第一次看代码时理解它用途的唯一线索。起名不能只图自己爽，得让协作的人扫一眼就懂。
实操建议：
- 标签名用 kebab-case，表达「是什么」：
<notification-banner></notification-banner>✅，<blue-alert></blue-alert>❌（颜色会变，语义失效） - 布尔属性优先用原生语义：
disabled、required直接继承，不要造is-disabled - 数据属性用
data-前缀，避免和未来 HTML 标准冲突：data-api-endpoint✅，api-url❌ - 避免缩写：
<usr-prfl></usr-prfl>比<user-profile></user-profile>更难猜，且编辑器补全失效
一个典型例子：<loading-spinner size="large" delay="300" hidden></loading-spinner> —— 属性名直接暴露行为意图，比 <div class="spinner spinner--large spinner--delayed" aria-hidden="true"> 更易读、更可控。<h3>不注册、不升级、不注释 = 白写</h3>
<p>自定义元素一旦写进 HTML，就不再是“可选优化”，而是项目运行依赖的一部分。如果只在 JS 文件里写了 <code>customElements.define()，但没确保它在 <loading-spinner></loading-spinner> 被解析前执行，轻则元素空白，重则 JS 报 Custom element not defined 错误。
容易被忽略的关键点：
- 注册时机：必须在元素被 HTML 解析前完成，推荐放在
<script defer></script>或模块入口处，避免放在DOMContentLoaded后 - 降级处理：对不支持的浏览器，至少提供
document.createElement('loading-spinner').attachShadow失败时的 fallback 渲染逻辑 - 必要注释：在组件开始/结束处加 HTML 注释说明作用域和限制，例如
<!-- notification-banner: renders only when .message is set, ignores empty strings -->
最常被跳过的一步，是忘记在构建流程中把自定义元素的 JS 文件纳入打包或预加载 —— 开发时一切正常，上线后 <date-picker></date-picker> 突然变成空白标签，debug 半天才发现 script 404。
