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 自动安装。

使用方法

$3

`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);
`

$3

`html



`

API 文档

$3

#### 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);
`

$3

#### 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引擎的额外配置选项
}
`

示例

$3

`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);
`

$3

`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
});
`

$3

`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
});
`

$3

`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引擎
});
`

$3

`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'
});
`

$3

`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);
// 库会自动尝试降级到备用引擎
}
`

$3

`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
});
`

常见问题

$3

A: 这通常是因为自定义字体未完全加载。解决方案：
- 启用 embedFonts: true 将字体内联到截图中
- 启用 preCacheFonts: true 预加载字体资源
- 确保在截图前字体已加载完成

$3

A: 本库具有自动降级机制：
- 默认优先使用 snapdom 引擎
- 失败时自动降级到 html2canvas
- 查看控制台错误信息进行调试

$3

A: 配置 CORS 相关选项：
`javascript
const base64 = await screenshot(element, {
useCORS: true,
allowTaint: false
});
`

$3

A: 尝试以下优化：
- 增加 scale 值获得更高分辨率
- 启用 processSvg 和 processGradientText
- 使用 PNG 格式保持最佳质量

最佳实践

1. 字体处理：对于包含自定义字体的元素，建议启用字体相关选项
2. 性能优化：大型元素截图时适当降低 scale 和 quality
3. 错误处理：始终使用 try-catch 包装截图调用
4. 移动端：使用 window.devicePixelRatio` 适配不同设备
5. 复杂元素：启用预处理选项处理 SVG 和渐变文本

许可证

MIT