customElements.define()仅注册标签，不自动渲染模板；动态渲染需在connectedCallback中手动克隆<template>并填充内容，否则元素为空且事件/样式易失效。
自定义元素（customElements.define()）本身不负责模板动态化，它只注册标签；真正做动态渲染的，是 <template> + JS 克隆填充，或 React/Vue 的渲染函数。混用二者时，最容易卡在“注册了但没渲染”或“渲染了但事件/样式失效”上。
为什么不能直接用 customElements.define() 渲染模板
customElements.define() 只告诉浏览器：“这个标签名我认，后续遇到就当合法元素处理”，但它不自动读取、克隆、填充任何模板内容。如果你只注册了 my-card，却不写 connectedCallback 里手动取 <template id="card-tmpl"> 并插入内容，页面上就只会有一个空的 <my-card></my-card> 节点——既没结构，也没数据。
- 常见错误：把
<template>当作“注册即生效”的模板引擎，结果 DOM 里啥都没出来 - 根本原因：自定义元素生命周期（如
connectedCallback）是空的，没主动操作 DOM - 正确做法：在
connectedCallback中定位模板、克隆、填充、挂载，例如：const tmpl = document.querySelector('#card-tmpl'); const frag = tmpl.content.cloneNode(true); this.appendChild(frag);
<template> 克隆后怎么安全填数据
克隆出来的节点树是普通 DOM，但不能直接改 innerHTML（破坏事件监听器、引入 XSS 风险），也不能依赖内联 onclick（<template> 里的脚本和事件绑定全被忽略）。
- 优先用
querySelector找目标元素，再设textContent或value：比如frag.querySelector('.title').textContent = this.getAttribute('title') - 需要保留原始结构中的
data-属性？用dataset：比如frag.querySelector('button').dataset.id = this.dataset.id - 避免在循环中反复
appendChild到真实 DOM，先塞进document.createDocumentFragment()，最后一次性挂载 - 如果模板含
<slot>，注意它只在 Shadow DOM 中生效；普通 DOM 下克隆后<slot>就是普通文本节点，不会分发内容
自定义元素 + <template> 组合时的样式与尺寸陷阱
把 <template> 内容 append 到自定义元素内部，样式链和尺寸计算可能意外中断，尤其当内容含 <canvas> 或依赖父容器宽高的组件时。
立即学习“前端免费学习笔记（深入）”；
- Shadow DOM 会切断 CSS 继承：外层定义的
.card img { max-width: 100% }对 shadowRoot 里的<img>不生效，必须在<style>标签里重写或用:host -
<canvas>渲染失败？不是库 bug，而是克隆后canvas.width/height未重设，或父容器还没 layout 完就被 JS 读取了getBoundingClientRect() - 避免在
connectedCallback立即读取offsetWidth—— 此时 DOM 刚挂载，样式尚未计算，应改用requestAnimationFrame延后一帧 - 如果模板里有第三方图表（如 Chart.js），别把
<canvas>放进 shadowRoot，否则getContext('2d')返回 null；要么放 light DOM，要么用attachShadow({ mode: 'open' })后显式注入<style>和尺寸逻辑
React/Vue 里用自定义元素渲染模板要绕开哪些坑
框架对自定义元素的支持是“语法层面兼容”，但不自动接管其内部模板逻辑。你写了 <my-card title="xxx">，框架只把它当一个黑盒 HTML 标签传下去，不会帮你解析里面嵌套的 <template> 或触发 connectedCallback。
- React 中：必须用
useEffect手动触发customElements.whenDefined('my-card').then(...)，否则服务端渲染（SSR）时组件可能提前挂载，connectedCallback没机会执行 - Vue 中：不要用
v-html渲染含自定义元素的字符串——v-html插入的是静态 DOM，不会触发customElements.define()注册流程，也不会调用生命周期 - 通用原则：框架负责“挂载自定义元素”，但“内部模板动态化”仍需在自定义元素类里自行实现，框架不越界
- 调试关键点：检查
console.dir(document.querySelector('my-card'))，确认它是不是HTMLUnknownElement（未注册）还是已注册的自定义构造函数实例
真正难的不是写 customElements.define()，而是让模板内容在正确时机、正确上下文、正确作用域里被克隆、填充、挂载，并且不破坏样式链、不丢事件、不卡尺寸计算。这些细节大多发生在 connectedCallback 和 attributeChangedCallback 里，而不是注册那一刻。
