Cropper.js
JavaScript 图片裁剪插件

下载

1.0.0-rc.2 (May 30, 2017)

Cropper.js

JavaScript 图片裁剪插件

目录

特点

目录结构


dist/
├── cropper.css       ( 5 KB)
├── cropper.min.css   ( 4 KB)
├── cropper.js        (90 KB, UMD)
├── cropper.min.js    (33 KB, UMD, compressed)
├── cropper.common.js (90 KB, CommonJS)
└── cropper.esm.js    (90 KB, ES Module)

入门

快速上手

可通过以下四步快速开始:

安装

包含文件:


<link  href="/path/to/cropper.css" rel="stylesheet">
<script src="/path/to/cropper.js"></script>

cdnjs 提供 CDN 服务，包括 Cropper.js 的 CSS 和 JavaScript。你可以从这个链接找到。

用法

用 Cropper 构造器初始化:



<div>
  <img id="image" src="picture.jpg">
</div>
            

/* 限制图片宽度，防止移除容器 */
img {
  max-width: 100%; /* 这个规则非常重要，不要忽视它！ */
}
            

var image = document.getElementById('image');
var cropper = new Cropper(image, {
  aspectRatio: 16 / 9,
  crop: function(e) {
    console.log(e.detail.x);
    console.log(e.detail.y);
    console.log(e.detail.width);
    console.log(e.detail.height);
    console.log(e.detail.rotate);
    console.log(e.detail.scaleX);
    console.log(e.detail.scaleY);
  }
});

常见问题

放大缩小后如何裁切一个新区域？

双击你的鼠标进入裁切模式。

裁切一个区域后如何移动图片？

双击你的鼠标进入移动模式。

如何在自由比例模式下修正宽高比？

当你要重置裁切框的时候，按住 shift 键即可。

在自由比例模式下如何裁切一个正方形区域？

当你在裁切图片时按住 shift 键即可。

注意

已知问题

选项

你可以用 new Cropper(image, options) 来设置cropper 选项。如果你要改变默认全局选项，可以使用 Cropper.setDefaults(options)。

名称 类型 说明
viewMode（视图模式）
  • 类型: Number
  • 默认: 0
 选项:
  • 0: 裁切框只在容器内
  • 1: 裁切框应在canvas内
  • 2: canvas 不应该在容器内
  • 3: 容器应该在 canvas 内

定义 cropper 的视图模式。
dragMode（拖动模式）
  • 类型: String
  • 默认: 'crop'
 选项:
  • 'crop': 创建一个新的裁切框
  • 'move': 移动canvas
  • 'none': 无操作

定义 cropper 的拖动模式。
aspectRatio（宽高比）
  • 类型: Number
  • 默认: NaN

设置裁切框的宽高比。默认情况下，裁切框是自由比例。
data（数据）
  • 类型: Object
  • 默认: null

如果你之前存储过裁切数据，当生成时会自动调用 setData 方法。
preview（预览）

为预览添加额外的元素（容器）

注意:

  • 预览容器的最大宽度就是初始宽度。
  • 预览容器的最大高度就是初始高度。
  • 如果你要设置一个 aspectRatio 选项，先确保设置了和预览容器相同的宽高比。
  • 如果预览未能正确显示，要在预览容器上设置 overflow: hidden 样式。
responsive（响应式）
  • 类型: Boolean
  • 默认: true

当改变窗口大小时重新渲染。
restore（恢复）
  • 类型: Boolean
  • 默认: true

当改变窗口大小时恢复裁切区域。
checkCrossOrigin（检查跨域）
  • 类型: Boolean
  • 默认: true

检查当前图片是否是一个跨域图片。

如果是，当克隆图片时，克隆图片元素会被添加一个 crossOrigin 属性，src 属性会被添加一个时间戳来重新加载原始图片，防止浏览器发生缓存错误。

通过在图片上添加 crossOrigin 属性来阻止时间戳添加到图片的URL上，防止重新加载图片。

如果图片的 crossOrigin 属性是 "use-credentials"，那么 withCredentials 属性会被设置为 true ，当通过 XMLHttpRequest 加载图片数据时。
checkOrientation（判断方向）
  • 类型: Boolean
  • 默认: true

检查当前图片的 Exif Orientation 信息。（包含图片的拍摄相机，时间，拍摄方向等信息，译者注）

更确切的说，读取方向的值用来旋转图片，然后将 Orientation 值设置为 1 (默认值) 防止相同的问题 (1, 2) 在ios设备上。

需要同时设置 rotatable 和 scalable 选项的值为 true。

注意: 始终不要相信这一点，因为一些 JPG 图片的 Orientation 值是不正确的（不标准的）。

Arrays 类型 支持 (IE 10+)。
modal（模态）
  • 类型: Boolean
  • 默认: true

在图片的上面，裁切框的下面显示黑色模态层。
guides（指示）
  • 类型: Boolean
  • 默认: true

