更新记录

1.0.0（2026-10-09）

首个版本。

• 矩形裁剪（crop with shape: 'rect'），区域越界自动钳制
• 圆形裁剪（cropCircle），Android / Harmony 支持真圆，iOS 输出中心正方形并 warn
• 圆角裁剪（cropRound），半径支持 fixed 像素 / percent 比例 / scale 短边倍数三种模式
• 中心正方形裁剪（cropSquare），三端行为一致
• 九宫格切片（slice9），聊天场景
• 平台能力查询：isRoundedSupported() / supportedShapes()，供业务按平台走分支
• 三端原生实现：
  • Android —— Bitmap.createBitmap + Canvas.clipPath + Path.addRoundRect
  • Harmony —— readPixelsSync 取 RGBA 逐像素算 alpha + createPixelMap 重建
  • iOS —— CIImage.cropped 零重采样裁剪（圆角受类型库限制，见 readme）

平台兼容性

uni-app(3.99)

其他

czg-imgcrop 图片裁剪圆角

图片裁剪、圆形与圆角处理、九宫格切片。Android 与 Harmony 支持真圆角裁剪。

平台能力（重要）

iOS 端做不出圆角，原因是 HBuilderX4.76 的 iOS 类型库有两个硬缺口：

1. UIImage.drawInRect 未暴露，只剩 drawAsPattern（平铺填充，无法定位绘制）
2. UIGraphicsImageRenderer.image(actions) 的闭包签名是 ()=>any，不接受参数，拿不到 CGContext，因此无法 clip 圆角路径；而 CoreImage 没有减法混合滤镜，也表达不出圆角遮罩

iOS 端调用 cropCircle / cropRound 时插件会输出有效图片（不会给你坏图），并打console.warn 说明。但那不是圆角图。

用这个 API 判断该怎么走：

import { isRoundedSupported, supportedShapes } from '@/uni_modules/czg-imgcrop/index.js'

if (isRoundedSupported()) {
  cropRound('/path/photo.jpg', 20, '/path/out.png')   // 真圆角
} else {
  // iOS：交给 CSS
  // <image style="border-radius: 20rpx" />
}

平台支持

API

crop(path, options)

统一裁剪入口。

import { crop } from '@/uni_modules/czg-imgcrop/index.js'

// 矩形裁剪
const r1 = crop('/path/photo.jpg', {
  x: 100, y: 200, width: 500, height: 500,
  outPath: '/path/cropped.jpg',
  format: 'jpg', quality: 90
})
// { path: '/path/cropped.jpg', size: 45678, width: 500, height: 500, format: 'jpg' }

// 圆形（默认输出 png 保留透明）
const r2 = crop('/path/photo.jpg', { shape: 'circle' })

// 圆角
const r3 = crop('/path/photo.jpg', {
  shape: 'round', radius: 20, format: 'png'
})

// 圆角按比例（需给 width/height 供换算）
const r4 = crop('/path/photo.jpg', {
  shape: 'round', radius: 0.15, radiusMode: 'percent',
  width: 800, height: 600
})

options

radiusMode 为 percent / scale 时需要同时给 width / height（插件靠它取短边换算像素半径）。

区域超出图片范围时会自动钳制到图片边界，不报错。

cropCircle(path, outPath)

取中心正方形 + 挖圆（Android / Harmony）。

cropRound(path, radius, outPath)

圆角裁剪，半径单位像素。

cropSquare(path, outPath)

取中心正方形，不做形状处理（三端一致）。

slice9(path, dir, format)

九宫格切片，聊天场景用。

const r = slice9('/path/big.png', '/path/slices', 'png')
// { dir: '/path/slices', count: 9, width: 300, height: 300, format: 'png' }
// 生成 1.png ~ 9.png，按行优先编号

输出目录不存在会自动创建。

错误处理

抛出的 Error 带 error.code：

隐私

全部处理在本机完成，不联网、不采集、不上传任何图片。

价格

普通授权版由 DCloud 对 uts 源码加密保护，运行时经云端解密编译；源码授权版提供完整 uts 源码，可自行修改与扩展，同样享受后续版本升级。

隐私说明

本插件全部图片处理在本机完成，不联网、不采集、不上传任何图片或数据。插件不主动读取相册与存储目录，输入完全由调用方通过参数传入。隐私声明详见 package.json 的 dcloudext.declaration。

更新日志

见 changelog.md

开源协议

MIT