更新记录

1.0.2（2026-11-03）

• 修复 iOS 选完图立刻导出：裁剪页刚出现时，确认按钮先不接收点击

1.0.1（2026-11-03）

• 声明支持 uni-app x 的 Android 与 iOS

1.0.0（2026-11-03）

• 原生头像裁剪压缩
• 圆形、方形、圆角，输出尺寸、质量和文件大小可改
• 取景 shape 和导出 output 分开。默认圆形取景、方形出图
• 默认英文，支持中文

平台兼容性

uni-app(4.27)

uni-app x(4.27)

其他

fz-avatar-crop

1.0.2

仅 App（Android / iOS）。打开原生页裁剪头像，并按质量和文件大小压缩。图片只在本机处理，不上传、不写系统相册。

取景和导出是两个参数。界面可以是圆形，保存出来的文件仍可以是方形。

不传 locale 时界面是英文。中文传 zh 或 zh-CN。strings 只改要换的词。

拷到 uni_modules 后打自定义基座。改 .kt / .swift / .uts 要重打。只改调用方的 js / vue 不用重打。

环境

插件不申请权限，也不带隐私用途说明。宿主自己选图时，在 manifest.json 里开 Gallery 模块。

用法

import { cropAvatar } from '@/uni_modules/fz-avatar-crop'

const res = await cropAvatar({
    imagePath: filePath,
    size: 512,
    quality: 85,
    maxBytes: 200 * 1024,
    shape: 'circle',
    output: 'square',
    locale: 'zh',
    themeColor: '#2F6FED',
    strings: { title: '设置头像' }
})
// res.path   _doc/fz-avatar-crop/avatar-*.jpg
// res.format jpeg | png
// res.width  res.height  实际边长
// res.bytes  文件字节数

取消是 94304，按取消处理，不要当成失败。H5 和小程序调用是 94308。

try {
    const res = await cropAvatar({ imagePath })
} catch (e) {
    if (e.errCode === 94304) return
    console.log(e.errCode, e.errMsg)
}

常见场景

圆形取景、方形文件。头像控件自己画成圆。这是默认行为。

await cropAvatar({
    imagePath,
    shape: 'circle',
    output: 'square'
})

圆形取景，导出也是圆，圆外透明。文件是 PNG。

await cropAvatar({
    imagePath,
    shape: 'circle',
    output: 'circle',
    mask: true
})

方形取景，圆角文件，圆角外铺白底，仍是 JPEG。

await cropAvatar({
    imagePath,
    shape: 'square',
    output: 'round',
    corner: 0.22,
    fillColor: '#FFFFFF'
})

可配置项

只传要改的字段。没传的保持默认。

format 没传时：

显式传了 format 就按传入的来。JPEG 不能带透明，圆形 JPEG 的形状外是 fillColor。

操作：单指拖动，双指缩放，双击还原。缩放范围是盖住取景框的 1–8 倍。导入时会按 EXIF 把照片转正。

style

没传的项保持内置值。

icons

本地图片路径。按原图显示，不染色。没传的键继续用内置符号。

icons: { close: '/static/close.png' }

文案

strings 只传要改的键，其余仍按 locale。

返回值

同目录只保留最近 8 张。iOS 必须写在 _doc，缓存绝对路径上传读不到。Android 在 _doc 建不出来时，退回缓存绝对路径。

错误码

errSubject 为 fz-avatar-crop。

隐私

无广告，无统计。不申请相册、相机、存储权限。不读取通讯录，不上传图片。选图、上传由宿主自己做。