vue3-cropperjs

Table of contents

• Features
• Getting started
• Options
• Methods
• Events
• License

Features

• 支持触摸（移动）
• 支持缩放
• 支持旋转
• 支持缩放（翻转）
• 支持多种作物
• 支持通过画布在浏览器端裁剪图像
• 支持翻译 Exif 方向信息
• 跨浏览器支持

Getting started

Installation

npm install vue3-cropperjs
yarn add vue3-cropperjs

//组件内使用
import v3Cropper from 'vue3-cropperjs'
import 'vue3-cropperjs/dist/v3cropper.css'

components: {
   v3Cropper
}

main.js里面使用
import v3Cropper from 'vue3-cropperjs'
import 'vue3-cropperjs/dist/v3cropper.css'

app.component('v3-cropper', v3Cropper)

// 需要设置容器的宽高
<v3-cropper
  style="width: 100%;height: 500px"
  :src="options.src"
></v3-cropper>

Options

src

• Type: url 地址 || base64 || blob
• Default: null

裁剪图片的地址

viewMode

• Type: Number
• Default: 0
• Options:
  • 0：无限制
  • 1：限制裁剪框不超过画布的大小。
  • 2：限制最小画布尺寸以适合容器。 如果画布和容器的比例不同，则最小画布将被维度之一的额外空间包围。
  • 3：限制最小画布尺寸以填充适合容器。 如果画布和容器的比例不同，容器将无法在其中一个维度中容纳整个画布。

定义裁剪器的视图模式。 如果将 viewMode 设置为 0，则裁剪框可以扩展到画布之外，而值为“1”、“2”或“3”会将裁剪框限制为画布的大小。 2 或 3 的 viewMode 将额外限制画布到容器。 当画布和容器的比例相同时，2 和 3 之间没有区别。

dragMode

• Type: String
• Default: 'crop'
• Options:
  • 'crop'：创建一个新的裁剪框
  • 'move'：移动画布
  • 'none'：什么也不做

定义裁剪器的拖动模式。

initialAspectRatio

• Type: Number
• Default: NaN

定义裁剪框的初始纵横比。 默认情况下，它与画布（图像包装器）的纵横比相同。

data

• Type: Object
• Default: null

之前存储的裁剪数据将在初始化时自动传递给 setData 方法。

仅在autoCrop选项设置为true时可用。

modal

• Type: Boolean
• Default: true

在图像和裁剪框下方显示黑色模态。

guides

• Type: Boolean
• Default: true

显示裁剪框内部的虚线

center

• Type: Boolean
• Default: true

显示裁剪框中的中心指示灯。

background

• Type: Boolean
• Default: true

显示容器的网格背景。

autoCrop

• Type: Boolean
• Default: true

启用初始化时会自动裁剪图像。

autoCropArea

• Type: Number
• Default: 0.8 (80% of the image)

它应该是0到1之间的数字。定义自动裁剪区域大小（百分比）。

movable

• Type: Boolean
• Default: true

上传图片是否可以移动

rotatable

• Type: Boolean
• Default: true

启用旋转图像。

scalable

