Compressor.js

JavaScript image compressor. Uses the Browser’s native HTMLCanvasElement.toBlob() 方法来做压缩工作，这意味着它是有损压缩, 异步, 并且 has 不同浏览器中的不同压缩效果.通常，在上传图像之前，请使用它在客户端对其进行预压缩。

• Website

目录

• 主文件
• 入门指南
• 选项
• 方法
• 无冲突
• 浏览器支持
• 贡献
• 版本控制
• 授权许可

Main Files

1
2
3
4
5
dist/
├── compressor.js        (UMD)
├── compressor.min.js    (UMD, compressed)
├── compressor.common.js (CommonJS, default)
└── compressor.esm.js    (ES Module)

Getting started

安装

1
npm install compressorjs

使用说明

语法

1
new Compressor(file[, options])

file

• 类型： File 或者 Blob

的 target image file for compressing.

options

• Type: Object
• 自选

压缩选项。查看可用的 options.

例

1
<input type="file">

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import axios from 'axios';
import Compressor from 'compressorjs';
 
document.getElementById('file').addEventListener('change', (e) => {
  const file = e.target.files[0];
 
  if (!file) {
    return;
  }
 
  new Compressor(file, {
    质量: 0.6,
 
    // The compression process is asynchronous,
    // which means you have to access the `result` in the `success` hook function.
    success（结果） {
      const formData = new FormData();
 
      // The third parameter is required for server
      formData.append('file', result, result.name);
 
      // Send the compressed image file to server with XMLHttpRequest.
      axios.post('/path/to/upload', formData).then(() => {
        console.log('Upload success');
      });
    },
    错误（错误） {
      console.log(err.message);
    },
  });
 
});

⬆ back to top

Options

您可以使用以下命令设置压缩器选项 new Compressor(file, options).
如果要更改全局默认选项，您可以使用 Compressor.setDefaults(options).

严格

• Type: boolean
• 违约： true

表示当压缩图像的大小大于原始图像时，是否输出原始图像而不是压缩图像，但以下情况除外：

• The 保留Exif 选项设置为true.
• The mime类型 选项，并且其值与图像的 MIME 类型不同。
• The 宽度 选项，其值大于图像的自然宽度。
• The 高度 选项，其值大于图像的自然高度。
• The 最小宽度 option is set and its value is greater than the natural width of the image.
• The 最小高度 option is set and its value is greater than the natural height of the image.
• The 最大宽度 选项，其值小于图像的自然宽度。
• The 最大高度 选项，其值小于图像的自然高度。

checkOrientation

• Type: boolean
• Default: true

Indicates whether to read the image’s Exif Orientation value (JPEG image only)，和 then rotate or flip the image automatically with the value.

笔记：

• 不要一直相信这一点，因为某些 JPEG 图像具有不正确（非标准）方向值。
• 如果目标图像的大小太大（例如，大于 10 MB），则应禁用此选项以避免内存不足崩溃。
• 图像的 Exif 信息将在压缩后被删除，因此如果您需要 Exif 信息，您可能还需要上传原始图像。

retainExif

• Type: boolean
• Default: false

表示压缩后是否保留图像的Exif信息。

maxWidth

• Type: number
• Default: Infinity

输出图像的最大宽度。该值应大于 0.

Avoid getting a blank output image, you might need to set the maxWidth and maxHeight 选项到有限的数量，因为the size limits of a canvas element，推荐使用 4096 或更少。

maxHeight

• Type: number
• Default: Infinity

输出图像的最大高度。该值应大于 0.

minWidth

• Type: number
• Default: 0

输出图像的最小宽度。该值应大于 0 并且不应大于maxWidth.

minHeight

• Type: number
• Default: 0

输出图像的最小高度。该值应大于 0 and should not be greater than the maxHeight.

width

• Type: number
• Default: undefined

输出图像的宽度。如果未指定，则将使用原始图像的自然宽度，或者如果 height 选项，则宽度将按自然纵横比自动计算。

height

• Type: number
• Default: undefined

输出图像的高度。如果未指定，则将使用原始图像的自然高度，或者如果 width 选项，则高度将通过自然纵横比自动计算。

调整

• Type: string
• Default: "none"
• 选项： "none", "contain", and "cover".

设置如何将图像的大小调整为 width and height 选项。

注意: 仅当width and height 选项。

quality

• Type: number
• Default: 0.8

