更新记录

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.datadata: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: transformbackface-visibility: hiddentranslateZ(0) 以启用 GPU 加速;在 .crop-canvas 设置 touch-action: none 提升触摸响应。
  • 组件仅在 visibletrue 时渲染;关闭时会重置为居中初始状态,避免“记住上次位置”的问题。
  • 输出格式默认使用 PNG;如需 JPG,可在导出逻辑中调整 fileTypequality

常见问题

  • 图片打开不居中/再次打开未重置:组件在 handleImageLoadhandleReset 中已统一居中与重置逻辑。
  • 交互卡顿:已通过合并高频更新(rAF/降级)与缩放算法优化;若仍卡顿,请检查设备性能与图片分辨率。

版本变更与优化摘要

  • 新增小程序兼容的 scheduleFrame(rAF 不可用时自动降级)。
  • 交互更新采用帧合并,缩放算法改为“相对初始距离”,显著减小抖动与卡顿。
  • CSS 渲染优化:will-changebackface-visibilitytranslateZ(0)touch-action: none 禁用默认滚动。
  • 打开时自动居中并重置状态;比例切换按画布动态计算并居中。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

许可协议

MIT协议

暂无用户评论。