• Type: `Boolean
• Default: true

启用以缩放图像。

zoomable

• Type: Boolean
• Default: true

启用以缩放图像。

zoomOnTouch

• Type: Boolean
• Default: true

启用通过拖动触摸来缩放图像的功能。

zoomOnWheel

• Type: Boolean
• Default: true

启用通过鼠标滚轮缩放图像。

wheelZoomRatio

• Type: Number
• Default: 0.1

通过鼠标滚轮缩放图像时定义缩放比例。

cropBoxMovable

• Type: Boolean
• Default: true

启用通过拖动移动裁剪框。

cropBoxResizable

• Type: Boolean
• Default: true

Enable to resize the crop box by dragging.

toggleDragModeOnDblclick

• Type: Boolean
• Default: true

在裁剪器上单击两次时，可以在“裁剪”和“移动”之间切换拖动模式。

Requires dblclick event support.

Methods

内置方法 通过this.$refs.cropper 调用

crop()

手动显示裁剪框。

reset()

将图像和裁切框重置为其初始状态。

clear()

清除裁剪框。

enable()

启用（解冻）裁剪器。

disable()

禁用（冻结）裁剪器。

move(offsetX[, offsetY])

• offsetX:

  • Type: Number
  • 水平方向移动大小（px）。

• offsetY (optional):

  • Type: Number
  • 垂直方向移动大小（px）。
  • 如果不存在，则其默认值为 offsetX。

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

zoom(ratio)

• ratio:
  • Type: Number
  • 放大：需要一个正数 (ratio > 0)
  • 缩小：需要负数 (ratio < 0)

以相对比例缩放画布（图像包装器）。

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

rotate(degree)

• degree:
  • Type: Number
  • 向右旋转：需要一个正数 (degree > 0)
  • 向左旋转：需要负数 (degree < 0)

以相对角度旋转图像。

Requires CSS3 2D Transforms support (IE 9+).

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

getData([rounded])

• rounded (optional):

  • Type: Boolean
  • Default: false
  • Set true获得四舍五入的值。

• (return value):

  • Type: Object
  • Properties:
    • x: 裁剪区域左侧的偏移量
    • y: 裁剪区域的偏移顶部
    • width: 裁剪区域的宽度
    • height: 裁剪区域的高度
    • rotate: 图像的旋转度数
    • scaleX: 应用于图像横坐标的缩放因子
    • scaleY: 应用于图像纵坐标的缩放因子

输出最终裁剪区域的位置和大小数据（基于原始图像的自然大小）。

您可以将数据发送到服务器端直接裁剪图像：

1. 使用 rotate 属性旋转图像。
2. 使用 scaleX 和 scaleY 属性缩放图像。
3. 使用 x、y、width 和 height 属性裁剪图像。

setData(data)

• data:
  • Type: Object
  • Properties: 请参阅 getData 方法。
  • 在传入数据属性之前，您可能需要对其进行舍入。

使用新数据（基于原始图像）更改裁剪区域的位置和大小。

Note: 此方法仅在 viewMode 选项的值大于或等于 1 时可用。

getContainerData()

• (return value):
  • Type: Object
  • Properties:
    • width：容器的当前宽度
    • height：容器的当前高度

输出容器大小数据。

getImageData()

• (return value):
  • Type: Object
  • Properties:
    • left：图像左侧的偏移量
    • top：图像的偏移顶部
    • width：图片的宽度
    • height：图片的高度
    • naturalWidth：图片的自然宽度
    • naturalHeight：图像的自然高度
    • aspectRatio：图像的纵横比
    • rotate：图像旋转后的角度
    • scaleX：缩放后应用于图像横坐标的缩放因子
    • scaleY：缩放时应用于图像纵坐标的缩放因子

输出图像位置、大小等相关数据。

getCanvasData()

• (return value):
  • Type: Object
  • Properties:
    • left：画布左侧的偏移量
    • top：画布顶部的偏移量
    • width：画布的宽度 -height：画布的高度
    • naturalWidth：画布的自然宽度（只读）
    • naturalHeight：画布的自然高度（只读）

输出画布（图像包装器）位置和大小数据。

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

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

setCanvasData(data)

• data:
  • Type: Object
  • Properties:
    • left：画布左侧的新偏移量
    • top：画布的新偏移顶部
    • width：画布的新宽度
    • height：画布的新高度

使用新数据更改画布（图像包装器）的位置和大小。

getCropBoxData()

• (return value):
  • Type: Object
  • Properties:
    • left：裁剪框左侧的偏移量
    • top：裁剪框的顶部偏移
    • width：裁剪框的宽度
    • height：裁剪框的高度

输出裁剪框位置和大小数据。

setCropBoxData(data)

• data:
  • Type: Object
  • Properties:
    • left：裁剪框左侧的新偏移量
    • top：裁剪框的新偏移顶部
    • width：裁剪框的新宽度 -height：裁剪框的新高度

使用新数据更改裁剪框的位置和大小。

getCroppedCanvas([options])

• options (optional):

  • Type: Object

  • Properties:

    • width：输出画布的目标宽度。
    • height：输出画布的目标高度。
    • minWidth：输出画布的最小目标宽度，默认值为'0'。
    • minHeight：输出画布的最小目标高度，默认值为0。
    • maxWidth：输出画布的最大目标宽度，默认值为 Infinity。
    • maxHeight：输出画布的最大目标高度，默认值为 Infinity。
    • fillColor：一种颜色，用于填充输出画布中的所有alpha值，默认值为transparent。
    • imageSmoothingEnabled: 设置为更改图像是否平滑（true，默认值）或不平滑（false）。
    • imageSmoothingQuality: 设置图像平滑的质量，低（默认）、中或高之一。

  • (return value):

    • Type: HTMLCanvasElement
    • A canvas drawn the cropped image.

  • Notes:

    • 输出画布的纵横比将自动适应裁剪框的纵横比。
    • 如果您打算从输出画布中获取 JPEG 图像，则应先设置 fillColor 选项，否则默认情况下 JPEG 图像中的透明部分将变为黑色。
    • 使用浏览器原生的 canvas.toBlob API 来做压缩工作，即**有损压缩 **。 为了获得更好的图像质量，您可以将原始图像和裁剪后的数据上传到服务器并在服务器上进行裁剪工作。

获取绘制裁剪图像的画布（有损压缩）。 如果未裁剪，则返回绘制整个图像的画布。

之后就可以直接将画布显示为图片，或者使用HTMLCanvasElement.toDataURL获取一个Data URL，或使用 HTMLCanvasElement.toBlob 获取 blob 并使用 [FormData](https: //developer.mozilla.org/en-US/docs/Web/API/FormData) 如果浏览器支持这些 API。

this.$refs.cropper.getCroppedCanvas();

this.$refs.cropper.getCroppedCanvas({
  width: 160,
  height: 90,
  minWidth: 256,
  minHeight: 256,
  maxWidth: 4096,
  maxHeight: 4096,
  fillColor: '#fff',
  imageSmoothingEnabled: false,
  imageSmoothingQuality: 'high'
});

// 如果浏览器支持`HTMLCanvasElement.toBlob`，则将裁剪后的图像上传到服务器。
// `toBlob` 的第二个参数的默认值为 'image/png'，如有必要，请更改它。
this.$refs.cropper.getCroppedCanvas().toBlob((blob) => {
  const formData = new FormData();

  // 如有必要，将图像文件名作为第三个参数传递。
  formData.append('croppedImage', blob/*, 'example.png' */);

  // 以`jQuery.ajax` 方法为例
  $.ajax('/path/to/upload', {
    method: 'POST',
    data: formData,
    processData: false,
    contentType: false,
    success() {
      console.log('Upload success');
    },
    error() {
      console.log('Upload error');
    },
  });
}/*, 'image/png' */);

events

ready

插件初始化完成将触发此事件

cropStart

• event.detail.originalEvent:

  • Type: Event
  • Options: pointerdown, touchstart, and mousedown

• event.detail.action:

  • Type: String
  • Options:
    • 'crop': create a new crop box
    • 'move': move the canvas (image wrapper)
    • 'zoom': zoom in / out the canvas (image wrapper) by touch.
    • 'e': resize the east side of the crop box
    • 'w': resize the west side of the crop box
    • 's': resize the south side of the crop box
    • 'n': resize the north side of the crop box
    • 'se': resize the southeast side of the crop box
    • 'sw': resize the southwest side of the crop box
    • 'ne': resize the northeast side of the crop box
    • 'nw': resize the northwest side of the crop box
    • 'all': move the crop box (all directions)

当画布（图像包装器）或裁剪框开始改变时触发此事件。

cropMove

• event.detail.originalEvent:

  • Type: Event
  • Options: pointermove, touchmove, and mousemove.

• event.detail.action: the same as "cropStart".

当画布（图像包装器）或裁剪框发生变化时会触发此事件。

cropEnd

• event.detail.originalEvent:

  • Type: Event
  • Options: pointerup, pointercancel, touchend, touchcancel, and mouseup.

• event.detail.action: the same as "cropStart".

当画布（图像包装器）或裁剪框停止更改时会触发此事件。

crop

• event.detail.x
• event.detail.y
• event.detail.width
• event.detail.height
• event.detail.rotate
• event.detail.scaleX
• event.detail.scaleY

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

当画布（图像包装器）或裁剪框更改时触发此事件。

zoom

• event.detail.originalEvent:

  • Type: Event
  • Options: wheel, pointermove, touchmove, and mousemove.

• event.detail.oldRatio:

  • Type: Number
  • The old (current) ratio of the canvas

• event.detail.ratio:

  • Type: Number
  • The new (next) ratio of the canvas (canvasData.width / canvasData.naturalWidth)

当裁剪器实例开始放大或缩小其画布（图像包装器）时会触发此事件。

<template>
  <v3-cropper
    ref="cropper"
    @ready="ready"
    @cropStart="cropStart"
    @cropMove="cropMove"
    @cropEnd="cropEnd"
    @crop="crop"
    @zoom="zoom"
    style="width: 100%;height: 500px"
    src="https://dss2.bdstatic.com/70cFvnSh_Q1YnxGkpoWK1HF6hhy/it/u=3909434962,3584802110&fm=26&gp=0.jpg"></v3-cropper>
</template>

<script>
export default{
  methods: {
    ready() {},
    cropStart(opt) {},
    cropMove(opt) {},
    cropEnd(opt) {},
    crop(opt) {},
    zoom(opt){}
  }
}
</script>

⬆ back to top

License

MIT © [Liu Yuanshen]