xk-image-compressor

一个浏览器端图片压缩工具，适用于上传前压缩图片的场景。

它支持：

• 上传前压缩 File
• 可选限制图片宽高
• 可选添加平铺文字水印
• 返回一个可直接上传的新 File

安装

npm install xk-image-compressor

使用方式

这个包同时支持 JavaScript 和 TypeScript 项目。

支持以下导入方式：

• import { compressForUpload } from "..."
• const { compressForUpload } = require("...")

基础示例

TypeScript / ESM

import { compressForUpload } from "xk-image-compressor";

async function handleUpload(file: File) {
  const compressedFile = await compressForUpload(file, {
    quality: 0.8,
    maxWidth: 1920,
    maxHeight: 1920,
    outputType: "image/jpeg"
  });

  const formData = new FormData();
  formData.append("file", compressedFile);

  await fetch("/api/upload", {
    method: "POST",
    body: formData
  });
}

JavaScript / ESM

import { compressForUpload } from "xk-image-compressor";

async function handleUpload(file) {
  const compressedFile = await compressForUpload(file, {
    quality: 0.8,
    maxWidth: 1920,
    maxHeight: 1920,
    outputType: "image/jpeg"
  });

  const formData = new FormData();
  formData.append("file", compressedFile);

  return fetch("/api/upload", {
    method: "POST",
    body: formData
  });
}

JavaScript / CommonJS

const { compressForUpload } = require("xk-image-compressor");

async function handleUpload(file) {
  return compressForUpload(file, {
    quality: 0.8,
    maxWidth: 1600,
    maxHeight: 1600,
    outputType: "image/jpeg"
  });
}

获取完整压缩结果信息

import { compressImage } from "xk-image-compressor";

const result = await compressImage(file, {
  quality: 85,
  outputType: "image/jpeg",
  fileNameSuffix: "-compressed",
  watermark: {
    text: "internal use only",
    opacity: 30,
    angle: -25,
    fontSize: 24,
    color: "#888888"
  }
});

console.log(result.originalSize);
console.log(result.compressedSize);
console.log(result.compressionRate);
console.log(result.file);

上传组件里的 beforeUpload 示例

import { compressForUpload } from "xk-image-compressor";

export async function beforeUpload(file: File) {
  return compressForUpload(file, {
    quality: 0.82,
    maxWidth: 1600,
    maxHeight: 1600
  });
}

Vue + Element Plus 接入示例

<script setup lang="ts">
import { ElMessage } from "element-plus";
import { compressForUpload } from "xk-image-compressor";

async function beforeUpload(rawFile: File) {
  try {
    return await compressForUpload(rawFile, {
      quality: 0.82,
      maxWidth: 1600,
      maxHeight: 1600,
      outputType: "image/jpeg",
      fileNameSuffix: "-compressed"
    });
  } catch (error) {
    ElMessage.error("图片压缩失败");
    return false;
  }
}
</script>

<template>
  <el-upload
    action="/api/upload"
    :before-upload="beforeUpload"
  >
    <el-button type="primary">上传图片</el-button>
  </el-upload>
</template>

对应示例文件：

• examples/element-plus-upload-demo.vue
• examples/element-plus-before-upload.ts

React + antd Upload 接入示例

import { message, Upload, Button } from "antd";
import type { UploadProps } from "antd";
import { compressForUpload } from "xk-image-compressor";

const beforeUpload: UploadProps["beforeUpload"] = async (file) => {
  try {
    return await compressForUpload(file as File, {
      quality: 0.8,
      maxWidth: 1600,
      maxHeight: 1600,
      outputType: "image/jpeg",
      fileNameSuffix: "-compressed"
    });
  } catch (error) {
    message.error("图片压缩失败");
    return Upload.LIST_IGNORE;
  }
};

export function ImageUploader() {
  return (
    <Upload action="/api/upload" beforeUpload={beforeUpload}>
      <Button>上传图片</Button>
    </Upload>
  );
}

对应示例文件：

• examples/antd-upload-demo.tsx
• examples/antd-before-upload.ts

包内示例文件

你也可以直接复制这些现成示例：

• examples/native-upload.ts
• examples/element-plus-before-upload.ts
• examples/antd-before-upload.ts
• examples/element-plus-upload-demo.vue
• examples/antd-upload-demo.tsx
• examples/native-upload.js
• examples/element-plus-before-upload.js
• examples/antd-before-upload.js
• examples/commonjs-before-upload.cjs

返回结果

compressImage(fileOrBlob, options) 会返回：

• file
• blob
• dataUrl
• originalSize
• compressedSize
• compressionRate
• originalWidth
• originalHeight
• width
• height
• originalType
• outputType
• wasCompressed

API

compressForUpload(file, options)

压缩图片并返回新的 File，适合直接拿去上传。

compressImage(fileOrBlob, options)

压缩图片并返回更完整的结果对象。

参数类型

type SupportedOutputType = "image/jpeg" | "image/png";

interface WatermarkOptions {
  text: string;
  angle?: number;
  opacity?: number;
  fontSize?: number;
  color?: string;
  fontFamily?: string;
  gapX?: number;
  gapY?: number;
}

interface CompressImageOptions {
  quality?: number;
  outputType?: SupportedOutputType;
  maxWidth?: number;
  maxHeight?: number;
  fileName?: string;
  fileNameSuffix?: string;
  backgroundColor?: string;
  returnOriginalIfLarger?: boolean;
  watermark?: WatermarkOptions;
}

说明

• quality 同时支持 0.8 和 80 两种写法。
• image/png 的压缩效果依赖浏览器实现，通常不如 image/jpeg 明显。
• 透明图片如果输出成 image/jpeg，默认会补白色背景。
• 这个包面向浏览器环境，不是给 Node.js 服务端压缩用的。
• 发布产物同时包含 ESM、CommonJS 和 TypeScript 类型声明。

本地开发

npm install
npm run build