自定义元素名必须含连字符（如my-card）、禁用原生名和PascalCase；constructor仅做最小初始化，DOM操作和属性读取须在connectedCallback中；Shadow DOM需内嵌样式并用:host和CSS变量；扩展现有元素必须用is属性且大小写严格匹配。
自定义元素必须带连字符，否则注册直接失败
浏览器只认含连字符的标签名，比如 nav-menu、date-picker，写成 navmenu 或 NavMenu 会立刻报错：Failed to execute 'define' on 'CustomElementRegistry': The name "navmenu" is not a valid custom element name。原生标签名（如 div、button、slot）也禁止复用。
常见错误场景包括：在原型项目里用下划线命名（my_button），或试图用 PascalCase（MyCard）——这些都不会被解析为自定义元素，HTML 解析器直接当未知标签处理，后续所有生命周期钩子、属性监听、Shadow DOM 都不会触发。
-
my-card✅ 合法，小写 + 连字符 -
x-input✅ 可用，但建议语义化而非前缀化 -
card❌ 冲突原生名（虽未被占用，但规范禁止）
constructor 里不能读属性或操作 DOM，connectedCallback 才是安全入口
很多人在 constructor 里直接写 this.getAttribute('size') 或 this.innerHTML = 'loading...'，结果发现属性读不到、样式不生效、甚至抛 NotSupportedError: Failed to execute 'attachShadow'。这是因为此时元素尚未挂载到文档，DOM 尚未就绪，且 attribute 值可能还未同步。
正确做法是：constructor 只做最小初始化（super()、创建 shadow root、绑定私有字段）；所有 DOM 操作、属性读取、模板渲染，必须等 connectedCallback 触发后再执行。
立即学习“前端免费学习笔记（深入）”；
- 需要响应
label="xxx"？先在static get observedAttributes()里声明['label']，再靠attributeChangedCallback更新视图 - 初始值不会触发
attributeChangedCallback，得在connectedCallback里手动调一次this.label = this.getAttribute('label') - 想用
fetch加载数据？必须放connectedCallback，否则请求可能发不出去或返回空
样式必须注入 Shadow DOM 内部，外部 CSS 默认不穿透
写了 this.attachShadow({ mode: 'open' }) 却发现字体、颜色、间距全丢了？不是代码错了，是 Shadow DOM 天然隔离样式 —— 外部 CSS 不会进来，内部样式也不会漏出去。你不能指望页面全局的 body { color: red } 影响自定义元素里的文本。
必须显式把样式塞进 shadow root：要么用 shadowRoot.innerHTML += '<style>...</style>'，要么创建 style 元素后 appendChild。想让外部控制尺寸或主题？用 CSS 自定义属性：
shadowRoot.innerHTML = `
<style>
:host { display: inline-block; }
:host([size="large"]) { font-size: 1.2em; }
.content { color: var(--text-color, #333); }
</style>
<div class="content"><slot></slot></div>
`;
-
:host选中宿主元素自身，:host([disabled])可响应布尔属性 - 避免在 shadow 内写
body或html选择器 —— 它们根本不存在 - 若需继承外部字体/行高，显式用
inherit或var(--font-base)
扩展现有元素必须用 is 属性，否则 width/height/getContext 全失效
想给 <canvas> 加个自动 resize 功能？写 class RenderArea extends HTMLCanvasElement 然后 customElements.define('render-area', RenderArea, { extends: 'canvas' }) 是对的，但 HTML 里写 <render-area width="400"></render-area> 就错了 —— 浏览器根本不把它当 canvas 解析，width 属性无效，getContext() 报 undefined。
正确写法只有一种：<canvas is="render-area" width="400" height="300"></canvas>。注意：is 的值必须和 define() 第一个参数完全一致（大小写、连字符、无空格），漏掉或写错，就等于没注册。
-
<canvas is="render-area">✅ 生效 -
<canvas is="RenderArea">❌ 大小写不匹配，失效 -
<render-area is="render-area">❌ 混用标签名和 is，浏览器忽略自定义类 - 旧浏览器（IE / Edge ≤18）必须引入
@webcomponents/custom-elementspolyfill，且要在任何define()前加载
积木式开发的核心不是堆标签，而是让每个自定义元素真正“自包含”：它得有自己的 DOM 结构、样式边界、属性契约和生命周期响应。最容易被忽略的是属性初始值同步和 is 属性的强制性 —— 这两点一错，整个组件就静默失效，连控制台都不报错。
