更新记录

1.0.0（2026-06-02）

• ✨ 初始版本
• ✨ 支持图片选择
• ✨ 支持图片裁剪
• ✨ 支持缩放调整
• ✨ 支持拖拽移动
• ✨ 支持圆形/方形切换
• ✨ 符合 easycom 规范

平台兼容性

uni-app(3.7.8)

upload-img-cropper-pro

一款功能强大的 uni-app 图片裁剪/头像上传组件，支持图片选择、裁剪、缩放、拖拽等功能，完全符合 easycom 规范，开箱即用。

🎨 功能特性

📱 平台兼容性

📦 安装方式

方式一：npm 安装（推荐）

npm install upload-img-cropper-pro --save

方式二：手动安装

1. 下载组件包
2. 将 upload-img-cropper-pro 文件夹复制到项目的 components 目录下

方式三：easycom 自动引入（uni-app 推荐）

由于组件符合 easycom 规范，只需将组件放入项目的 components 目录，即可在页面中直接使用，无需手动 import。

easycom 配置（在 pages.json 中）：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^upload-(.*)": "@/components/upload-$1/upload-$1.vue"
    }
  }
}

🔧 使用方式

基本使用

<template>
  <view class="container">
    <upload-img-cropper-pro 
      v-model="avatar" 
      :width="200" 
      :height="200"
      :circle="true"
      @change="onAvatarChange"
    ></upload-img-cropper-pro>
  </view>
</template>

<script>
export default {
  data() {
    return {
      avatar: ''
    }
  },
  methods: {
    onAvatarChange(url) {
      console.log('头像已更新:', url)
      // 可以在这里上传到服务器
      this.uploadToServer(url)
    },
    uploadToServer(url) {
      uni.uploadFile({
        url: 'https://your-server.com/upload',
        filePath: url,
        name: 'avatar',
        success: (res) => {
          console.log('上传成功:', res)
        }
      })
    }
  }
}
</script>

进阶使用

1. 方形头像

<upload-img-cropper-pro 
  v-model="coverImage" 
  :width="300" 
  :height="200"
  :circle="false"
  @change="onCoverChange"
></upload-img-cropper-pro>

2. 自定义尺寸

<upload-img-cropper-pro 
  v-model="largeAvatar" 
  :width="400" 
  :height="400"
  :circle="true"
></upload-img-cropper-pro>

3. 配合表单使用

<template>
  <view class="form">
    <view class="form-item">
      <text class="form-label">用户头像</text>
      <upload-img-cropper-pro 
        v-model="formData.avatar" 
        :width="160" 
        :height="160"
      ></upload-img-cropper-pro>
    </view>

    <view class="form-item">
      <text class="form-label">商品封面</text>
      <upload-img-cropper-pro 
        v-model="formData.cover" 
        :width="300" 
        :height="200"
        :circle="false"
      ></upload-img-cropper-pro>
    </view>

    <button @click="submitForm">提交</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      formData: {
        avatar: '',
        cover: ''
      }
    }
  },
  methods: {
    submitForm() {
      // 验证表单
      if (!this.formData.avatar) {
        uni.showToast({
          title: '请选择头像',
          icon: 'none'
        })
        return
      }

      // 提交表单
      console.log('表单数据:', this.formData)
    }
  }
}
</script>

📋 Props 参数

🎯 Events 事件

🎨 裁剪界面功能

裁剪界面提供以下交互功能：

1. 缩放控制

• 滑块拖动：通过拖动底部滑块调整缩放比例（1-5倍）
• 点击轨道：直接点击滑块轨道快速定位到对应缩放比例

2. 拖拽移动

• 触摸拖拽（移动端）：在裁剪区域内用手指拖动图片
• 鼠标拖拽（PC端）：在裁剪区域内用鼠标拖动图片

3. 边界限制

• 当图片缩放后超出裁剪区域时，可以自由拖拽选择区域
• 当图片小于裁剪区域时，自动居中且不允许拖拽

🔌 API 说明

组件方法

组件内部调用的 uni-app API：

📁 项目结构

upload-img-cropper-pro/
├── upload-img-cropper-pro.vue  # 组件主文件
├── package.json                # 组件配置文件
└── README.md                   # 组件说明文档

⚠️ 注意事项

1. 微信小程序兼容性：微信小程序环境中 document 对象不可用，组件已做兼容性处理
2. 权限配置：使用相机功能需要在 manifest.json 中配置相机权限
3. canvas-id 唯一性：页面中如果有多个 canvas，确保 canvas-id 不重复
4. 图片大小限制：建议对上传图片大小进行限制，避免过大图片影响性能

🐛 常见问题

Q1: 组件不显示？

A：请检查：

• 组件是否正确放置在 components 目录下
• pages.json 中是否配置了 easycom
• 是否有语法错误，可以在控制台查看报错信息

Q2: 裁剪后图片不显示？

A：请检查：

• 确认 canvas-id 唯一
• 确认图片路径正确
• 在微信小程序开发工具中查看是否有报错

Q3: 拖拽功能不生效？

A：请检查：

• 移动端需要使用触摸事件，PC端需要使用鼠标事件
• 确保没有其他元素阻止了事件传递

Q4: 如何上传到服务器？

A：可以在 @change 事件中调用 uni.uploadFile 上传：

onAvatarChange(url) {
  uni.uploadFile({
    url: 'https://your-server.com/api/upload',
    filePath: url,
    name: 'file',
    success: (res) => {
      const data = JSON.parse(res.data)
      console.log('上传成功:', data)
    },
    fail: (err) => {
      console.error('上传失败:', err)
    }
  })
}

🔄 版本更新记录

v1.0.0

• ✨ 初始版本
• ✨ 支持图片选择
• ✨ 支持图片裁剪
• ✨ 支持缩放调整
• ✨ 支持拖拽移动
• ✨ 支持圆形/方形切换
• ✨ 符合 easycom 规范

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发流程

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/xxx)
3. 提交代码 (git commit -m 'feat: add xxx')
4. 推送到分支 (git push origin feature/xxx)
5. 创建 Pull Request

代码规范

• 遵循 uni-app 开发规范
• 使用 ES6+ 语法
• 保持代码简洁清晰
• 添加必要的注释

📄 License

MIT License

📧 联系方式

如有问题或建议，欢迎通过以下方式联系：

• 提交 Issue
• 发送邮件：your-email@example.com

如果这个组件对你有帮助，请给个 Star ⭐️