xyxiao001 / vue-cropper

A simple picture clipping plugin for vue

vue-cropper

一个优雅的图片裁剪插件

[ 查看演示 Demo ]
[ README_english ]
[ 更新日志 ]

一、安装使用

1. 安装

# npm 安装
npm install vue-cropper

# yarn 安装
yarn add vue-cropper

如果你没有使用 npm

在线例子vue-cropper + vue.2x

在线例子vue-cropper@next + vue.3x

服务器渲染 nuxt 解决方案 设置为 ssr: false

module.exports = {
  ...
  build: {
    vendor: [
      'vue-cropper
    ...
    plugins: [
      { src: '~/plugins/vue-cropper', ssr: false }
    ]
  }
}

2. 引入 Vue Cropper

Vue 3 组件内引入

npm install vue-cropper@next
import 'vue-cropper/dist/index.css'
import { VueCropper }  from "vue-cropper";

Vue3 全局引入

import VueCropper from 'vue-cropper'; 
import 'vue-cropper/dist/index.css'

const app = createApp(App)
app.use(VueCropper)
app.mount('#app')

Vue3 CDN 方式引入

<style type="text/css" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.css"></style> 

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vue.global.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vue-cropper.umd.js"></script>
const app = Vue.createApp({...});
app.component('vue-cropper', window['vue-cropper'].VueCropper);

Vue2 组件内引入

import { VueCropper }  from 'vue-cropper' 
components: {
  VueCropper
}

Vue2 全局引入

import VueCropper from 'vue-cropper'
Vue.use(VueCropper)

Vue2 CDN 方式引入

<script src="//cdn.jsdelivr.net/npm/[email protected]/dist/index.js"></script>

Vue.use(window['vue-cropper'].default)

nuxt 引入方式

if(process.browser) {
  vueCropper = require('vue-cropper')
  Vue.use(vueCropper.default)
}

3. 代码中使用

重要！ 需要关掉本地的 mock 服务， 不然图片转化会报错 重要！ 需要使用外层容器包裹并设置宽高

<vueCropper
  ref="cropper"
  :img="option.img"
  :outputSize="option.size"
  :outputType="option.outputType"
></vueCropper>

二、文档

1. props

目前还不知道什么原因项目里面开启 mock 会导致 file 报错，建议使用时关掉 mock

名称	功能	默认值	可选值
img	裁剪图片的地址	空	url 地址, base64, blob
outputSize	裁剪生成图片的质量	1	0.1 ~ 1
outputType	裁剪生成图片的格式	jpg (jpg 需要传入jpeg)	jpeg, png, webp
info	裁剪框的大小信息	true	true, false
canScale	图片是否允许滚轮缩放	true	true, false
autoCrop	是否默认生成截图框	false	true, false
autoCropWidth	默认生成截图框宽度	容器的 80%	0 ~ max
autoCropHeight	默认生成截图框高度	容器的 80%	0 ~ max
fixed	是否开启截图框宽高固定比例	false	true, false
fixedNumber	截图框的宽高比例, 开启fixed生效	[1, 1]	[ 宽度 , 高度 ]
full	是否输出原图比例的截图	false	true, false
fixedBox	固定截图框大小	不允许改变	false
canMove	上传图片是否可以移动	true	true, false
canMoveBox	截图框能否拖动	true	true, false
original	上传图片按照原始比例渲染	false	true, false
centerBox	截图框是否被限制在图片里面	false	true, false
high	是否按照设备的dpr 输出等比例图片	true	true, false
infoTrue	true 为展示真实输出图片宽高 false 展示看到的截图框宽高	false	true, false
maxImgSize	限制图片最大宽度和高度	2000	0 ~ max
enlarge	图片根据截图框输出比例倍数	1	0 ~ max(建议不要太大不然会卡死的呢)
mode	图片默认渲染方式	contain	contain , cover, 100px, 100% auto
limitMinSize	裁剪框限制最小区域	10	Number, Array, String
fillColor	导出时背景颜色填充	空	#ffffff, white

2. 可用回调方法

• @realTime 实时预览事件
• @imgMoving 图片移动回调函数
• @cropMoving 截图框移动回调函数
• @imgLoad 图片加载的回调, 返回结果 success, error

@realTime 实时预览事件

realTime(data) {
  var previews = data
  var h = 0.5
  var w = 0.2

  this.previewStyle1 = {
    width: previews.w + "px",
    height: previews.h + "px",
    overflow: "hidden",
    margin: "0",
    zoom: h
  }

  this.previewStyle2 = {
    width: previews.w + "px",
    height: previews.h + "px",
    overflow: "hidden",
    margin: "0",
    zoom: w
  }

  // 固定为 100 宽度
  this.previewStyle3 = {
    width: previews.w + "px",
    height: previews.h + "px",
    overflow: "hidden",
    margin: "0",
    zoom: 100 / preview.w
  }

  // 固定为 100 高度
  this.previewStyle4 = {
    width: previews.w + "px",
    height: previews.h + "px",
    overflow: "hidden",
    margin: "0",
    zoom: 100 / preview.h
  }
  this.previews = data
}

<div class="show-preview" :style="{'width': previews.w + 'px', 'height': previews.h + 'px',  'overflow': 'hidden',
    'margin': '5px'}">
  <div :style="previews.div">
    <img :src="option.img" :style="previews.img">
  </div>
