前言

需求遇到需要封装一个裁剪图片的组件，自己写了一个插件，欢迎大家使用后点评，有需要改善的地方请留言，有时间会迭代滴。
本篇就是告诉大家如何引入使用的。

到 Uniapp 的插件市场，搜索 una-img-cropper
快速通道：https://ext.dcloud.net.cn/search?q=una-img-cropper&cat1=2

一、 插件介绍

1.✨ 特性

• 支持从相册或相机选择图片
• 支持固定比例裁剪
• 内置常用裁剪比例：
  • 1:1
  • 4:3
  • 16:9
  • 3:4
  • 9:16
  • 3:2
  • 2:3
• 支持自定义可选裁剪比例
• 支持拖拽移动裁剪区域
• 支持拖拽右下角调整裁剪框大小
• 支持设置裁剪区域高度
• 支持设置导出图片宽度
• 支持设置导出质量
• 支持设置导出图片格式
• 支持 Canvas 导出临时文件路径
• 支持 v-model:src 双向绑定图片路径
• 支持通过 ref 主动调用选择图片、裁剪、重置方法

2. Props 参数

参数	类型	默认值	说明
src	String	''	当前图片路径，支持 v-model:src 双向绑定
defaultRatio	String	'1:1'	默认裁剪比例
ratios	Array	['1:1','4:3','16:9','3:4','9:16','3:2','2:3']	可选裁剪比例列表
stageHeight	Number	420	裁剪操作区域高度，单位为 px
outputWidth	Number	1080	导出图片宽度
quality	Number	0.92	导出图片质量，通常范围为 0 ~ 1
fileType	String	'jpg'	导出图片格式，例如 jpg、png

• ratios 参数说明：
  • 支持字符串数组：

    ['1:1', '4:3', '16:9']
    

  • 也支持对象数组：

    	[
    	  { label: '方图', value: '1:1' },
    	  { label: '横图', value: '16:9' }
    	]
    	```
    

3.Events事件

事件名	回调参数	说明
update:src	path: string	选择图片后触发，用于支持 v-model:src
change	ratio	切换裁剪比例时触发
ready	info	图片信息读取完成时触发
crop	result	裁剪成功时触发
error	error	选择图片、读取图片或导出图片失败时触发

• change 事件参数

  {
    label: '1:1',
    value: 1,
    raw: '1:1'
  }
  

• ready 事件参数

  ready 返回 uni.getImageInfo 获取到的图片信息，常见结构如下：

  {
    width: 1080,
    height: 1920,
    path: '图片路径',
    orientation: 'up',
    type: 'jpg'
  }
  

• crop 事件参数

  {
    tempFilePath: '裁剪后的临时文件路径',
    width: 1080,
    height: 1080,
    ratio: '1:1',
    source: {
      x: 0,
      y: 0,
      width: 800,
      height: 800
    }
  }
  

  字段说明：

  字段	说明
  tempFilePath	裁剪后生成的临时图片路径
  width	导出图片宽度
  height	导出图片高度
  ratio	当前裁剪比例
  source.x	原图中的裁剪起点 X 坐标
  source.y	原图中的裁剪起点 Y 坐标
  source.width	原图中的裁剪宽度
  source.height	原图中的裁剪高度

• v-model:src 数据结构
  当前组件没有使用默认的 modelValue，而是使用 v-model:src 绑定图片路径。

  const imagePath = ref('')
  

  • 类型为：string
  • 示例：

    <una-img-cropper v-model:src="imagePath" />
    

  • 当用户选择图片后，组件会触发：

    emit('update:src', path)
    

  因此外部绑定的 imagePath 会更新为当前选择的图片临时路径。

• 裁剪结果数据结构

  裁剪后的数据通过 crop 事件返回：

  {
    tempFilePath: string,
    width: number,
    height: number,
    ratio: string,
    source: {
      x: number,
      y: number,
      width: number,
      height: number
    }
  }
  

4. 注意事项

• 插件依赖 uni.chooseImage、uni.getImageInfo、uni.createCanvasContext、uni.canvasToTempFilePath 等 uni-app API。
• 组件适用于 Vue 3 项目。
• 默认支持微信小程序和 App Vue。
• H5 端部分能力需要根据实际平台兼容性测试。
• 导出图片高度会根据 outputWidth 和当前裁剪比例自动计算。

二、插件使用示例

1. 下载路径

https://ext.dcloud.net.cn/plugin?id=28308

先导入在自己的项目试用，觉得没啥问题，符合需求，再付费购买。


购买之后，将组件导入的项目中

点击“确认”，查看此时在哪个目录里。
【注意】因为uniapp修改了传入的目录结构，我的项目结构为 components/una-banner，若有冲突，保证自己的项目不被影响的前提下，点击忽略冲突，别替换了自己项目的文件

2. 引入组件

1）方法一：放入uni_modules

在 uni_modules中新建一个目录una-img-cropper，将下载的 componets下的文件都放入这个目录中。如图：

2）放入components

可以删除无用的 文件，如package.json 、 README.md。

这里我留着是示例如果有同学需要看的话，就放入这个文件夹里，不然自己的其他组件多了之后不好管理文件。

3. 在微信小程序中的运行

案例：点击进入裁剪页，裁剪图片并预览裁剪后的结果

效果如图，第一个页面的button 跳转就不给示例了哈，图片裁剪页面具体代码如下：

<template>
	<view class="page">
		<una-img-cropper
			v-model:src="imagePath"
			default-ratio="1:1"
			:output-width="1080"
			@crop="handleCrop"
			@error="handleError"
		/>

		<view v-if="cropResult" class="result">
			<image class="result-image" :src="cropResult.tempFilePath" mode="aspectFit" />
			<view class="result-meta">
				<text>裁剪完成：{{ cropResult.width }} x {{ cropResult.height }}</text>
			</view>
		</view>
	</view>
</template>

<script setup>
import { ref } from 'vue'
const imagePath = ref('')
const cropResult = ref(null)

function handleCrop(result) {
	cropResult.value = result
	uni.showToast({
		title: '裁剪完成',
		icon: 'success'
	})
}

function handleError(error) {
	console.error(error)
	uni.showToast({
		title: '操作失败',
		icon: 'none'
	})
}
</script>

<style>
	.page {
		min-height: 100vh;
		padding: 16px;
		box-sizing: border-box;
		background: #f6f7f9;
	}
	
	.result {
		margin-top: 16px;
		padding: 12px;
		border-radius: 8px;
		background: #ffffff;
	}
	
	.result-image {
		display: block;
		width: 100%;
		height: 220px;
		background: #eef1f5;
	}
	
	.result-meta {
		margin-top: 10px;
		color: #30343b;
		font-size: 14px;
	}
</style>

有问题可以留言，感谢使用

三、其他插件文章

1. 【Uniapp 插件 una-banner 】轮播图 / banner / swiper

快速通道

2. 【Uniapp 插件 una-bubble 】气泡 / 聊天框 / 对话框

快速通道

3.【Uniapp 插件 una-upload-resource 】上传资源组件｜ 图片上传｜视频上传｜混传

快速通道

4.【Uniapp 插件 una-img-cropper 】 支持自定义裁剪比例、拖拽缩放调整画面，可导出指定尺寸与画质的图片，跨端兼容，适用于头像上传、图片裁切等业务场景。

快速通道