# 图片格式转换工具

基于 Sharp 的高性能图片格式转换工具，支持多种图片格式之间的转换，包括 JPG、PNG、WebP、AVIF 等。

## 功能特性

- 🚀 高性能图片格式转换
- 📐 支持尺寸调整和缩放
- 🎨 支持质量控制和压缩选项
- 📦 批量转换支持
- 🖼️ 缩略图生成
- 📊 详细的转换统计信息
- 🔍 图片信息获取

## 支持的格式

### 输入格式
- JPEG/JPG
- PNG
- WebP
- AVIF
- TIFF
- GIF

### 输出格式
- JPEG/JPG
- PNG
- WebP
- AVIF
- TIFF

## 安装依赖

确保项目中已安装 Sharp：

```bash
npm install sharp
```

## 基本用法

### 1. 单张图片转换

```typescript
import { convertImage } from '@xiping/node-utils';

// 将 JPG 转换为 WebP
const result = await convertImage(
  './input/sample.jpg',
  './output/sample.webp',
  'webp',
  {
    quality: 85,
    width: 800,
    height: 600
  }
);

console.log('转换结果:', result);
```

### 2. 批量转换

```typescript
import { batchConvert } from '@xiping/node-utils';

const files = [
  {
    inputPath: './input/image1.jpg',
    outputPath: './output/image1.webp',
    format: 'webp'
  },
  {
    inputPath: './input/image2.png',
    outputPath: './output/image2.avif',
    format: 'avif'
  }
];

const results = await batchConvert(files, {
  quality: 80,
  width: 1200
});
```

### 3. 创建缩略图

```typescript
import { createThumbnail } from '@xiping/node-utils';

const result = await createThumbnail(
  './input/large-image.jpg',
  './output/thumbnail.jpg',
  200,
  200,
  'jpeg',
  { quality: 90 }
);
```

### 4. 获取图片信息

```typescript
import { getImageInfo } from '@xiping/node-utils';

const info = await getImageInfo('./input/sample.jpg');
console.log('图片信息:', info);
```

## 高级用法

### 使用 ImageConverter 类

```typescript
import { ImageConverter } from '@xiping/node-utils';

// 转换为 WebP（推荐用于 Web）
await ImageConverter.toWebP('./input.jpg', './output.webp', 85);

// 转换为 AVIF（最新格式，压缩率更高）
await ImageConverter.toAVIF('./input.jpg', './output.avif', 80);

// 转换为 PNG（保持透明度）
await ImageConverter.toPNG('./input.jpg', './output.png', true);

// 转换为 JPEG（通用格式）
await ImageConverter.toJPEG('./input.png', './output.jpg', 90);
```

### 创建响应式图片

```typescript
import { ImageConverter } from '@xiping/node-utils';

const sizes = [
  { width: 320, height: 240, suffix: 'small' },
  { width: 640, height: 480, suffix: 'medium' },
  { width: 1280, height: 960, suffix: 'large' }
];

const results = await ImageConverter.createResponsiveImages(
  './input/hero-image.jpg',
  './output/',
  'hero',
  sizes
);
```

## 转换选项

```typescript
interface ConvertOptions {
  /** 输出质量 (1-100)，仅对 JPEG、WebP、AVIF 有效 */
  quality?: number;
  /** 是否保持透明度，仅对 PNG、WebP 有效 */
  keepTransparency?: boolean;
  /** 输出宽度，保持宽高比 */
  width?: number;
  /** 输出高度，保持宽高比 */
  height?: number;
  /** 是否强制调整尺寸（不保持宽高比） */
  forceResize?: boolean;
  /** 压缩级别 (0-9)，仅对 PNG 有效 */
  compressionLevel?: number;
  /** 是否渐进式编码，仅对 JPEG 有效 */
  progressive?: boolean;
}
```

## 转换结果

```typescript
interface ConvertResult {
  /** 输入文件路径 */
  inputPath: string;
  /** 输出文件路径 */
  outputPath: string;
  /** 原始文件大小（字节） */
  originalSize: number;
  /** 转换后文件大小（字节） */
  convertedSize: number;
  /** 压缩率 */
  compressionRatio: number;
  /** 转换耗时（毫秒） */
  processingTime: number;
}
```

## 格式推荐

### Web 应用
- **WebP**: 现代浏览器支持，压缩率高，推荐用于 Web
- **AVIF**: 最新格式，压缩率最高，但浏览器支持有限
- **JPEG**: 通用格式，兼容性最好

### 移动应用
- **WebP**: Android 原生支持，iOS 14+ 支持
- **JPEG**: 通用兼容性

### 打印/专业用途
- **PNG**: 无损压缩，支持透明度
- **TIFF**: 专业格式，支持多种压缩算法

## 性能优化建议

1. **批量处理**: 使用 `batchConvert` 进行批量转换
2. **质量设置**: 根据用途调整质量参数（Web 用 80-85，打印用 90-95）
3. **尺寸优化**: 根据显示需求设置合适的输出尺寸
4. **格式选择**: 优先使用 WebP 或 AVIF 以获得更好的压缩率

## 错误处理

所有函数都会抛出详细的错误信息，建议使用 try-catch 进行错误处理：

```typescript
try {
  const result = await convertImage(inputPath, outputPath, 'webp');
  console.log('转换成功:', result);
} catch (error) {
  console.error('转换失败:', error.message);
}
```

## 注意事项

1. 确保输入文件存在且可读
2. 输出目录会自动创建
3. GIF 格式暂不支持输出
4. 大文件转换可能需要较长时间，建议在后台处理
5. 某些格式转换可能不支持所有选项（如透明度）