更新记录

0.2.0（2026-07-20）

• 新增 custom 自绘相册（序号选择、即时校验、大图预览、主题色、中英文），Android 无权限时自动降级 system
• 新增 camera 系统相机拍照/录像
• system 模式：Android Photo Picker / iOS PHPicker，零权限；自动 HEIC 转 JPG、视频抽帧封面

平台兼容性

uni-app(3.99)

其他

zoo-media-picker

一次打开相册，图片和视频同屏混排、混着一次选完。

uni.chooseImage 只能选图，uni.chooseMedia 的 mediaType 实际上也没法在一次会话里让用户既挑照片又挑视频——用户要传「3 张照片 + 1 段视频」，就得点两次入口、走两遍流程。这个插件解决的就是这件事。

特性

• 图片视频混选：一次打开，同屏混排，任意勾选
• 零权限：Android 走系统 Photo Picker、iOS 走 PHPicker，不申请 READ_MEDIA_IMAGES，不触发相册授权弹窗，Google Play 敏感权限声明表也不用填
• 零第三方依赖：不引 Glide / SDWebImage / RxJava，不和宿主 App 已有的库打架
• 脏活都包了：HEIC/HEIF 自动转 JPG、视频自动抽首帧封面、iCloud 未下载资源自动拉取、Android content:// 自动落盘成可上传的真实文件
• API 对齐官方：走 uni.chooseMedia 的参数与返回约定，另附 Promise 版本

快速开始

import { chooseMediaPro } from '@/uni_modules/zoo-media-picker'

chooseMediaPro({
  count: 9,
  mediaType: ['image', 'video'],
  success: (res) => {
    res.tempFiles.forEach((file) => {
      console.log(file.mediaType, file.tempFilePath, file.size)
    })
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  }
})

Promise 版本：

import { chooseMediaProAsync } from '@/uni_modules/zoo-media-picker'

try {
  const res = await chooseMediaProAsync({ count: 9 })
  console.log(res.tempFiles)
} catch (err) {
  console.log(err.errCode, err.errMsg)
}

仅支持 App（Android / iOS），H5 与小程序不支持。 UTS 插件必须打自定义基座才能真机调试，标准基座下不生效。

参数

返回

success 回调收到：

{
  tempFiles: ZooMediaFileItem[]
  openTypeUsed: string   // 实际生效的模式，请求 custom 时这里会是 'system'
}

每个 ZooMediaFileItem：

错误码

errMsg 会带上具体是哪个文件、超了多少，可直接提示给用户。

三种模式（openType）

任何降级都通过 success.openTypeUsed 如实告知实际生效的模式，不走 fail。请求 custom 但被降级时 openTypeUsed 会是 'system'。

custom 模式所需权限（宿主自行在 manifest.json 声明）：

• Android：READ_MEDIA_IMAGES / READ_MEDIA_VIDEO（13+），READ_EXTERNAL_STORAGE（≤12）。上架 Google Play 的宿主需自行处理敏感权限声明；不上架商店的宿主无此顾虑。
• iOS：NSPhotoLibraryUsageDescription。

各平台行为

Android

• 插件不在 AndroidManifest 里声明任何权限，装上不会给宿主 App 增加任何权限。
• count 在 Photo Picker 上由系统强制；ACTION_GET_CONTENT 分支系统不限数量，插件会在选完后校验并返回 9012006。

iOS

• iOS 14+ 是绝对主流路径，不需要任何隐私描述。
• iOS 13 及以下：插件坚持不硬写隐私描述（否则会给宿主 App 平白加上相册权限、影响审核）。宿主若没声明，插件返回 9012005 而不是闪退。要支持这条分支，请在宿主的 manifest.json → App 权限配置里补 NSPhotoLibraryUsageDescription。

FAQ

Q：为什么图片的 thumbTempFilePath 和 tempFilePath 一样？ 图片本身就能直接渲染，再生成一份缩略图纯属浪费。回填自身路径是为了让前端统一只认 thumbTempFilePath，不用对图片和视频写两套渲染分支。

Q：为什么 GIF 选完还是原来那么大？ GIF 和 WebP 可能是动图，重编码只会留下第一帧、动画就没了。所以插件对这两类只做原样拷贝，sizeType: ['compressed'] 对它们不生效。只有 JPEG / PNG / HEIC 会被重编码，其中 PNG 用 PNG 编码保住透明通道。

Q：maxFileSize 是选之前限制还是选之后？ system 模式下 UI 是系统的，插件无法在用户勾选的瞬间拦截，只能选完再校验并返回 9012008；custom 模式则在选中时即时校验时长、超限当场拦截。另外，会被压缩的图片按压缩后的体积校验——原图 12MB、压缩后 800KB，在 maxFileSize: 1MB 下是通过的。

Q：视频会被压缩吗？ 不会。sizeType 只作用于图片。视频原样落盘，避免转码耗时和画质损失。

Q：HEIC 一定能转成 JPG 吗？ Android 9 以下的系统解码器不支持 HEIF，这种情况下插件会原样拷贝，并如实把 fileExtension 保留为 heic（不会谎报成 jpg），前端可据此自行降级。iOS 全版本原生支持，不受影响。

Q：选中的顺序能保证吗？ 能。iOS 15+ 开了 .ordered 选择模式，返回顺序即用户勾选顺序；Android Photo Picker 与系统返回顺序一致。

授权说明

本插件按 uni appid + 包名 粒度授权，一次购买绑定一个应用。更换 appid 或包名需重新购买。