简介

vue-advanced-cropper 是一个灵活的 Vue 图片裁剪组件，让您能够创建几乎任何您想要的裁剪器。它同样易于使用和自定义。

安装

npm install vue-advanced-cropper
# or
yarn add vue-advanced-cropper

基本用法

基本示例

<template>
  <div class="basic-cropper">
    <h2>基础裁剪器示例</h2>
    <cropper class="cropper" :src="imageSrc" @change="onChange" />
    <div v-if="result" class="result">
      <h3>裁剪结果:</h3>
      <img :src="result" alt="裁剪结果" />
    </div>
  </div>
</template>

<script setup>
import { ref } from "vue";
import { Cropper } from "vue-advanced-cropper";
import "vue-advanced-cropper/dist/style.css";

const imageSrc = ref(
  "https://images.unsplash.com/photo-1600984575359-310ae7b6bdf2?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=700&q=80"
);
const result = ref(null);

const onChange = ({ coordinates, canvas }) => {
  console.log("坐标:", coordinates);
  if (canvas) {
    result.value = canvas.toDataURL();
  }
};
</script>

<style scoped>
.basic-cropper {
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
}

.cropper {
  height: 500px;
  width: 100%;
  background: #ddd;
  border-radius: 8px;
  margin-bottom: 20px;
}

.result {
  text-align: center;
}

.result img {
  max-width: 200px;
  height: auto;
  border-radius: 8px;
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
}
</style>

主要特性

1. 完全可定制

• 自定义裁剪器的几乎任何方面
• 开箱即用

2. 移动端支持

• 支持桌面和移动设备
• 内置触摸事件支持
• 支持裁剪器调整大小等

3. Canvas / 坐标

• 可用于创建带有裁剪区域的画布
• 或仅获取相对于原始图像的坐标，用于服务器端裁剪

4. 高级功能

• 设置最小和最大宽高比
• 自定义最小和最大高度和宽度等

组件属性

Cropper 组件属性

属性	类型	描述	默认值
src	String	要裁剪的图片（链接/base64）	–
stencilComponent	String, Object	模板组件	RectangleStencil
stencilProps	Object	模板组件的属性	{}
classname	String	根裁剪器块的类名	–
imageClassname	String	裁剪图片的类名	–
areaClassname	String	区域的类名	–
backgroundClassname	String	图片下方背景的类名	–
debounce	String, Number	变化事件发出前的延迟时间（毫秒）	500
canvas	Boolean	是否使用画布	true
minWidth	String, Number	模板的最小宽度（百分比）	10
minHeight	String, Number	模板的最小高度（百分比）	10
maxWidth	String, Number	模板的最大宽度（百分比）	90
maxHeight	String, Number	模板的最大高度（百分比）	90
checkOrientation	Boolean	是否检查 EXIF 方向	true
touchMove	Boolean	是否允许触摸拖拽图片	true
touchResize	Boolean	是否允许触摸调整大小	true
mouseMove	Boolean	是否允许鼠标拖拽图片	true
wheelResize	Boolean	是否允许鼠标滚轮调整大小	true
imageRestriction	String	图片位置限制 (‘area’, ‘stencil’, ‘none’)	'area'

事件

事件	描述
change	当模板位置/大小改变时触发，在组件挂载后和图片改变时也会触发
ready	图片加载成功时触发
error	图片加载错误时触发

高级示例

固定宽高比裁剪

圆形裁剪

带预览的裁剪器

文件上传裁剪

常见问题

1. 如何获取裁剪后的图片？

const onChange = ({ coordinates, canvas }) => {
  if (canvas) {
    // 获取base64格式的图片
    const imageData = canvas.toDataURL("image/png");

    // 获取Blob格式的图片
    canvas.toBlob((blob) => {
      console.log("Blob:", blob);
    }, "image/png");
  }
};

2. 如何设置裁剪区域的大小？

const stencilProps = {
  aspectRatio: 16 / 9, // 宽高比
  minWidth: 100, // 最小宽度
  minHeight: 100, // 最小高度
  maxWidth: 500, // 最大宽度
  maxHeight: 500, // 最大高度
};

3. 如何禁用某些交互？

<cropper
  :src="imageSrc"
  :touch-move="false"
  :mouse-move="false"
  :wheel-resize="false"
  @change="onChange"
/>

4. 如何处理图片加载错误？

<template>
  <div>
    <cropper :src="imageSrc" @change="onChange" @error="onError" />
    <div v-if="error" class="error-message">
      {{ error }}
    </div>
  </div>
</template>

<script setup>
import { ref } from "vue";

const error = ref("");

const onError = (errorMessage) => {
  error.value = "图片加载失败: " + errorMessage;
};
</script>

总结

vue-advanced-cropper 是一个功能强大且灵活的图片裁剪组件，支持：

• 多种裁剪形状（矩形、圆形等）
• 自定义宽高比和尺寸限制
• 移动端和桌面端支持
• 高度可定制的界面
• 丰富的 API 和事件

高级Demo示例下载

免费下载：关注公众号“前端开发技术前沿”，回复：“adv-cropper”即可。