更新记录

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

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

平台兼容性

uni-app(3.8.0)

img-cropper 图片裁剪组件

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

特性

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

安装

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

基本用法

<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>

Props

Events

Methods

技术说明

帧-图交叉区域算法

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

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

居中公式：

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

APP 端兼容处理

许可证

MIT