ImageCropper 图片裁切

介绍

基于 useTouchZoom 的图片裁切组件：双指缩放、单指拖动、可选双指旋转，裁切框始终被图片覆盖，支持按比例 / 圆形裁切并导出临时文件。

TIP

建议在真机或开启触控模拟的环境下体验双指手势。组件默认开启 webp（便于网络 WebP；通用 Image 组件仍默认关闭）。导出默认 PNG，可通过 file-type 设为 jpg（quality 仅对 jpg 生效）。圆形裁切或需要透明通道时请使用 png，jpg 会丢失透明。GIF 等动图裁切后会变为静态图并丢失动画。部分端对本地 WebP 的 getImageInfo / canvas 支持不稳定，可真机验证；与 Uploader 搭配时可在 after-choose 中跳过不支持格式（见 Uploader 搭配裁切）。

基础用法

传入图片地址，组件会按 aspect-ratio 生成居中裁切框。

<vd-image-cropper
  ref="cropperRef"
  src="/static/exh-1.jpg"
  custom-class="cropper-box"
/>

const cropperRef = ref();

async function handleCrop() {
  const path = await cropperRef.value.crop();
  console.log(path);
}

裁切比例

通过 aspect-ratio 设置裁切框宽高比，例如 16 / 9、4 / 3、1。

<vd-image-cropper :aspect-ratio="16 / 9" src="..." />

圆形裁切

设置 circle 后裁切框为圆形（强制 1:1），圆外区域透明；需透明时请保持 file-type 为 png（默认）。

<vd-image-cropper circle src="..." />

双指旋转

默认开启双指旋转，松手吸附到最近的 90°；不需要时可设 :rotatable="false"。

<vd-image-cropper :rotatable="false" src="..." />

导出尺寸

默认按「裁切框宽度 × export-scale（默认 2）」导出，比屏上框更清晰。也可用 export-width 指定绝对宽度（优先于 export-scale）。

<!-- 默认约 2 倍裁切框宽度 -->
<vd-image-cropper src="..." />

<!-- 指定倍率 -->
<vd-image-cropper :export-scale="3" src="..." />

<!-- 指定绝对宽度 -->
<vd-image-cropper :export-width="1080" src="..." />

API

Props

参数	说明	类型	默认值
src	图片地址	string	''
webp	系统不支持时是否启用 webp（同 image，仅网络资源）	boolean	true
aspect-ratio	裁切框宽高比（宽 / 高）；circle 时固定为 1	number | string	1
crop-size	裁切框相对容器较短边的占比（0~1）	number | string	0.8
max-zoom	最大缩放倍数	number | string	3
zoomable	是否允许双指捏合缩放	boolean	true
wheel-zoom	滚轮单次缩放步进	number | string	0.1
show-grid	是否显示九宫格	boolean	true
circle	是否圆形裁切	boolean	false
rotatable	是否允许双指旋转	boolean	true
height	容器高度	number | string	240
file-type	导出图片类型，可选 png jpg；圆形 / 透明请用 png	ImageExportType	png
quality	导出图片质量（0~1），仅 jpg 时生效	number | string	1
export-scale	导出相对裁切框的倍率（未传 export-width 时生效）	number | string	2
export-width	导出图片宽度（px），优先于 export-scale	number | string	-

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
load	图片信息加载完成	{ width, height }
error	图片加载或处理失败	unknown
crop	导出成功	{ path }

Expose

方法名	说明	参数	返回值
reset	重置缩放、位移与旋转	-	-
getCropArea	获取裁切区域（原图像素 AABB，含 rotate）	-	ImageCropperArea | null
crop	导出裁切图片	-	Promise<string>

类型定义

import type {
  ImageCropperProps,
  ImageCropperEmits,
  ImageCropperArea,
  ImageCropperInstance,
} from 'vital-design';