更新记录
1.00(2025-10-21) 下载此版本
ImageCropper 是一个跨端图片裁剪组件,支持 H5、App、以及各主流小程序。内置 3:4 / 1:1 / 4:3 / 16:9 / 9:16 五种常用比例,支持拖拽、双指缩放、旋转、翻转、重置与网格辅助线。组件使用稳定的 Canvas 位移+缩放方案生成裁剪结果,确保不同平台输出一致。
平台兼容性
uni-app(3.8.0)
Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
---|---|---|---|---|---|---|---|---|
- | √ | √ | √ | √ | √ | √ | √ | √ |
微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 快应用-华为 | 快应用-联盟 |
---|---|---|---|---|---|---|---|---|---|---|
√ | - | - | - | - | - | - | - | - | - | √ |
ImageCropper 组件使用文档
概述
ImageCropper 是一个跨端图片裁剪组件,支持 H5、App、以及各主流小程序。内置 3:4 / 1:1 / 4:3 / 16:9 / 9:16 五种常用比例,支持拖拽、双指缩放、旋转、翻转、重置与网格辅助线。组件使用稳定的 Canvas 位移+缩放方案生成裁剪结果,确保不同平台输出一致。
兼容性
- H5(浏览器)
- App-Plus
- 小程序(微信/支付宝/百度/抖音/QQ 等)
已内置 scheduleFrame
兼容调度,当小程序环境不存在 requestAnimationFrame
时自动降级到 setTimeout
,避免报错并保持交互流畅。
快速上手
<template>
<ImageCropper
:visible="showCropper"
:imageSrc="imageSrc"
@confirm="onCropConfirm"
@cancel="showCropper = false"
@error="onCropError"
/>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import ImageCropper from '@/components/ImageCropper.vue'
const showCropper = ref(false)
const imageSrc = ref('')
function openCropper(path: string) {
imageSrc.value = path
showCropper.value = true
}
function onCropConfirm(res: { data: string; width: number; height: number; tempFilePath?: string }) {
// res.data 为 Base64;小程序下 res.tempFilePath 可用于持久化/上传
showCropper.value = false
}
function onCropError(message: string) {
console.error('裁剪错误:', message)
}
</script>
Props
visible
:Boolean,是否显示组件,默认false
imageSrc
:String,必填,待裁剪图片的地址(支持本地/网络)customRatios
:Object,默认{ width: 240, height: 320 }
,用于初始化裁剪框参考尺寸scaleFactor
:Number,默认1
,缩放系数(按需保留)defaultQuality
:Number,默认0.9
,导出质量(PNG/JPG 可调)
事件
confirm(payload)
:裁剪完成回调payload.data
:data:image/png;base64,...
payload.width
/payload.height
:输出尺寸payload.tempFilePath?
:仅小程序,临时文件路径
cancel()
:取消裁剪error(message)
:错误回调
内置裁剪比例与标准输出尺寸
- 3:4 → 240 × 320
- 1:1 → 240 × 240
- 4:3 → 320 × 240
- 16:9 → 320 × 180
- 9:16 → 180 × 320
比例切换时,裁剪框会按画布动态计算合适尺寸并重新居中,确保视觉与输出一致。
交互操作说明
- 单指拖拽:移动图片位置(显示网格辅助线)
- 双指缩放:基于“相对初始距离”计算,避免连续乘比造成抖动
- 旋转:左转/右转 90°
- 翻转:水平/垂直镜像
- 重置:图片与裁剪框回到居中初始状态
使用示例:选择图片后裁剪
// 以 UniApp 为例:选择图片后打开裁剪
uni.chooseImage({
count: 1,
success: (res) => {
const path = res.tempFilePaths?.[0] || res.tempFilePath
openCropper(path)
}
})
注意事项与性能优化
- 小程序环境中
requestAnimationFrame
不一定存在,组件已通过scheduleFrame
自动降级,无需额外处理。 - H5 端已在
.crop-image
启用will-change: transform
、backface-visibility: hidden
、translateZ(0)
以启用 GPU 加速;在.crop-canvas
设置touch-action: none
提升触摸响应。 - 组件仅在
visible
为true
时渲染;关闭时会重置为居中初始状态,避免“记住上次位置”的问题。 - 输出格式默认使用 PNG;如需 JPG,可在导出逻辑中调整
fileType
与quality
。
常见问题
- 图片打开不居中/再次打开未重置:组件在
handleImageLoad
与handleReset
中已统一居中与重置逻辑。 - 交互卡顿:已通过合并高频更新(rAF/降级)与缩放算法优化;若仍卡顿,请检查设备性能与图片分辨率。
版本变更与优化摘要
- 新增小程序兼容的
scheduleFrame
(rAF 不可用时自动降级)。 - 交互更新采用帧合并,缩放算法改为“相对初始距离”,显著减小抖动与卡顿。
- CSS 渲染优化:
will-change
、backface-visibility
与translateZ(0)
;touch-action: none
禁用默认滚动。 - 打开时自动居中并重置状态;比例切换按画布动态计算并居中。