@web-js/dom-screenshot/README.md

A lightweight DOM screenshot library based on @zumer/snapdom and html2canvas.

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

## 使用方法

### ES 模块

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

### UMD 模块（浏览器）

```html
<!-- 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 字符串。

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

### DomScreenshot 类

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

## 常见问题

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

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

### Q: 截图失败怎么办？

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

### Q: 如何处理跨域图片？

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

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

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

## 最佳实践

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

## 许可证

MIT