点赞 + 关注 + 收藏 = 学会了

html2canvas 简介

在实际项目中，最常遇到的需求是「把页面上的某块内容保存为图片」——比如生成分享海报、保存订单凭证、或是做离线文档。传统做法需要后端渲染或调用第三方截图服务，既麻烦又不够实时。html2canvas 这款纯前端的 JavaScript 库。直接在浏览器里把 HTML 元素「拍」成 Canvas 图片，让这些需求变得轻松可控。

安装方法

根据项目的技术栈选择合适的方式即可。

. npm / yarn 安装

如果你的项目使用 Webpack、Vite 等建立工具。直接通过包管理器引入：

# npm
npm install html2canvas
# yarn
yarn add html2canvas

下面示例基于 Vite 创建的 Vue3 项目，其他框架的使用方式基本相同。

. CDN 引入

对于纯 HTML 页面只需在 或 中加入 CDN 链接：

从基础用法来看。一键截图并显示

痛点：第一次使用时往往只想「点按钮」就能得到图片，却常因样式缺失、跨域图片或滚动条等问题导致截图不完整。其实，下面先给出最小可运行示例，再逐步说明常见坑。老实说，

常见坑①的观点是，标题样式不被渲染

如果在截图区域加入 默认样式往往会丢失。

雷猴

随便写点什么...

方法：为所有标签显式写样式，避免浏览器默认样式被忽略。

常用配置选项

配置项	类型	默认值	说明
scale	number	window.devicePixelRatio	缩放比例，提高清晰度；设为 1 可防止模糊。
useCORS	boolean	false	true 时允许加载跨域图片。按理说，
backgroundColor	string	#ffffff	Cavnas 背景色。设为 null 可得到透明背景。
logging	boolean	false	true 时在控制台输出调试信息。
scrollX / scrollY--截屏时的滚动偏移，用于修正滚动导致的错位。

Pain Point：跨域图片显示为空白 ⚠️

If your screenshot contains images hosted on anor domain,y will appear blank by default due to browser's same‑origin policy.

Solve it in two steps:

1. Add ` on image server .
2. Create canvas with { useCORS: true }.
3. Add to tag.

// 示例 const canvas = await html5 canvas

Pain Point：CSS 样式不兼容

Some advanced CSS are not fully supported by html5 canvas.

• Keep layout simple – avoid complex effects inside captured area.
• Replace heavy effects with static images if necessary.
• Check official “Supported CSS” list for details.

Pain Point：自定义字体未渲染

When using @font-face。screenshots may fall back to system fonts because font hasn't finished loading.

document . get Element By Id . add Event Listener => {
// 等待所有字体加载完成
await document . fonts . ready;const element = document . get Element By Id;const canvas = await html5 canvas;说起来，document . body . append Child;})，按理说，

Pain Point：滚动条导致截取不完整

当目标元素内部出现滚动条时截屏会把滚动条一起捕获或出现内容被裁剪的问题。

const el = document . get Element By Id;const originalOverflow = el . style . overflow;其实，// 保存原始值
el . style . overflow = ' hidden ';话说回来，// 隐藏滚动条

const canvas = await html5 canvas;el . style . overflow = originalOverflow;// 恢复

Pain Point：iframe 内容无法捕获

• 同源 iframe 可以先获取其内部元素再进行截屏。
• 跨域 iframe 基本无解，只能考虑后端渲染或第三方服务。

Pain Point：大量 DOM 导致卡顿

• 降低 。
• 截图前隐藏不必要的元素。
• 尽量只截取必要区域，而不是整页。说起来，

Pain Point：SVG 渲染异常

Directly capturing an inline SVG may result in distortion or missing graphics.

// 将 SVG 转为 Image 再截取
const svgEl = document . query Selector;const svgData = new XMLSerializer . serialize To String;const img = new Image;img.src = ' data:image/svg+xml;base64,' + btoa ));

img.onload = async => { svgEl . parentNode . replace Child;const canvas= await html5 canvas );document . body . append Child;}，

Pain Point：z-index 层级错乱

• 为涉及层级的元素显式设置 position。
• 如有冲突，可通过调整 DOM 顺序来控制覆盖关系。

<& script setup>& n import {ref}from'vue';import html5 canvasfrom'html5 canvas';说起来，

const captureRef=ref;const handleCapture=async=>{ const c anvas=await html5ca nvas;// 转成 PNG Base64 const imgData=c anvas.toDataURL;// 创建下载链接并触发 const link=document.createElement;link.download='我的截图.png';link.href=imgData;link.click，};<&/script>& n

<& style scoped>& n .capture-area{ 至于width，400px;border:1px solid #ccc;} .title{font-size:24px;font-weight:bold;margin:10px，} <&/style>& n

• CORS 图片空白：Add server header、set crossorigin and enable useCORS:true.

• CSS 不兼容：Simplify styles or replace with images.

• TTC 字体未加载：Await document.fonts.ready before calling html5canvas.

• Echarts/Highcharts 动态图表：If using Canvas‑based charts y work out‑of‑‑box. For SVG charts convert m to Canvas first.

• IFrame 跨域限制：Use same‑origin if possible or switch to server‑side screenshot service.

• LARGE DOM 性能问题：Reduce scale,hide unnecessary nodes and limit capture area.

• SVG 渲染错误：Convert SVG → Image → Canvas before screenshotting.

• Z‑Index 错乱：Explicitly set position and adjust DOM order instead of relying solely on z-index.

。

---