</div>
<p>中等大小</p>
<div :style="previewStyle1"> 
  <div :style="previews.div">
    <img :src="previews.url" :style="previews.img">
  </div>
</div>

<p>迷你大小</p>
<div :style="previewStyle2"> 
  <div :style="previews.div">
    <img :src="previews.url" :style="previews.img">
  </div>
</div>

@imgMoving 图片移动回调函数

返回的参数内容

{
   moving: true, // moving 是否在移动
   axis: {
     x1: 1, // 左上角
     x2: 1，// 右上角
     y1: 1，// 左下角
     y2: 1 // 右下角
   }
 }

@cropMoving 截图框移动回调函数

返回的参数内容

{
   moving: true, // moving 是否在移动
   axis: {
     x1: 1, // 左上角
     x2: 1，// 右上角
     y1: 1，// 左下角
     y2: 1 // 右下角
   }
 }

2. 内置方法 和 属性

通过 this.$refs.cropper 调用

属性

属性	说明
this.$refs.cropper.cropW	截图框宽度
this.$refs.cropper.cropH	截图框高度

方法

方法	说明
this.$refs.cropper.startCrop()	开始截图
this.$refs.cropper.stopCrop()	停止截图
this.$refs.cropper.clearCrop()	清除截图
this.$refs.cropper.changeScale()	修改图片大小 正数为变大 负数变小
this.$refs.cropper.getImgAxis()	获取图片基于容器的坐标点
this.$refs.cropper.getCropAxis()	获取截图框基于容器的坐标点
this.$refs.cropper.goAutoCrop	自动生成截图框函数
this.$refs.cropper.rotateRight()	向右边旋转90度
this.$refs.cropper.rotateLeft()	向左边旋转90度

获取截图内容

获取截图的 base64 数据

this.$refs.cropper.getCropData(data => {
  // do something
  console.log(data)  
})

获取截图的 blob 数据

this.$refs.cropper.getCropBlob(data => {
  // do something
  console.log(data)  
})

三、相关文章参考

• shn_ui - vue-cropper - 野宁新之助
• vue全家桶开发管理后台—裁切图片 - 麻球科技-菅双鹏
• Vue-cropper 图片裁剪的基本原理 - 龙恩0707
• 关于昵称和头像的总结（模仿微信） - 秋晨光
• vue-cropper-h5 - 居里栈栈

四、交流

有什么意见，或者 bug，或者想一起开发 vue-cropper， 或者想一起开发其他插件

vue-cropper's Issues

指定截图尺寸大小

当按原图比例输出时（即 props = true）
1、指定截图尺寸大小
2、指定截图的最大宽度，当截图宽度大于最大宽度时，按照最大宽度输出

Translate Docs

Translate docs to English please. Thanks.

可否提供属性，让截图框为圆形。

【移动端】高亮图与后面真实图位置出现偏差

上传图片较小时不能放满容器，出现高亮图向右偏差。能否解决或将图片铺满全屏，谢谢！

在苹果手机上，第一次要双击才会触发！

大神，你看看呢

没有点击上传图片功能？只能写死照片路径吗

如题

Uncaught ReferenceError: n is not defined

到我们的环境里提示语如下。Uncaught ReferenceError: n is not defined

能否支持移动端手势自定义旋转呢?

如果有的话就更加完美了!

您好，这个插件支持移动端么？另外getCropData()返回的是裁剪的信息，还是裁剪后的base64编码？

ios拍照之后无法显示在剪辑图片容器中？

1.拍完照之后，报错canvas.toBlob is not a function
pfnet/PaintsChainer#51
尝试了下vue-cropper依赖exif-js降级到2.2.0版本也不会报错，但是还是会出现下面的问题