在裁切框上面显示虚线。
center（居中）
  • 类型: Boolean
  • 默认: true

在裁切框上面居中显示指针。
highlight（高亮）
  • 类型: Boolean
  • 默认: true

在裁切框上面显示白色模态层 (高亮裁切框)。
background（背景）
  • 类型: Boolean
  • 默认: true

在容器上显示网格。
autoCrop(自动裁切)
  • 类型: Boolean
  • 默认: true

启用后当初始化时自动裁切图片。
autoCropArea（自动裁切区域）
  • 类型: Number
  • 默认: 0.8 (图片的 80%)

一个介于 0 和 1. 之间的数值，来定义裁切区域的大小(百分比)。
movable（可移动）
  • 类型: Boolean
  • 默认: true

启用后可移动图片。
rotatable（可旋转）
  • 类型: Boolean
  • 默认: true

启用后可旋转图片。
scalable（可伸缩）
  • 类型: Boolean
  • 默认: true

启用后可伸缩图片。
zoomable（可缩放）
  • 类型: Boolean
  • 默认: true

启用后可缩放图片。
zoomOnTouch（触摸缩放）
  • 类型: Boolean
  • 默认: true

启用后可通过触摸拖动来缩放图片。
zoomOnWheel（滚轮缩放）
  • 类型: Boolean
  • 默认: true

启用后可通过鼠标滚轮来缩放图片。
wheelZoomRatio（滚轮缩放比）
  • 类型: Number
  • 默认: 0.1

定义当通过鼠标滚轮缩放图片时的缩放比例。
cropBoxMovable（裁切框可移动）
  • 类型: Boolean
  • 默认: true

启用后当拖动时可移动裁切框。
cropBoxResizable（裁切框大小可改变）
  • 类型: Boolean
  • 默认: true

启用后当拖动时可改变裁切框的大小。
toggleDragModeOnDblclick（双击切换裁切模式）
  • 类型: Boolean
  • 默认: true

启用后，当在cropper上双击时，可在 "crop" 和 "move" 模式之间切换。
minContainerWidth（最小容器宽度）
  • 类型: Number
  • 默认: 200

容器的最小宽度。
minContainerHeight（最小容器高度）
  • 类型: Number
  • 默认: 100

容器的最小高度。
minCanvasWidth（最小canvas宽度）
  • 类型: Number
  • 默认: 0

canvas的最小宽度 (图片容器)。
minCanvasHeight（最小canvas高度）
  • 类型: Number
  • 默认: 0

canvas的最小高度 (图片容器)。
minCropBoxWidth（最小裁切框宽度）
  • 类型: Number
  • 默认: 0

裁切框的最小宽度。

注意: 这个大小是相对于页面，而不是图片。
minCropBoxHeight（最小裁切框高度）
  • 类型: Number
  • 默认: 0

裁切框的最小高度。

注意: 这个大小是相对于页面，而不是图片。
ready
  • 类型: Function
  • 默认: null

一个 "ready" 事件的快捷方式。
cropstart
  • 类型: Function
  • 默认: null

一个 "cropstart" 事件的快捷方式
cropmove
  • 类型: Function
  • 默认: null

一个 "cropmove" 事件的快捷方式。
cropend
  • 类型: Function
  • 默认: null

一个 "cropend" 事件的快捷方式。
crop
  • 类型: Function
  • 默认: null

一个 "crop" 事件的快捷方式。
zoom
  • 类型: Function
  • 默认: null

一个 "zoom" 事件的快捷方式。

方法

因此在加载图片时有一个 异步 进程，你 会调用到绝大多数方法，在ready之后, 除了 "setAspectRatio", "replace" 和 "destroy"。

如果一个方法不需要任何返回值，它会返回 cropper 实例 (this) 来进行链式结构。


new Cropper(image, {
  ready: function () {
    // this.cropper[method](argument1, , argument2, ..., argumentN);
    this.cropper.move(1, -1);

    // 允许链式结构
    this.cropper.move(1, -1).rotate(45).scale(1, -1);
  }
});

crop()

手动显示裁切框。


new Cropper(image, {
  autoCrop: false,
  ready: function () {
    // Do something here
    // ...

    // And then
    this.cropper.crop();
  }
});

reset()

重置图片和裁切框到初始状态。

clear()

清除裁切框。

replace(url[, onlyColorChanged])

替换图片的src并重新构建 cropper。

enable()

启用（解冻） cropper。

disable()

禁用 （冻结）cropper。

destroy()

销毁 cropper 并从图片中移除实例。

move(offsetX[, offsetY])

移动 canvas (图片容器) 相对偏移。


cropper.move(1);
cropper.move(1, 0);
cropper.move(0, -1);

moveTo(x[, y])

移动 canvas (图片容器)到一个绝对的点。

