DOM Screenshot

一个智能的 DOM 截图库，优先使用 @zumer/snapdom，失败时自动降级到 html2canvas，支持 ES 模块和 UMD 模块。

特性

🚀 轻量级，双引擎支持（snapdom + html2canvas）
🔄 智能降级机制，确保截图成功率
📦 支持 ES 模块和 UMD 模块
🎯 TypeScript 支持
🖼️ 多种输出格式（Canvas、Base64、Blob）
⚙️ 丰富的配置选项
📱 支持移动端

工作原理

本库采用智能双引擎截图策略：

优先使用 @zumer/snapdom：更快速、更准确的现代截图引擎
自动降级到 html2canvas：当 snapdom 失败时，自动切换到经过验证的 html2canvas
错误处理：提供详细的错误信息，帮助调试问题

安装

npm install @web-js/dom-screenshot

注意：本库依赖 @zumer/snapdom 和 html2canvas，它们会作为 peer dependencies 自动安装。

使用方法

ES 模块

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

UMD 模块（浏览器）

<!-- UMD 模块已包含所有依赖，无需额外引入 -->
<script src="node_modules/@web-js/dom-screenshot/dist/dom-screenshot.umd.js"></script>
<script>
  const element = document.getElementById('target');
  DomScreenshot.screenshot(element).then(base64 => {
    console.log(base64);
  });
</script>

API 文档

快速函数

`screenshot(element, options?)`

截取 DOM 元素为 Base64 字符串。

const base64 = await screenshot(element, {
  quality: 0.8,
  format: 'jpeg',
  backgroundColor: '#ffffff'
});

`screenshotToCanvas(element, options?)`

截取 DOM 元素为 Canvas 对象。

const canvas = await screenshotToCanvas(element);
document.body.appendChild(canvas);

`screenshotToBlob(element, options?)`

截取 DOM 元素为 Blob 对象。

const blob = await screenshotToBlob(element);
const url = URL.createObjectURL(blob);

DomScreenshot 类

`captureToCanvas(element, options?)`

截取 DOM 元素为 Canvas。

`captureToBase64(element, options?)`

截取 DOM 元素为 Base64 字符串。

`captureToBlob(element, options?)`

截取 DOM 元素为 Blob 对象。

`downloadScreenshot(element, filename?, options?)`

直接下载 DOM 元素截图。

const domScreenshot = new DomScreenshot();
await domScreenshot.downloadScreenshot(element, 'my-screenshot');

配置选项

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

示例

基础用法

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

自定义配置

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

下载截图

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

字体渲染优化

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

处理复杂元素

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

错误处理

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

移动端适配

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

常见问题

Q: 为什么字体在截图中显示不正确？

A: 这通常是因为自定义字体未完全加载。解决方案：

启用 embedFonts: true 将字体内联到截图中
启用 preCacheFonts: true 预加载字体资源
确保在截图前字体已加载完成

Q: 截图失败怎么办？

A: 本库具有自动降级机制：

默认优先使用 snapdom 引擎
失败时自动降级到 html2canvas
查看控制台错误信息进行调试

Q: 如何处理跨域图片？

A: 配置 CORS 相关选项：

const base64 = await screenshot(element, {
  useCORS: true,
  allowTaint: false
});

Q: 截图质量不佳怎么办？

A: 尝试以下优化：

增加 scale 值获得更高分辨率
启用 processSvg 和 processGradientText
使用 PNG 格式保持最佳质量

最佳实践

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

许可证

MIT

Détail du package

@web-js/dom-screenshot

readme