2.用这个方法解决后，没有报错，但是还是无法在剪辑局域正常显示所拍照片

测试机型：iPhone5s(IOS 8.1)、iPhone 7 plus(IOS10.3.3)

能否让大尺寸的图片按照原始尺寸初始化？

能否让大尺寸的图片按照原始尺寸初始？或者是50%放大倍数初始化。。

这里有个需求是，用户用手机对着桌子上的文件拍照，然后通过这个上传。部分用户不会去缩放，直接传上来了。原本手机拍出来一个1920X1080的图 变长了一个极小的图。所有的文字都看不清。所以 如果这个插件能实现，当用户选择了图片之后，展示给用户的是一张放大了的，用户就会自己去选择需要截图的位置。

一开始是隐藏的，然后点击弹窗显示图片，但是显示出来不能使用

如题

除了服务器端解决资源跨域 还有没其他办法解决

除了服务器端解决资源跨域 还有没其他办法解决

为什么我的图片传不上去呢

设置截图宽高比无效

设置canScale: false,
autoCrop: true,
// 只有自动截图开启 宽度高度才生效
autoCropWidth: 320,
autoCropHeight: 200,
// 开启宽度和高度比例
fixed: true,
fixedNumber: [1, 1]

插件可以批量上传吗？我有点没懂呢！

插件可以批量上传吗？我有点没懂呢！

安装这个依赖之后，项目会报错，移除之后就正常了，up主，注意下。

苹果7p，6p手机，对于拍照的图片裁切，导致页面重新加载

6s没有这个问题，7p和6p上面问题比较明显。demo上也有这个问题，微信浏览器里拍照上传进行裁剪，会导致页面重新加载。safari里会提示页面出现错误，重新载入。

小图片剪裁时错位

你可以找一张小图试试，比如200x200的图。剪裁时 明图会跟暗图错开

容器内显示不对啊

为什么我用的会是这个样子呢？？

.avatar-box {
            position: relative;
            height: 500px;
        }
<div class="avatar-box">
                    <VueCropper ref="cropper"
                    :img="option.img"
                    :autoCrop="true"
                    :outputType="option.outputType"></VueCropper>
                </div>

设置vue-cropper有点问题，能不能帮我看下是哪里出现的问题？

<template>
  <div class="edit-teacher-container">
        <Card>
                <div slot="title">
                    <Button type="text" icon="reply" @click.native="returnTeacherPage">返回</Button>
                </div>          
                <Button slot="extra" type="primary" icon="plus-round" @click.native="saveTeacher">保存</Button>
                <Row :gutter="16">
                    <Col span="10">
                        <Card style="height:500px">
                            <p slot="title">
                                <Icon type="person"></Icon>
                                设置老师头像
                            </p>
                                <Button type="primary" @click="modal1 = true">上传文件</Button>


                        </Card>
                    </Col>
                </Row>
        </Card>

        <Modal
            v-model="modal1"
            title="设置老师头像"
            width=800
            @on-ok="ok"
            @on-cancel="cancel">
            <vueCropper
                ref="cropper2"
                :img="example2.img"
                :outputSize="example2.size"
                :outputType="example2.outputType"
                :info="example2.info"
                :canScale="example2.canScale"
                :autoCrop="example2.autoCrop"
                :autoCropWidth="example2.width"
                :autoCropHeight="example2.height"
                :fixed="example2.fixed"
                :fixedNumber="example2.fixedNumber"
            ></vueCropper>
    </Modal>
  </div>
</template>
<script>
import vueCropper from 'vue-cropper'


