更新记录

1.1.1（2026-10-13） 下载此版本

v1.1.1（2026-10-13）— 本次新增

1.1.0（2026-07-13） 下载此版本

图片裁剪支持旋转

1.0（2026-06-17） 下载此版本

零依赖：自带弹窗，无需 uView 等 UI 库 跨端兼容：H5 + APP（含 Android 10 WebView）均已验证 精准裁剪：帧-图交叉区域算法，预览/生成图片与裁剪框视觉内容完全一致 垂直居中：任意尺寸图片（横版/竖版/正方形）在裁剪框中始终居中 手势交互：单指拖拽 + 双指缩放（最小宽度 = 裁剪框宽度） 可配置：裁剪框尺寸、输出尺寸、主题色、输出形状等均可自定义

平台兼容性

uni-app(3.8.5)

img-cropper 图片裁剪组件

支持 APP（含 Android 10）和 H5 端的图片裁剪组件，零外部依赖，开箱即用。

特性

• 零依赖：自带弹窗，无需 uView 等 UI 库
• 跨端兼容：H5 + APP（含 Android 10 WebView）均已验证
• 精准裁剪：帧-图交叉区域算法，预览/生成图片与裁剪框视觉内容完全一致
• 垂直居中：任意尺寸图片（横版/竖版/正方形）在裁剪框中始终居中
• 手势交互：单指拖拽 + 双指缩放（最小宽度 = 裁剪框宽度）
• 图片旋转：点击旋转按钮每次顺时针旋转 90°，canvas 变换确保导出图片与预览一致
• 可配置：裁剪框尺寸、输出尺寸、主题色、输出形状、按钮文案等均可自定义

安装

将 img-cropper 目录复制到项目的 uni_modules 目录下即可，easycom 自动注册。

uni_modules/
└── img-cropper/
    ├── components/
    │   └── img-cropper/
    │       └── img-cropper.vue
    ├── pages/
    │   └── demo/
    │       └── demo.vue       # 插件自带演示页
    ├── package.json
    └── readme.md

基本用法

<template>
  <view>
    <button @click="chooseImage">选择图片</button>

    <img-cropper
      ref="cropperRef"
      @complete="onComplete"
      @cancel="onCancel"
    />
  </view>
</template>

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

const cropperRef = ref(null);

const chooseImage = () => {
  uni.chooseImage({
    count: 1,
    sizeType: ['original'],
    success: (res) => {
      cropperRef.value?.open(res.tempFilePaths[0]);
    },
  });
};

const onComplete = (tempFilePath) => {
  console.log('裁剪完成:', tempFilePath);
  // 调用上传接口...
};

const onCancel = () => {
  console.log('用户取消');
};
</script>

API

Props

Events

Methods

支持平台

技术说明

帧-图交叉区域算法

组件使用帧-图交叉区域算法确保裁剪输出与裁剪框视觉内容完全一致：

1. 计算裁剪框与图片在屏幕坐标系下的交叉矩形
2. 源矩形：交叉区域映射回原图坐标（drawImage 的 sx/sy/sw/sh）
3. 目标矩形：交叉区域在输出画布中居中放置

居中公式：

dx = (framePx - intersectW) * outputScale / 2
dy = (framePx - intersectH) * outputScale / 2

图片旋转实现

• 预览：CSS transform: rotate() 实时旋转显示
• 导出：canvas ctx.rotate() + ctx.translate() 变换，确保 90°/180°/270° 旋转后导出图片与预览完全一致
• 重置：点击「重置」按钮同时清除旋转角度

APP 端兼容处理

常见问题

图片不显示

原因：cropAreaHeight 在异步回调中赋值，导致 computed 计算出负数偏移

解决：已在 open() 中立即设置初始值，无需额外处理

TypeScript 报错

问题：提示找不到 uni 或 vue 模块

解决：不影响运行，可忽略。如需类型支持，安装 @dcloudio/types

裁剪结果与预览不一致

组件使用帧-图交叉区域算法，确保预览与生成图片完全一致。如遇问题，请检查：

• 图片路径是否正确
• 输出尺寸是否合理

许可证

MIT

更新日志

v1.1.1 (2026-10-13)

• 🐛 修复双指缩放以图片左上角为锚点导致的位置偏移，现以视觉中心为锚点缩放
• 🐛 修复双指缩放中抬起一根手指后继续拖动时图片跳变的问题

v1.1.0 (2026-07-13)

• ✨ 新增图片旋转功能，点击「旋转」按钮每次顺时针旋转 90°
• ✨ 增大裁剪区域上下留白，操作空间更大
• ✅ canvas 旋转变换确保导出图片与预览完全一致

v1.0.0 (2026-06-17)

• ✨ 初始版本发布
• ✅ 支持 H5 和 APP 端
• ✅ 帧-图交叉区域算法
• ✅ 单指拖拽 + 双指缩放
• ✅ 圆形/方形裁剪