NCropper 图片裁剪

全屏沉浸式图片裁剪层：拖拽、双指缩放、旋转选区图片，矩形 / 圆形裁剪框，确认后按框区域导出 png dataURL。适用于头像裁剪、图片编辑等场景。

平台兼容性

App(ANDROID)	App(IOS)	App(HARMONY)	WEB	微信小程序
✓	✓	✓	✓	✓

• Web 端系统选图（chooseImage）由浏览器文件选择承载；微信端网络图导出需在平台配置 downloadFile 合法域名。
• 覆盖层为固定全屏黑底，裁剪区外通过超大边框遮罩压暗（圆形裁剪框自动圆角化）。

基本使用

<template>
	<n-cropper :show="show" :src="src" shape="circle" :crop-width="240" :crop-height="240"
		@confirm="onConfirm" @close="show = false" />
	<n-button text="打开裁剪" @click="show = true" />
</template>
<script setup lang="uts">
	const show = ref(false);
	const src = ref("/static/photo.png");
	function onConfirm(dataUrl: string) {
		// dataUrl 为 png 格式 base64 图片数据，可直接用作 image src 或自行转存
	}
</script>

配合 v-model:show（内部关闭/确认动作会请求收起）：

<n-cropper v-model:show="show" :src="src" @confirm="onConfirm" />

API

属性

属性	类型	默认值	说明
show	boolean	false	受控显隐：true 显示全屏裁剪层，false 关闭并重置内部状态（弹层族标准契约）
src	string	""	图源：本地路径 / 临时路径 / 网络地址（微信端网络图需配置 downloadFile 合法域名）
autoChoose	boolean	false	show 变 true 且尚无图源时自动拉起系统选图
shape	"square" / "circle"	"square"	裁剪框形状，circle 用于头像
cropWidth	number	200	裁剪框宽度 px（居中显示，超出容器自动收敛）
cropHeight	number	200	裁剪框高度 px（居中显示，超出容器自动收敛）
exportWidth	number	0	输出图片宽度 px，0 表示跟随裁剪框宽度
exportHeight	number	0	输出图片高度 px，0 表示跟随裁剪框高度
maxScale	number	3	图片最大显示尺寸：显示宽不超 容器宽×maxScale 且高不超 容器高×maxScale
resizable	boolean	false	是否允许拖拽四角调整裁剪框大小（松手后图片反向适配并居中）
showGrid	boolean	true	是否显示裁剪框九宫格辅助线
zIndex	number	1000	覆盖层层级
confirmText	string	""	确认按钮文案，空值使用内置词条
watermark	NWwatermarkOption | null	null	水印配置（showOnSave 控制导出图是否含水印），null 不绘制
customClass	string	""	根节点类名（类须定义在组件样式表内，如 n-cropper--xxx）
customStyle	string	""	根节点行内样式，拼接在内部默认值之后可覆盖

水印配置对象 NWwatermarkOption（与手写签名的 watermark 同款）：text 必填，其余可选——fontSize(16)、fontFamily("sans-serif")、color("rgba(0,0,0,0.12)")、spacing(120)、bold(false)、rotate(-30)、single(false)、showOnSave(false)。

事件

事件	参数	说明
load	{ width, height }	图片加载完成时触发，参数为原始像素尺寸
change	path: string	选择图片完成时触发，参数为图片路径
open	—	裁剪层打开时触发（show 翻真或 open() 方法）
close	—	关闭时触发（关闭按钮或 close() 方法），同帧发 update:show
confirm	dataUrl: string	确认导出时触发，参数为 png 格式 dataURL，同帧发 update:show
error	error: Error	图片加载失败或导出失败时触发
update:show	show: boolean	受控显隐双通道：内部打开/关闭/确认动作请求翻转 show，配合 v-model:show

插槽

无。

实例方法

（通过 ref 直调）

方法	签名	说明
open	open(url: string): void	设置图源并打开（show 为 false 时同帧请求翻开）
close	close(): void	关闭，同帧发 close 与 update:show
chooseImage	chooseImage(): void	拉起系统选图，选完自动载入并触发 change
rotate	rotate(): void	顺时针旋转 90°，旋转后不足覆盖裁剪框时自动放大
reset	reset(): void	重置视图：裁剪框回初始居中、图片回初始适配
toPng	toPng(): Promise<string>	按当前视图导出 png dataURL（确认按钮同链路）

实现说明（参考做法 vs 本库做法）

机制	参考做法	本库做法	分歧理由
打开通道	open 方法改内部 visible（cool）/ v-if 外控（unix）/ src 受控即处理（first）	show 受控 prop（弹层族标准）+ src prop + open()/autoChoose() 三通道全收，open 走 update:show 双通道	三参考各持一通道，并集融合；受控契约统一到弹层族模式
触摸动画通道	wxs / bindingx 视图层动画（first）	逻辑层统一实现（cool 同款）	wxs/bindingx 不适用 uni-app x；逻辑层实现三端行为一致
导出格式	临时文件路径 + fileType/quality（unix/first）	png dataURL（三端一致）	临时路径方案依赖各端 canvasToTempFilePath 差异 API，无法三端一致实现；dataURL 通道全端可验证，转存/上传由使用方按平台处理
输出尺寸	width/height 独立设置（unix）/ scaleRatio 倍数（first）	exportWidth/exportHeight 显式 px，0 跟随裁剪框	显式尺寸最直观；倍数方案用显式尺寸可完整表达，不双轨收录
遮罩实现	四块矩形拼洞（cool）/ 3000px 大边框（first）	大边框法（框本体 + 2000px 实心边框），circle 圆角化	单节点覆盖矩形与圆形两形态；App 端原生渲染超大边框的真机表现已单列待验
翻转	cool 源码有翻转变量但 UI 未暴露	不收录	参考均未提供翻转入口，不发明
cancelText（unix）	—	不收录	本库关闭为图标键无文字位，语义由关闭按钮承担
background（first）	—	不收录	覆盖层底色走 customStyle 通道（弹层族同裁决）
borderColor（first）	—	不收录	裁剪框描边用白色半透明默认（cool 同款），细粒度定制走 customStyle
network（first）	显式 prop 先下载	不收录	uni-app x 的 image/canvas 直接支持网络路径；微信端只需配置 downloadFile 域名
openType=chooseAvatar（unix）	微信头像专用选图通道	不收录	autoChoose + chooseImage 已覆盖选图入口
边界约束	图片边界恒覆盖裁剪框（cool 回弹约束 / first margin 检测）	同 cool：拖动中自由、松手回弹约束	手感与覆盖保证兼得
双指缩放	围绕触点中点补偿位移、上下限收敛（cool）	同款移植	最小覆盖框、最大容器×maxScale、保持比例