必须等DOM渲染完成后再调用，否则因元素未挂载、CSS未生效或字体未加载，会导致黑块、白图、缺字或布局塌陷；推荐用requestAnimationFrame+offsetHeight检测渲染就绪。
直接用 html-to-image 库最省事，不依赖服务器、不传数据、前端本地就能跑，但必须注意 DOM 渲染完成后再调用。
为什么不能一加载就转？
HTML 转图片本质是「截图」，不是「渲染快照」。如果目标元素还没挂载、CSS 还没生效、字体还没加载完，生成的图就是空白、错位或缺字。
- 常见错误现象：
toPng()返回黑块、白图、文字缺失、布局塌陷 - 使用场景：动态生成的图表容器、Vue/React 组件内嵌内容、含 WebFont 的标题
- 解决办法：等
targetElement真实存在于 DOM 且样式就绪 —— 推荐用requestAnimationFrame+offsetHeight检查，比setTimeout更可靠 - 示例片段：
const el = document.getElementById('text-container'); if (el.offsetHeight === 0) { requestAnimationFrame(() => toPng(el)); } else { toPng(el); }
toPng() 和 toJpeg() 怎么选？
纯文字转图，优先用 toPng()；如果要发微信、嵌入 PPT 或上传到不支持透明通道的系统，才切 toJpeg()。
-
toPng()默认保留透明背景，适合深色主题页面导出；但文件体积比 JPEG 大 2–5 倍 -
toJpeg()强制丢弃 alpha 通道，quality: 0.92是清晰度与体积的合理平衡点（低于 0.8 文字边缘易出现模糊噪点） - 注意：
toJpeg()在含 CSSfilter: drop-shadow()或backdrop-filter的元素上可能失效，需提前移除或降级
中文字体不显示？检查这三个地方
不是库的问题，是浏览器渲染链路断在了字体加载环节。
立即学习“前端免费学习笔记（深入）”；
- 确保字体已通过
@font-face声明，且src路径可访问（本地 file:// 协议下 WebFont 通常被拦截） - 避免用系统字体名如
"PingFang SC"，改用更通用的后备栈：font-family: "Inter", "Helvetica Neue", sans-serif; - 关键文字元素加
font-display: swap，防止字体加载期间 fallback 字体被截进图里 —— 但得配合document.fonts.load()等待实际加载完成再触发转换
批量转多段文字？别循环调用 toPng()
连续调用会阻塞主线程、触发浏览器节流，还容易因 canvas 上下文复用导致图像重叠或内存溢出。
- 正确做法：为每段文字创建独立
<div>容器，每个容器单独调用toPng()，并用Promise.all()控制并发（建议限制为 3–4 个） - 性能影响：未加限制时 10 段文字可能卡死低端手机；加并发控制后耗时增加约 15%，但稳定性提升明显
- 容易踩的坑：把所有文字塞进同一个
div再分段截取 ——html-to-image不支持局部区域裁剪，只能靠 DOM 结构隔离
真正难的不是调用函数，而是让浏览器「诚实地画出来」—— 字体、尺寸、渲染时机，三者缺一不可。多数失败案例，最后都卡在 document.fonts.load() 没等完，或者用了 display: none 隐藏容器却忘了切回 visibility: hidden。
