更新记录

2.0.0（2026-11-01）

首个发布版本。

功能

• 支持矩形 / 圆形 / 圆角裁剪，裁切比例支持 free / original / 1:1 / 3:4 / 4:3 / 9:16 / 16:9 或数值
• 支持缩放、拖拽、旋转（含 90° 快捷）、水平 / 垂直翻转、撤销 / 重做
• 支持网格线、遮罩色、角把手、边框、棋盘格背景等外观配置
• 支持自定义导出：输出尺寸、DPR、格式（PNG / JPEG / WebP）与质量
• 提供命令式 API（cropImage / getCropController）与组件式（l-crop）两种用法
• 提供 Hook（useCrop / useCropAgent）便于完全自定义裁剪 UI

平台兼容性

uni-app(4.45)

uni-app x(5.31)

其他

lime-crop 图片裁剪

一款支持缩放、旋转、翻转、网格、圆形与圆角裁剪，并可自定义导出的图片裁剪插件，兼容 uni-app / uni-app-x。

插件依赖：lime-shared、lime-style、lime-use

::: tip 提示 本插件依赖的插件会在 uni_modules 中自动引入，无需手动导入。 :::

安装方法

1. 在 uni-app 插件市场中搜索并导入 lime-crop
2. 首次导入后可能需要重新编译项目
3. 在页面中使用 l-crop 或 l-crop-agent 组件

代码演示

命令式调用（推荐）

先在页面放置一次 <l-crop-agent />，再调用 cropImage 弹出裁剪界面。

<!-- 在页面中放置代理组件（只需一次） -->
<l-crop-agent />

import { cropImage } from '@/uni_modules/lime-crop'
import type { LimeCropOptions } from '@/uni_modules/lime-crop'

const options: LimeCropOptions = {
  src: '/static/photo.png',
  aspectRatio: '1:1',
  onConfirm: (dataUrl: string) => {
    console.log('裁剪结果:', dataUrl)
  },
  onCancel: () => {
    console.log('用户取消')
  },
  onError: (message: string) => {
    console.log('出错了:', message)
  }
}
cropImage(options)

多实例

同一页面需要多个裁剪入口时，给 <l-crop-agent> 加 id，调用时带上同一个 id。

<l-crop-agent id="avatar" />
<l-crop-agent id="cover" />

import { cropImage, getCropController } from '@/uni_modules/lime-crop'

cropImage({ id: 'avatar', src: avatarSrc, aspectRatio: '1:1' })
cropImage({ id: 'cover', src: coverSrc, aspectRatio: '16:9' })

// 也可以拿到控制器直接操作
const controller = getCropController('avatar')
controller?.rotateLeft()

id 默认为 default，不传时两者都对应默认实例。

组件式使用（自定义 UI）

使用 l-crop 自身搭建界面，适合需要完全自定义操作按钮和布局的场景。

<l-crop
  ref="cropRef"
  src="/static/photo.png"
  aspect-ratio="1:1"
  @change="onCropChange"
  @error="onCropError"
/>
<button @click="handleRotateLeft">向左旋转</button>
<button @click="handleCrop">裁剪</button>

import type { LimeCropActionDetails } from '@/uni_modules/lime-crop'

// LCropComponentPublicInstance 由 uni-app x 自动生成，无需手动引入
const cropRef = ref<LCropComponentPublicInstance | null>(null)

const onCropChange = (actionDetails: LimeCropActionDetails) => {
  console.log('当前旋转角度:', actionDetails.rotateDegrees)
}
const onCropError = (message: string) => {
  uni.showToast({ title: message, icon: 'none' })
}

const handleRotateLeft = () => cropRef.value?.rotateLeft()

const handleCrop = async () => {
  const result = await cropRef.value?.crop()
  console.log('裁剪结果:', result)
}

组件显隐请由调用方通过 v-if 控制：<l-crop v-if="cropVisible" ... />。组件内部不做 v-if，因为卸下 Canvas 后需要重新初始化。

