@aurouscia/image-compress

客户端图片压缩与缩放工具，支持 Canvas 绘制、object-fit 模式、SVG 转栅格图及自定义输出格式。

功能

• compressImage：将图片（含 SVG）绘制到指定尺寸的 Canvas 上，支持 CSS object-fit 风格的填充模式（contain、cover、fill、none、scale-down）。
• resizeImage：按最大宽高等比缩放图片（含 SVG），画布尺寸等于缩放后的图片尺寸，不会放大。
• 输出格式与质量可调，默认输出 image/webp。
• 支持按目标文件大小自动调整质量（仅 image/jpeg / image/webp）。
• 支持 SVG 输入：自动解析 width、height、viewBox 作为原始尺寸，无尺寸时默认使用 512×512。

安装

npm install @aurouscia/image-compress

使用

compressImage

将图片压缩到固定画布尺寸，使用 objectFit 控制绘制方式：

import { compressImage } from '@aurouscia/image-compress'

const { blob, canvas, quality } = await compressImage(file, {
  width: 300,
  height: 300,
  objectFit: 'contain',
  type: 'image/webp',
  quality: 0.8,
})

resizeImage

按最大尺寸限制等比缩放，不超出限制也不放大：

import { resizeImage } from '@aurouscia/image-compress'

const { blob, canvas, quality } = await resizeImage(file, {
  maxWidth: 1920,
  maxHeight: 1080,
  type: 'image/webp',
  quality: 0.9,
})

目标文件大小

通过 targetSize（字节）让输出文件尽量小于指定大小，仅对 image/jpeg 和 image/webp 有效：

import { compressImage } from '@aurouscia/image-compress'

const { blob, quality } = await compressImage(file, {
  width: 800,
  height: 800,
  targetSize: 100 * 1024, // 目标 100 KB
  minQuality: 0.1,        // 最低可接受质量，默认 0.1
  maxIterations: 10,      // 二分查找最大次数，默认 10
})

选项说明

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | width | number | 原图宽度 | compressImage 专用，画布宽度 | | height | number | 原图高度 | compressImage 专用，画布高度 | | objectFit | ObjectFit | 'contain' | compressImage 专用，绘制模式 | | maxWidth | number | 无限制 | resizeImage 专用，最大宽度 | | maxHeight | number | 无限制 | resizeImage 专用，最大高度 | | type | string | 'image/webp' | 输出 MIME 类型 | | quality | number | 0.8 | 输出质量上限（0 ~ 1），配合 targetSize 时会从该值向下调整 | | targetSize | number | - | 目标文件大小（字节），仅对 image/jpeg / image/webp 有效 | | minQuality | number | 0.1 | 配合 targetSize 使用，最低可接受质量 | | maxIterations | number | 10 | 配合 targetSize 使用，质量二分查找最大迭代次数 |

返回值

两个函数都返回：

{
  blob: Blob,
  canvas: HTMLCanvasElement,
  quality: number, // 实际使用的输出质量
}

设置了 targetSize 时，quality 可能低于传入的 quality。

开发

# 安装依赖
pnpm install

# 构建库
pnpm run build

# 运行演示项目
pnpm run dev

# 运行测试
pnpm run test:run

License

MIT