customElements.define()报“not a valid custom element name”是因为HTML规范强制要求自定义标签名必须包含至少一个ASCII短横线且全小写，如user-card合法，而myheader、UserCard、sidebar因缺短横线或含大写等违反规范被浏览器硬拦截拒绝注册。
customElements.define() 为什么报 “not a valid custom element name”
因为浏览器强制要求自定义标签名必须含短横线，否则直接拒绝注册。customElements.define() 遇到 myheader、UserCard 或 sidebar 这类名字，会抛出 Failed to execute 'define' on 'CustomElementRegistry': The name "xxx" is not a valid custom element name。
这不是兼容性问题，是 HTML 规范层的硬拦截——目的是让解析器能无歧义区分原生标签（如 header、article）和自定义扩展。
- 合法：
main-layout、user-card、responsive-grid - 非法：
header（原生已有）、MyCard（无短横线+大驼峰）、usercard（小写无短横线） - 别试图用
data-前缀绕过，data-user-card也不是合法标签名
布局类组件该不该用 Shadow DOM
大多数布局模板（比如三栏、顶部导航+主内容、响应式栅格）**不该用** Shadow DOM。它的核心代价是样式穿透被切断，外部 CSS 写 main-layout .content 就完全失效。
布局组件要的是结构复用 + 语义化 + 外部可控，不是强封装。强行加 this.attachShadow({ mode: 'open' }) 反而让下游开发者没法调整 padding、margin、颜色等基础表现。
立即学习“前端免费学习笔记（深入）”；
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- 适合 Shadow DOM 的：按钮、输入框、模态框等自带行为与样式的 UI 控件
- 布局组件更推荐直接操作
this.innerHTML或this.append()，保持样式作用域开放 - 若真需局部样式隔离（如默认页头背景），只在内部加一层
<style>，不要整个容器 Shadow
attributeChangedCallback 为什么没触发
它只响应 HTML 属性变更（setAttribute()、removeAttribute()、初始 HTML 中写的属性），对 JS 属性赋值（el.mode = 'dark'）完全静默。
常见误判是以为监听了 mode 就能捕获所有修改，结果用户代码里写 myLayout.mode = 'mobile'，UI 却毫无反应。
- 必须显式声明
static get observedAttributes() { return ['mode', 'breakpoint']; } - 首次初始化时
oldValue是null，别直接用=== 'old'判断，改用oldValue !== newValue - 布尔属性（如
collapsed）的newValue是字符串"true"或null，需手动转布尔：!!newValue - 若需支持 JS 属性同步，得在 setter 里补
this.setAttribute('mode', value)
template.content.cloneNode(true) 为什么不能直接用 content
<template> 的 content 是一个离线 DocumentFragment，直接 appendChild(content) 会把节点“移动”过去，只有一份；后续再用就空了。直接 innerHTML = template.content 会丢失事件绑定、破坏 ID 唯一性、甚至静默失败。
正确做法永远是克隆：用 template.content.cloneNode(true) 得到一份全新副本，再填充数据、绑定事件、插入 DOM。
<template id="card"><div class="card"><h3 data-bind="title"></h3><p data-bind="desc"></p></div></template>- 克隆后遍历找
data-bind，写入对应字段：instance.querySelector('[data-bind="title"]').textContent = data.title - 内联
onclick在克隆后无效，改用instance.querySelector('button').addEventListener('click', handler)
真正难的不是写出来，而是想清楚：这个组件到底需要多强的封装边界？布局结构要不要被外部样式控制？属性变更是否必须实时响应？这些判断比语法细节更能决定最终能否落地。