输出图像的质量。它必须是介于 0 and 1.如果此参数是其他任何参数，则默认值 0.92 and 0.80 用于image/jpeg and image/webp 分别。其他参数将被忽略。小心使用1 因为它可能会使输出图像的大小变大。

Note: 此选项仅适用于image/jpeg and image/webp 图像。

Check out the documentation of the HTMLCanvasElement.toBlob() 方法了解更多详情。

示例:

质量	输入大小	输出大小	压缩比	描述
0	2.12 兆字节	114.61 KB	94.72%	-
0.2	2.12 MB	349.57 KB	83.90%	-
0.4	2.12 MB	517.10 KB	76.18%	-
0.6	2.12 MB	694.99 KB	67.99%	推荐
0.8	2.12 MB	1.14 兆字节	46.41%	Recommend
1	2.12 MB	2.12 MB	0%	不推荐
南	2.12 MB	2.01 兆字节	5.02%	-

mimeType

• Type: string
• Default: 'auto'
• Options: "auto", "image/png", "image/jpeg", and "image/webp".

输出图像的 MIME 类型。默认情况下，将使用源图像文件的原始 MIME 类型。

Note: Safari 不支持mimeType 转换为"image/webp".有关更多详细信息，请参阅 browser compatibility of the HTMLCanvasElement.toBlob() method.

转换类型

• Type: Array or string （多种类型应用逗号分隔）
• Default: ["image/png"]
• 例子：
  • ["image/png", "image/webp"]
  • "image/png,image/webp"

文件类型包含在此列表中且文件大小超过 转换大小 值将转换为 JPEG。

For image file type support, see the Image file type and format guide.

convertSize

• Type: number
• Default: 5000000 (5 兆字节)

文件类型包含在 convertTypes 列表，其文件大小超过此值将转换为 JPEG。要禁用此功能，只需将值设置为Infinity.

Examples:

convertSize	输入尺寸（类型）	输出尺寸（类型）	Compression ratio
5 MB	1.87 MB （PNG）	1.87 MB (PNG)	0%
5 MB	5.66 MB （PNG）	450.24 KB （JPEG）	92.23%
5 MB	9.74 MB （PNG）	883.89 KB （JPEG）	91.14%

beforeDraw（上下文，画布）

• Type: Function
• Default: null
• 参数：
  • context：画布的 2D 渲染上下文。
  • canvas：用于压缩的画布。

在将图像绘制到画布中进行压缩之前要执行的钩子函数。

1
2
3
4
5
6
7
new Compressor(file, {
  beforeDraw(context, canvas) {
    context.fillStyle = '#fff';
    context.fillRect(0, 0, canvas.width, canvas.height);
    context.filter = 'grayscale(100%)';
  },
});

drew（上下文，画布）

• Type: Function
• Default: null
• Parameters:
  • context: The 2d rendering context of the canvas.
  • canvas: The canvas for compression.

将图像绘制到画布中进行压缩后执行的钩子函数。

1
2
3
4
5
6
7
new Compressor(file, {
  drew(context, canvas) {
    context.fillStyle = '#fff';
    context.font = '2rem serif';
    context.fillText('watermark', 20, canvas.height - 20);
  },
});

success(result)

• Type: Function
• Default: null
• Parameters:
  • result：压缩图像（ File (只读） 或 Blob 对象）。

成功压缩图像时要执行的钩子函数。

error(err)

• Type: Function
• Default: null
• Parameters:
  • err：压缩误差（ Error object).

hook 函数在压缩图像失败时执行。

⬆ back to top

Methods

中止（）

中止压缩过程。

1
2
3
4
const compressor = new Compressor(file);
 
// Do something...
compressor.abort();

No conflict

如果您必须使用具有相同命名空间的另一个压缩器，只需调用 Compressor.noConflict static 方法来恢复它。

1
2
3
4
5
6
<script src="other-compressor.js">script>
<script src="compressor.js">script>
<script>
  Compressor.noConflict();
  // Code that uses other `Compressor` can follow here.
script>

Browser support

• Chrome（最新）
• Firefox（最新）
• Safari（最新）
• 歌剧（最新）
• 边缘（最新）
• Internet Explorer 10+

Contributing

请通读我们的 contributing guidelines.

Versioning

根据 Semantic Versioning guidelines.

License

MIT © Chen Fengyuan

⬆ back to top