export default {
    components:{
        vueCropper
    },
data () {
    return {
        modal1: false,
        example2: {
				img: 'http://ofyaji162.bkt.clouddn.com/bg1.jpg',
				info: true,
				size: 1,
				outputType: 'jpeg',
				canScale: false,
				autoCrop: true,
				// 只有自动截图开启 宽度高度才生效
				autoCropWidth: 300,
				autoCropHeight: 300,
				// 开启宽度和高度比例
				fixed: true,
				fixedNumber: [1, 1]
			}
    }
}
</script>

希望添加背景色支持

在我使用透明png图片的时候， 默认切割出来的是黑色背景色，
应该很多人都存在需要透明背景色的需求吧，如下图所示

为什么显示vueCropper is not defined

我先install然后import了，结果报这个错

不能等比例缩放截图框? 宽高一比一

html

                     <VueCropper
                            ref="cropper"
                            :img="example2.img"
                            :outputSize="example2.size"
                            :outputType="example2.outputType"
                            :info="example2.info"
                            :canScale="example2.canScale"
                            :autoCrop="example2.autoCrop"
                            :autoCropWidth="example2.width"
                            :autoCropHeight="example2.height"
                    ></VueCropper>

js

                    img: 'http://ofyaji162.bkt.clouddn.com/bg1.jpg',    // 图片地址
                    info: false,    // 宽高信息
                    size: 1,        // 图片质量
                    outputType: 'jpeg', // 输出格式
                    canScale: false,    // 底图是否缩放
                    autoCrop: true,     // 自动截图框
                    // 只有自动截图开启 宽度高度才生效
                    autoCropWidth: 300,
                    autoCropHeight: 250,
                    // 开启宽度和高度比例
                    fixed: true,
                    fixedNumber: [1, 1],

大神，能帮忙加个点击放大缩小的事件吗

找了一天用click触发滚轮滚动的事件的方法都没找到

java后台如何获取image值啊？

我现在不知道java后台如何获取这个data值

this.$refs.cropper.getCropData((data) => {
                this.$refs.avatarForm.reset();
                this.$post(`${this.$url}/teacher/uploadFileToQiniu`,{
                    imgStream : data
                })
                .then(res=>{

                })
                .catch(err=>{

                })
            })

文档里少写了2个参数，，，

:fixed 跟 :fixedNumber ，，可以写上去

如何不使用npm 安装 ，直接下载到本地使用这个插件呢

现在我下载到本地使用这个插件，报错

苹果6s，相册选择图片没问题，但是通过拍照图片会有拉伸，在安卓上没有问题

截图框能否限制在图片的内容以内

能否在缩小放大的时候不要把透明背景圈进去

是否支持禁止放大缩小裁剪框，即固定裁剪框大小

是否支持禁止放大缩小裁剪框，即固定裁剪框大小

截图框里可以支持滚轮缩放是不是更好呢

截图框 无法高亮 没有加任何的css

为什么不开放一个初始化的方法呢？？

很多时候希望图片加载完毕后，初始化组件。没有这个方法，很多事情都做不了了

vue2.2.6 怎么只有裁剪框 没有图片

vue2.2.6 怎么只有裁剪框 没有图片

不支持在Modal中使用

在使用iview的Modal组件中嵌入本插件，
Modal刚刚开始是隐藏的，点击按钮打开后，
初始化的数据全部失效，而且也无法切图，如下图所示

png图片透明部分裁剪后变成了黑色

图片跨域了怎么办？我已经按照MDN那样设置了。

我也看见你的源码里面也有设置相应的img.crossOrigin，但是谷歌浏览器仍然提示跨域。

可以增加更多的参数吗？

https://github.com/fengyuanchen/cropperjs#options

这里面的参数，可否提供一个方法一次性设置进去？

截图的形状可以为原形吗

上传服务端

如何将裁剪的数据传递给服务端，getCropData这个方法返回的只是一个base64编码，getCropBlob这个方法返回的是blob，这个blob数据是裁剪后的图片的流吗？

图片旋转的支持

对于网页上传的图片，不是所有的图片展示方向都是正的。所以有旋转图片会更好一点。
==，上传了一个竖着拍的图片，展示方向是横着。

怎么设置viewMode参数？

在手机上图片比例没有铺满，看了cropper文档里面有viewMode，但是在你开发的vue-cropper上好像缺少了这个支持，那么怎么设置viewMode?

固定裁剪框,之内的图片无法移动和缩放,只能移动裁剪框外的部分

有做过浏览器兼容性测试么

浏览器兼容性怎么样，有份浏览器支持的列表就更完美了

有个bug

希望添加服务器渲染支持

RT，我使用nuxt，为这个组件关闭了ssr，但是还是会在浏览器控制台得到一条警告信息。

The client-side rendered virtual DOM tree is not matching server-rendered content. This is likely caused by incorrect HTML markup, for example nesting block-level elements inside

, or missing. Bailing hydration and performing full client-side render.

裁剪得到的图片尺寸能否按照原图比例

例如 1000 * 1000 的图片，放在500 * 500的容器内，裁剪框为250 * 250，裁剪得到的图片大小也为250 * 250。
能否使裁剪后的大小按照比例为 500 * 500

有些6s还有锤子手机上上传图片不显示

用了大佬的插件，然后在我朋友的6s上上传了图片，不显示，截图也无法实现，一个锤子手机也不行。。。

图片怎么进行还原啊?

图片旋转放大缩小后,怎么进行还原啊?