uniapp-image-cropper-vue3

一个专为 Vue3 设计的 uni-app 图片裁剪组件，采用 Composition API 和 <script setup> 语法。

特性

• 🎯 支持多种裁剪比例
• 📱 适配各种uni-app平台
• 🔄 支持图片旋转
• 📏 支持自定义裁剪尺寸
• 🎨 美观的UI界面
• ⚡ Vue3 Composition API 支持
• 🚀 使用 <script setup> 语法，更简洁的代码
• 📦 TypeScript 类型支持

安装

1npm install uniapp-image-cropper-vue3

使用

基本用法

1<template>
2  <view>
3    <!-- 固定比例裁剪组件 -->
4    <CropperPis
5        v-model="filesList" 
6        :max-count="9" 
7        :max-size="maxSize" 
8        :cropper-width="500"
9        :cropper-height="500"
10        :cropper-radius="10"
11        :previewWidth="160"
12        :previewHeight="160"
13        :mode="'free'"
14        :watermark="''"
15        :watermark-type="1"
16        @upload-success="onUploadSuccess"
17        @upload-error="onUploadError" 
18        @delete="onDelete" 
19    />
20    
21    <!-- 自由裁剪组件 -->
22    <CropperFix
23       v-model="filesList2"
24        :previewWidth="160"
25        :previewHeight="160"
26        :max-count="9"
27        :max-size="maxSize" 
28        :cropper-width="200"
29        :cropper-height="200"
30        :cropper-radius="10"
31        @upload-success="onUploadSuccess"
32        @upload-error="onUploadError" 
33        @delete="onDelete" 
34    />
35  </view>
36</template>
37
38<script setup>
39import { ref } from 'vue'
40import { CropperPis, CropperFix } from 'uniapp-image-cropper-vue3'
41
42// 响应式数据
43const filesList = ref([])
44const filesList2 = ref([])
45const maxSize = ref(5 * 1024 * 1024) // 5MB
46
47// 事件处理
48const onUploadSuccess = (file) => {
49  console.log('上传成功:', file)
50}
51
52const onUploadError = (error) => {
53  console.log('上传失败:', error)
54}
55
56const onDelete = ({ file, index }) => {
57  console.log('删除图片:', file, index)
58}
59</script>

局部注册（按需引入）

1<script setup>
2// 直接引入组件
3import { CropperFix, CropperPis } from 'uniapp-image-cropper-vue3'
4</script>

全局注册

1// main.js
2import { createApp } from 'vue'
3import App from './App.vue'
4import ImageCropper from 'uniapp-image-cropper-vue3'
5
6const app = createApp(App)
7app.use(ImageCropper)
8app.mount('#app')

API

CropperFix Props

参数	说明	类型	默认值
cropperWidth	裁剪器宽度	Number/String	500
cropperHeight	裁剪器高度	Number/String	500
cropperRadius	裁剪器圆角半径	Number/String	10
modelValue	图片列表 (Vue3 v-model)	Array	[]
maxSize	最大文件大小(字节)	Number	5242880 (5MB)
maxCount	最大上传数量	Number	9
accept	接受的文件类型	String	'image/*'
disabled	是否禁用	Boolean	false
multiple	是否支持多选	Boolean	false
previewWidth	预览图宽度	Number/String	160
previewHeight	预览图高度	Number/String	160

CropperPis Props

参数	说明	类型	默认值
mode	裁剪模式：'free'自由裁剪, 'fixed'固定模式, 'ratio'等比缩放	String	'free'
cropperWidth	裁剪框宽度	Number/String	500
cropperHeight	裁剪框高度	Number/String	500
maxWidth	输出图片最大宽度	Number/String	1024
maxHeight	输出图片最大高度	Number/String	1024
modelValue	图片列表 (Vue3 v-model)	Array	[]
maxSize	最大文件大小(字节)	Number	102400 (100KB)
maxCount	最大上传数量	Number	9
accept	接受的文件类型	String	'image/*'
disabled	是否禁用	Boolean	false
multiple	是否支持多选	Boolean	false
watermark	水印文字	String	''
watermarkType	水印样式	Number	1
previewWidth	预览图宽度	Number/String	160
previewHeight	预览图高度	Number/String	160

Events

事件名	说明	参数
update:modelValue	图片列表更新	(value: Array)
upload-success	上传成功	(file: Object)
upload-error	上传失败	(error: Object)
delete	删除图片	({ file: Object, index: Number })

Vue3 特性

Composition API 支持

组件内部使用 Vue3 Composition API 编写，提供更好的逻辑复用和类型推断：

1<script setup>
2import { ref, computed, watch } from 'vue'
3import { CropperFix } from 'uniapp-image-cropper-vue3'
4
5const fileList = ref([])
6const maxSize = ref(5 * 1024 * 1024)
7
8// 计算属性
9const canUpload = computed(() => fileList.value.length < 9)
10
11// 监听器
12watch(fileList, (newList) => {
13  console.log('文件列表更新:', newList)
14}, { deep: true })
15</script>

TypeScript 支持

提供完整的 TypeScript 类型定义：

1import type { DefineComponent } from 'vue'
2import type { FileItem } from 'uniapp-image-cropper-vue3'
3
4interface FileItem {
5  url: string
6  size: number
7  name: string
8  extension: string  // 文件扩展名，如 'jpg', 'png', 'gif' 等
9  isImage: boolean
10  status: string
11  message: string
12}
13
14const fileList = ref<FileItem[]>([])

文件对象结构

组件返回的文件对象包含以下字段：

1{
2  url: 'blob:http://localhost:8080/xxx',     // 文件URL
3  size: 1024000,                             // 文件大小（字节）
4  name: 'image_1703068800000.jpg',          // 文件名
5  extension: 'jpg',                          // 文件扩展名
6  isImage: true,                             // 是否为图片
7  status: 'done',                            // 状态：'done'成功, 'error'失败
8  message: '上传成功'                         // 状态消息
9}

平台兼容性

平台	支持
H5	✅
微信小程序	✅
支付宝小程序	✅
百度小程序	✅
字节跳动小程序	✅
QQ小程序	✅
App	✅

版本更新日志

v1.1.0 (2024-12-20)

• ✨ 新增文件扩展名字段 extension
• 📝 完善 TypeScript 类型定义，添加 FileItem 接口
• 🔧 优化文件对象结构，提供更完整的文件信息
• 📚 更新文档，添加文件对象结构说明

v1.0.0 (2024-12-20)

• 🎉 首次发布 Vue3 专用版本
• ✨ 采用 Composition API 和 <script setup> 语法
• 📦 完整的 TypeScript 类型支持
• 🚀 更好的性能和开发体验
• 🔄 从 Options API 迁移到 Composition API

从 Vue2 迁移

如果你正在从 Vue2 版本迁移，主要变化：

1. v-model 绑定：Vue3 统一使用 modelValue
2. 事件监听：使用 defineEmits 定义事件
3. 响应式数据：使用 ref 和 reactive
4. 生命周期：使用 Composition API 钩子

许可证

MIT License