zoom(ratio)

以一个相对的比例缩放 canvas（图片容器）。


cropper.zoom(0.1);
cropper.zoom(-0.1);

zoomTo(ratio)

缩放canvas (图片容器) 到一个绝对的比例。


cropper.zoomTo(1); // 1:1 (canvasData.width === canvasData.naturalWidth)

rotate(degree)

旋转图片到一个相对的角度。

依赖 CSS3 2D Transforms 支持 (IE 9+).


cropper.rotate(90);
cropper.rotate(-90);

rotateTo(度)

旋转图片到一个绝对的度数。

scale(scaleX[, scaleY])

缩放图片。

依赖 CSS3 2D Transforms 支持 (IE 9+)。


cropper.scale(-1); // Flip both horizontal and vertical
cropper.scale(-1, 1); // Flip horizontal
cropper.scale(1, -1); // Flip vertical

scaleX(scaleX)

缩放图片的横坐标。

scaleY(scaleY)

缩放图片的纵坐标。

getData([rounded])

输出最终裁切区域的位置和尺寸数据 (基于原图片的自然大小)。

你可以直接将裁切图片发送到服务器端。

A schematic diagram for data's properties

setData(data)

用新数据改变裁切区域的位置和大小 (基于原始图片)。

注意: 仅当viewMode模式选项的值大于或等于1时，该方法可用。

getContainerData()

输出容器的尺寸数据。

A schematic diagram for cropper's layers

getImageData()

输出图片的位置，尺寸和其他相关数据。

getCanvasData()

输出canvas (图片容器) 位置和尺寸数据。


var imageData = cropper.getImageData();
var canvasData = cropper.getCanvasData();

if (imageData.rotate % 180 === 0) {
  console.log(canvasData.naturalWidth === imageData.naturalWidth); // true
}

setCanvasData(data)

用新数据改变canvas (图片容器) 的位置和尺寸。

getCropBoxData()

输出裁切框的位置和尺寸数据。

setCropBoxData(data)

用新数据改变裁切框的位置和尺寸。

getCroppedCanvas([options])

得到一个绘制裁切图片的canvas。如果没有裁切，将返回整个canvas。

然后，你可以直接将canvas作为一个图片展示，或者用 HTMLCanvasElement.toDataURL 得到一个 Data URL, 或者用 HTMLCanvasElement.toBlob 得到一个 blob 对象，然后使用 FormData 将它上传到服务器，前提是浏览器支持这项 API。


cropper.getCroppedCanvas();

cropper.getCroppedCanvas({
  width: 160,
  height: 90,
  beforeDrawImage: function(canvas) {
    const context = canvas.getContext('2d');

    context.imageSmoothingEnabled = false;
    context.imageSmoothingQuality = 'high';
  },
});

// Upload cropped image to server if the browser supports `HTMLCanvasElement.toBlob`
cropper.getCroppedCanvas().toBlob(function (blob) {
  var formData = new FormData();

  formData.append('croppedImage', blob);

  // Use `jQuery.ajax` method
  $.ajax('/path/to/upload', {
    method: "POST",
    data: formData,
    processData: false,
    contentType: false,
    success: function () {
      console.log('Upload success');
    },
    error: function () {
      console.log('Upload error');
    }
  });
});

setAspectRatio(aspectRatio)

改变裁切框的宽高比。

setDragMode([mode])

改变拖动模式。

提醒: 你可以在cropper 上双击来切换 "crop" 和 "move" 模式。

事件

ready

这个事件会在目标图片已经加载好并且 cropper 实例已经就绪。


var cropper;

image.addEventListener('ready', function () {
  console.log(this.cropper === cropper);
  // -> true
});

cropper = new Cropper(image);

cropstart

这个事件会在canvas (图片容器) 或者裁切框开始改变的时候触发。


image.addEventListener('cropstart', function (e) {
  console.log(e.detail.originalEvent);
  console.log(e.detail.action);
});

cropmove

这个事件会在canvas (图片容器) 或者裁切框正在改变的时候触发。

cropend

这个事件会在canvas (图片容器) 或者裁切框停止改变的时候触发。

crop

关于这些属性，参见 getData 方法。

This event fires when the canvas (image wrapper) or the crop box changed.

zoom

这个事件会在一个cropper实例开始缩放 canvas（图片容器）时触发。


image.addEventListener('zoom', function (e) {

  // Zoom in
  if (e.detail.ratio > e.detail.oldRatio) {
    e.preventDefault(); // Prevent zoom in
  }

  // Zoom out
  // ...
});

避免冲突

如果在同一个命名空间内必须用其它裁切插件, 只需要调用一下 Cropper.noConflict 静态方法还原即可。

浏览器支持

贡献

请通读我们的 contributing guidelines。

Versioning

Maintained under the Semantic Versioning guidelines.

License

MIT © Fengyuan Chen

Related projects