裁剪样式

<!-- 矩形裁剪（默认） -->
<l-crop src="/static/photo.png" crop-style="0" />

<!-- 圆形裁剪 -->
<l-crop src="/static/photo.png" crop-style="1" />

<!-- 圆角矩形裁剪 -->
<l-crop src="/static/photo.png" crop-style="0" corner-radius="20" />

裁切比例

<!-- 自由比例 -->
<l-crop src="/static/photo.png" aspect-ratio="free" />

<!-- 保持原图比例 -->
<l-crop src="/static/photo.png" aspect-ratio="original" />

<!-- 1:1 方形 -->
<l-crop src="/static/photo.png" aspect-ratio="1:1" />

<!-- 3:4 竖版 -->
<l-crop src="/static/photo.png" aspect-ratio="3:4" />

<!-- 16:9 横版 -->
<l-crop src="/static/photo.png" aspect-ratio="16:9" />

自定义导出

<l-crop
  src="/static/photo.png"
  dest-format="image/jpeg"
  dest-quality="0.8"
  dest-width="800"
  dest-DPR="2"
/>

命令式调用同样支持：

cropImage({
  src: '/static/photo.png',
  destFormat: 'image/jpeg',
  destQuality: 0.8,
  destWidth: 800,
  destDPR: 2,
  onConfirm: (dataUrl) => { /* ... */ }
})

性能优化

低端机或 APP 原生平台拖拽不跟手时，通过 throttleFps 限制触摸移动帧率。

<!-- 默认 33（约 30fps） -->
<l-crop src="/static/photo.png" />

<!-- 限制 20fps，进一步降低 GPU 压力 -->
<l-crop src="/static/photo.png" :throttleFps="20" />

<!-- 设为 0 关闭节流 -->
<l-crop src="/static/photo.png" :throttleFps="0" />

默认值即 33（约 30fps），也就是默认开启节流；只有显式传 0 才是完全不限制。

API 文档

命令式 API

Props 分类

🎯 基础配置（最常用）

🖼️ 导出配置

🎨 样式与外观

⚙️ 行为配置

📞 回调（仅命令式 API）

Events（l-crop 组件）

Methods（l-crop 组件，通过 ref 调用）

crop() 无论成功失败都会复位 loading；失败时返回 null 并触发 error 事件。

LimeCropImperative（控制器）

cropImage(options) 与 getCropController(id) 的实例方法：

只读属性（响应式，可直接用于模板）：visible、currentSrc、currentConfig、sliderValue、showRotateTip、rotateTipDegree。

Hook

需要在自定义 UI 中复用裁剪逻辑时，可直接使用两个组合式函数（均由包入口导出）。

useCrop

import { useCrop } from '@/uni_modules/lime-crop'
import type { CropProps } from '@/uni_modules/lime-crop'

const {
  isReady, canUndo, canRedo,
  crop, rotate, rotateLeft, rotateRight, flip, flipHorizontal, flipVertical,
  reset, undo, redo, setAspectRatio, updateCropStyle, updateCornerRadius, setRotation,
  , , , ,
  imageCanvasId, cropCanvasId, exportCanvasId,
  showExportCanvas, exportCanvasStyle,
} = useCrop(props)

返回的 imageCanvasId / cropCanvasId / exportCanvasId 需要绑到你自己模板里的 <canvas> 上， showExportCanvas / exportCanvasStyle 用于控制导出画布。返回类型见 UseCropReturn。

useCropAgent

import { useCropAgent } from '@/uni_modules/lime-crop'

const { visible, currentSrc, currentConfig, cropRef, sliderValue, showRotateTip, rotateTipDegree, imperative } = useCropAgent()

imperative 即 LimeCropImperative 实例，用于搭建自定义的裁剪代理组件。

类型定义

LimeRotateOptions

