uniapp-image-cropper-vue3

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

特性

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

安装

npm install uniapp-image-cropper-vue3

使用

基本用法

<template>
  <view>
    <!-- 固定比例裁剪组件 -->
    <CropperPis
        v-model="filesList" 
        :max-count="9" 
        :max-size="maxSize" 
        :cropper-width="500"
        :cropper-height="500"
        :cropper-radius="10"
        :previewWidth="160"
        :previewHeight="160"
        :mode="'free'"
        :watermark="''"
        :watermark-type="1"
        @upload-success="onUploadSuccess"
        @upload-error="onUploadError" 
        @delete="onDelete" 
    />
    
    <!-- 自由裁剪组件 -->
    <CropperFix
       v-model="filesList2"
        :previewWidth="160"
        :previewHeight="160"
        :max-count="9"
        :max-size="maxSize" 
        :cropper-width="200"
        :cropper-height="200"
        :cropper-radius="10"
        @upload-success="onUploadSuccess"
        @upload-error="onUploadError" 
        @delete="onDelete" 
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { CropperPis, CropperFix } from 'uniapp-image-cropper-vue3'

// 响应式数据
const filesList = ref([])
const filesList2 = ref([])
const maxSize = ref(5 * 1024 * 1024) // 5MB

// 事件处理
const onUploadSuccess = (file) => {
  console.log('上传成功:', file)
}

const onUploadError = (error) => {
  console.log('上传失败:', error)
}

const onDelete = ({ file, index }) => {
  console.log('删除图片:', file, index)
}
</script>

局部注册（按需引入）

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

全局注册

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import ImageCropper from 'uniapp-image-cropper-vue3'

const app = createApp(App)
app.use(ImageCropper)
app.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 编写，提供更好的逻辑复用和类型推断：

<script setup>
import { ref, computed, watch } from 'vue'
import { CropperFix } from 'uniapp-image-cropper-vue3'

const fileList = ref([])
const maxSize = ref(5 * 1024 * 1024)

// 计算属性
const canUpload = computed(() => fileList.value.length < 9)

// 监听器
watch(fileList, (newList) => {
  console.log('文件列表更新:', newList)
}, { deep: true })
</script>

TypeScript 支持

提供完整的 TypeScript 类型定义：

import type { DefineComponent } from 'vue'
import type { FileItem } from 'uniapp-image-cropper-vue3'

interface FileItem {
  url: string
  size: number
  name: string
  extension: string  // 文件扩展名，如 'jpg', 'png', 'gif' 等
  isImage: boolean
  status: string
  message: string
}

const fileList = ref<FileItem[]>([])

文件对象结构

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

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

平台兼容性

| 平台 | 支持 | |------|------| | 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