A lightweight DOM screenshot library based on @zumer/snapdom and html2canvas.
npm install @web-js/dom-screenshot一个智能的 DOM 截图库,优先使用 @zumer/snapdom,失败时自动降级到 html2canvas,支持 ES 模块和 UMD 模块。
- 🚀 轻量级,双引擎支持(snapdom + html2canvas)
- 🔄 智能降级机制,确保截图成功率
- 📦 支持 ES 模块和 UMD 模块
- 🎯 TypeScript 支持
- 🖼️ 多种输出格式(Canvas、Base64、Blob)
- ⚙️ 丰富的配置选项
- 📱 支持移动端
本库采用智能双引擎截图策略:
1. 优先使用 @zumer/snapdom:更快速、更准确的现代截图引擎
2. 自动降级到 html2canvas:当 snapdom 失败时,自动切换到经过验证的 html2canvas
3. 错误处理:提供详细的错误信息,帮助调试问题
``bash`
npm install @web-js/dom-screenshot
注意:本库依赖 @zumer/snapdom 和 html2canvas,它们会作为 peer dependencies 自动安装。
`javascript
import { screenshot, DomScreenshot } from '@web-js/dom-screenshot';
// 快速截图 - 返回 Base64
const element = document.getElementById('target');
const base64 = await screenshot(element);
console.log(base64);
// 使用类实例
const domScreenshot = new DomScreenshot();
const canvas = await domScreenshot.captureToCanvas(element);
`
`html`
#### screenshot(element, options?)
截取 DOM 元素为 Base64 字符串。
`javascript`
const base64 = await screenshot(element, {
quality: 0.8,
format: 'jpeg',
backgroundColor: '#ffffff'
});
#### screenshotToCanvas(element, options?)
截取 DOM 元素为 Canvas 对象。
`javascript`
const canvas = await screenshotToCanvas(element);
document.body.appendChild(canvas);
#### screenshotToBlob(element, options?)
截取 DOM 元素为 Blob 对象。
`javascript`
const blob = await screenshotToBlob(element);
const url = URL.createObjectURL(blob);
#### captureToCanvas(element, options?)
截取 DOM 元素为 Canvas。
#### captureToBase64(element, options?)
截取 DOM 元素为 Base64 字符串。
#### captureToBlob(element, options?)
截取 DOM 元素为 Blob 对象。
#### downloadScreenshot(element, filename?, options?)
直接下载 DOM 元素截图。
`javascript`
const domScreenshot = new DomScreenshot();
await domScreenshot.downloadScreenshot(element, 'my-screenshot');
`typescript`
interface ScreenshotOptions {
quality?: number; // 图片质量 (0-1),默认 1
format?: 'png' | 'jpeg' | 'webp'; // 图片格式,默认 'png'
backgroundColor?: string; // 背景颜色,默认 '#ffffff'
allowTaint?: boolean; // 是否允许跨域,默认 false
useCORS?: boolean; // 是否使用 CORS,默认 true
scale?: number; // 缩放比例,默认 1
width?: number; // 输出宽度
height?: number; // 输出高度
ignoreElements?: (element: Element) => boolean; // 忽略元素的函数
processSvg?: boolean; // 是否启用SVG元素预处理,默认 true
processGradientText?: boolean; // 是否启用CSS渐变文本预处理,默认 true
enginePriority?: 'snapdom' | 'html2canvas'; // 引擎优先级,默认 'snapdom'
embedFonts?: boolean; // 是否内联字体以确保字体正确渲染,默认 true
preCacheFonts?: boolean; // 是否预加载字体和资源,默认 true
snapdomOptions?: object; // snapdom引擎的额外配置选项
html2canvasOptions?: object; // html2canvas引擎的额外配置选项
}
`javascript
import { screenshot } from '@web-js/dom-screenshot';
const element = document.querySelector('.screenshot-target');
const base64 = await screenshot(element);
// 显示截图
const img = document.createElement('img');
img.src = base64;
document.body.appendChild(img);
`
`javascript
import { DomScreenshot } from '@web-js/dom-screenshot';
const domScreenshot = new DomScreenshot();
const element = document.querySelector('.target');
const canvas = await domScreenshot.captureToCanvas(element, {
scale: 2,
backgroundColor: 'transparent',
format: 'png',
quality: 1
});
`
`javascript
import { DomScreenshot } from '@web-js/dom-screenshot';
const domScreenshot = new DomScreenshot();
const element = document.querySelector('.download-target');
// 直接下载
await domScreenshot.downloadScreenshot(element, 'my-page-screenshot', {
format: 'jpeg',
quality: 0.9
});
`
`javascript
import { screenshot } from '@web-js/dom-screenshot';
// 确保自定义字体正确渲染
const element = document.querySelector('.custom-font-element');
const base64 = await screenshot(element, {
embedFonts: true, // 内联字体到截图中
preCacheFonts: true, // 预加载字体资源
enginePriority: 'snapdom' // 优先使用snapdom引擎
});
`
`javascript
import { screenshotToCanvas } from '@web-js/dom-screenshot';
// 处理包含SVG和渐变文本的复杂元素
const element = document.querySelector('.complex-element');
const canvas = await screenshotToCanvas(element, {
processSvg: true, // 预处理SVG元素
processGradientText: true, // 处理CSS渐变文本
scale: 2, // 高分辨率截图
backgroundColor: 'transparent'
});
`
`javascript
import { screenshot } from '@web-js/dom-screenshot';
try {
const element = document.querySelector('.target');
const base64 = await screenshot(element, {
enginePriority: 'snapdom'
});
console.log('截图成功:', base64);
} catch (error) {
console.error('截图失败:', error.message);
// 库会自动尝试降级到备用引擎
}
`
`javascript
import { screenshotToBlob } from '@web-js/dom-screenshot';
// 移动端截图优化
const element = document.querySelector('.mobile-content');
const blob = await screenshotToBlob(element, {
scale: window.devicePixelRatio, // 适配设备像素比
format: 'jpeg',
quality: 0.8, // 平衡质量和文件大小
useCORS: true
});
`
A: 这通常是因为自定义字体未完全加载。解决方案:
- 启用 embedFonts: true 将字体内联到截图中preCacheFonts: true
- 启用 预加载字体资源
- 确保在截图前字体已加载完成
A: 本库具有自动降级机制:
- 默认优先使用 snapdom 引擎
- 失败时自动降级到 html2canvas
- 查看控制台错误信息进行调试
A: 配置 CORS 相关选项:
`javascript`
const base64 = await screenshot(element, {
useCORS: true,
allowTaint: false
});
A: 尝试以下优化:
- 增加 scale 值获得更高分辨率processSvg
- 启用 和 processGradientText
- 使用 PNG 格式保持最佳质量
1. 字体处理:对于包含自定义字体的元素,建议启用字体相关选项
2. 性能优化:大型元素截图时适当降低 scale 和 qualitywindow.devicePixelRatio` 适配不同设备
3. 错误处理:始终使用 try-catch 包装截图调用
4. 移动端:使用
5. 复杂元素:启用预处理选项处理 SVG 和渐变文本
MIT