必须用 cloneNode(true) 克隆 template.content 才能正确渲染；动画逻辑须在 connectedCallback 中显式触发，不可写在 template 内；slot 内容需通过 wrapper 容器或 slotchange 事件处理动画；避免在 constructor 中触发动画。
template 元素必须配合 cloneNode(true) 使用
<template> 本身不会渲染，也不会执行内部脚本或加载资源。直接 innerHTML 赋值或 appendChild 原始 template 元素，会导致结构丢失、事件失效、样式不生效。
- 必须用
document.getElementById('my-tpl').content.cloneNode(true)获取纯净副本 -
cloneNode(true)才能复制子节点、文本、属性，且不触发重复解析 - 错误写法：
this.shadowRoot.appendChild(document.getElementById('my-tpl'))—— 这会把 template 元素本身塞进去，它仍是不可见的文档片段 - 正确路径：克隆 → 替换占位符（如
data-bind或slot）→ 插入this.shadowRoot
动画逻辑不能写在 template 内部
<template> 是静态结构容器，不支持内联 JS、onload、onclick 等事件绑定，更无法直接调用 requestAnimationFrame 或控制 CSS 动画状态。
- 所有动画启动必须在组件类中显式触发：比如在
connectedCallback()里调用this.startAnimation() - 若需响应用户操作（如 hover 启动入场动画），要在
connectedCallback()中查到内部元素并绑定addEventListener('mouseenter', ...) - 避免在 template 字符串里写
style="animation: fade-in 0.3s"并指望它自动播放——CSS 动画需元素已挂载且 class 已存在，否则会被跳过
如何让动画与组件状态联动
原生 HTML 模板不提供响应式数据绑定，动画是否播放、播放哪一段、是否重置，全靠手动同步。- 推荐模式：用
this._isAnimating = true控制状态，结合getBoundingClientRect()或offsetTop判断可见性再触发动画 - 示例：滚动进入视口时播放淡入
const observer = new IntersectionObserver(entries => { entries.forEach(entry => { if (entry.isIntersecting) { entry.target.shadowRoot.querySelector('.content').classList.add('animate-in'); } }); }); observer.observe(this); - 注意：若组件被多次复用，每个实例要维护独立的 observer 实例或使用
WeakMap关联，避免互相干扰
slot 与动画的兼容性陷阱
<slot> 内容是“透传”进来的 light DOM 节点，它默认不在 shadowRoot 下，因此：
- 直接对
<slot>元素设置animation属性无效（它没被渲染到 shadow 内） - 若想给插槽内容加入场动画，必须在
slotchange事件中监听，并手动遍历assignedNodes()，再逐个添加 class 或 style - 更稳妥做法：在 template 中预留带 class 的 wrapper 容器（如
<div class="slot-wrapper"><slot></slot></div>），动画作用于 wrapper，而非 slot 本身
组件封装里最容易被忽略的，是动画触发时机和 DOM 生命周期的错位——比如在 constructor() 里就调用 requestAnimationFrame，此时元素还没挂载，getBoundingClientRect() 返回 0，动画永远卡在初始帧。
