Skip to content

@neosjs/cropper ​

Vue 3 图片裁剪组件。支持自动截图、固定宽高比、截图框拖动与缩放、旋转、高清模式、网格与样式定制,可实时预览裁剪结果,并通过 ref 调用组件方法获取 base64 数据或直接下载图片。

安装 ​

sh
pnpm add @neosjs/cropper
sh
npm i @neosjs/cropper
sh
yarn add @neosjs/cropper

快速上手 ​

引入组件与样式,通过 v-bind 绑定配置项,通过 real-time 事件获取实时预览数据:

vue
<script lang="ts" setup>
import NeosCropper from '@neosjs/cropper'
import { ref } from 'vue'
import '@neosjs/cropper/dist/index.css'

const cropper = ref(null)
const previews = ref<any>({})
const option = ref({
  img: 'xxxxxxx', // 图片地址
  quality: 1,
  fileExt: 'png', // 输出类型
  canMove: false, // 是否可以移动图片
  canMoveBox: true, // 截图框是否可以拖动
  autoCrop: false, // 是否自动截图
  // 只有开启自动截图,宽高才生效
  autoCropWidth: 200, // 自动截图宽度
  autoCropHeight: 150, // 自动截图高度
  centerBox: false, // 截图框是否被限制在图片里
  high: false, // 是否按高清
  enlarge: 1, // 截图框的放大倍数
  mode: 'contain', // 截图框的模式
  maxImgSize: 3000, // 最大允许的图片大小
  limitMinSize: [50, 50], // 截图框的最小大小
  fixed: false, // 是否开启截图框宽高固定比例
  fixedNumber: [2, 1], // 截图框的宽高比例
  fillColor: '', // 截图框的背景颜色
  showGrid: true // 是否显示网格
})

function imgLoad() {
  console.log('图片加载完成')
}
function imgLoadError() {
  console.log('图片加载失败')
}
function realTime(data: any) {
  previews.value = data
}
function startCrop() {
  cropper.value.startCrop()
}
function stopCrop() {
  cropper.value.stopCrop()
}
function clearCrop() {
  cropper.value.clearCrop()
}
</script>

<template>
  <div>
    <NeosCropper
      ref="cropper"
      v-bind="option"
      @real-time="realTime"
      @img-load="imgLoad"
      @img-load-error="imgLoadError"
    />
    <section class="block">
      <p>截图预览</p>
      <div
        class="show-preview"
        :style="{
          width: `${previews.w}px`,
          height: `${previews.h}px`,
          overflow: 'hidden',
          margin: '5px',
        }"
      >
        <div :style="previews.div">
          <img :src="previews.url" :style="previews.img">
        </div>
      </div>
    </section>
  </div>
</template>

API ​

方法 ​

通过组件 ref 调用:

方法名说明参数
startCrop开始截图-
stopCrop停止截图-
clearCrop清除截图-
destroyCrop销毁截图-
rotateLeft左旋转-
rotateRight右旋转-
changeScale缩放图片Number
downloadImg下载图片-
getImgData获取图片数据-
getCropData获取转换成 base64 的图片信息Function

事件 ​

事件名说明返回值
on-error图片加载失败-
on-success图片加载成功-
real-time截图框实时数据Object
crop-moving截图框移动中-

参数 ​

参数说明类型可选值默认值
img图片地址String | Blob | File | null--
quality输出图片质量Number-1
fileExt输出图片类型String-jpeg
fileScale输出图片的缩放比例Boolean-false
canScale是否开启滚轮放大缩小Boolean-false
canMove是否可以移动图片Boolean-false
canMoveBox截图框是否可以拖动Boolean-true
autoCrop是否自动截图Boolean-false
autoCropWidth自动截图宽度Number | String-0
autoCropHeight自动截图高度Number | String-0
fixedRatio是否开启固定宽高比Boolean-false
fixedNumber固定宽高比例Array-[1, 1]
fixedSize是否固定截图框大小Boolean-false
original是否显示原图按钮Boolean-false
centerBox截图框是否被限制在图片里Boolean-false
showInfo是否显示截图框信息Boolean-true
high是否按高清Boolean-true
maxImgSize最大允许的图片大小Number-2000
fillColor导出时填充背景颜色String--
cutDotColor截图框的点的颜色String-rgb(51 153 255 / 75%)
cutDotSize截图框的点的大小Number-6
cutDotRound截图框的点是否圆角Boolean-true
showGrid是否显示网格Boolean-true
gridColor网格颜色String-#eeeeee
showToolIcon显示工具栏图标ArrayzoomIn / zoomOut / rotateLeft / rotateRight / redo / save['close', 'confirm']
toolPosition工具栏位置Stringleft / center / rightright