所有字段均可省略，省略时取表中默认值。

LimeFlipOptions

所有字段均可省略，省略时取表中默认值。

LimeCropActionDetails

change 事件与 onChange 回调的载荷，常用只读字段：

裁剪样式说明

矩形裁剪（cropStyle = 0）

默认模式，支持自由比例和固定比例裁剪。配合 cornerRadius 可实现圆角矩形。

圆形裁剪（cropStyle = 1）

圆形模式下自动锁定 1:1 比例，导出图片为圆形透明背景 PNG。

圆形模式下调用 setAspectRatio 传入非 1:1 的比例会被强制为 1:1。

圆角矩形

设置 cornerRadius > 0 即可，圆角半径最大不超过角标宽度（cornerSize 的宽度），导出时圆角外侧为透明区域。

主题定制

组件样式主要通过 props 定制；l-crop-agent 另提供 CSS 变量。

使用示例

方式一：通过 props 设置（推荐）

<l-crop
  src="/static/photo.png"
  mask-color="rgba(0,0,0,0.6)"
  line-color="#07c160"
  corner-color="#07c160"
  :line-height="2"
/>

方式二：通过 lStyle 设置

<l-crop src="/static/photo.png" :l-style="{ width: '100%', height: '100%' }" />

方式三：通过 CSS 变量定制 l-crop-agent

<view class="crop-wrapper">
  <l-crop-agent />
</view>

<style>
.crop-wrapper {
  --l-crop-agent-confirm-bg: #1989fa;
  --l-crop-agent-text-color: #333;
}
</style>

常用变量：

⚠️ 重要提示

关于 class 的使用

请不要直接在 lime- 组件上使用 class 属性！ 推荐以下三种方式：

方式一：在父级或根节点上设置 class

<view class="crop-wrapper">
  <l-crop src="/static/photo.png" />
</view>
<style>
.crop-wrapper {
  /* 在这里设置相关样式 */
}
</style>

方式二：使用 lStyle 直接设置

<l-crop src="/static/photo.png" :l-style="{ width: '100%' }" />

方式三：使用 lClass 配合样式

<l-crop src="/static/photo.png" lClass="custom-crop" />
<style>
.custom-crop {
  /* 在这里设置相关样式 */
}
</style>

快速预览

导入插件后，可以直接使用以下标签查看演示效果：

<!-- 代码位于 uni_modules/lime-crop/components/lime-crop -->
<lime-crop />

插件标签说明

平台差异与已知限制

注意事项

1. 本组件基于 Canvas 2D 实现，需要平台支持 Canvas 2D API
2. uni-app x 项目使用 .uvue 文件，非 uni-app x 项目使用 .vue 文件
3. cornerRadius 最大值受 cornerSize 的宽度限制
4. cropImage 依赖页面中已放置的 <l-crop-agent />；没有匹配 id 的实例时 cropImage 不做任何事
5. 裁剪内核为纯逻辑，不调用 uni API，源码不随插件包分发，包内仅有压缩产物 crop-core.esm.min.js
6. 图片解码完成前调用 setAspectRatio 不会报错：比例会暂存，等图片就绪后自动生效；此时调用 rotate / flip 会被忽略（可通过 isReady 判断就绪状态）

常见问题

命令式调用没有反应？

请确认页面中已放置 <l-crop-agent />，且 cropImage({ id }) 的 id 与该组件一致（默认都是 default）。

在弹窗中使用时裁剪区尺寸异常？

裁剪组件初始化时需要读取 Canvas 的真实尺寸，弹窗未展开时尺寸可能为 0。请确保弹窗展开后再渲染：

<l-popup v-model="show">
  <l-crop v-if="show" src="/static/photo.png" />
</l-popup>

导出的图片是空白 / 透明？

• 确认图片已加载完成（isReady 为 true）后再调 crop()
• 圆形与圆角模式下，裁剪区域外本来就是透明区域

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助