更新记录

1.0.0(2026-11-18)

第一版


平台兼容性

uni-app(4.51)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ - - √ √ 6.0 15 √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(4.51)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - 6.0 15 √ -

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

wen-camera

自定义拍照录像、CameraX / AVFoundation 预览和 I420、NV21、亮度帧采集。

功能介绍

  1. 拍照、录像、暂停继续、镜头切换、变焦、曝光和对焦。
  2. 原生预览与 uni-app x 页面内预览,网格、闪光灯及镜像设置。
  3. I420、NV21、亮度帧,按需读取、旋转、裁剪与连续帧导出。
  4. 照片、录像、帧文件的本机预览、分享、校验和清理。

平台兼容性

项目 要求
HBuilderX 5.26 或更新版本
uni-app / uni-app x Vue 3;原生 App
Android API 23 起;部分系统能力有更高版本要求
iOS 15.0 起;以设备能力及宿主配置为准
HarmonyOS 使用 app-harmony 源码及其声明的 SDK / 权限
Web / 小程序 不提供原生能力

插件测试使用方法

  1. 在插件市场绑定自己的项目 AppID,将插件导入项目的 uni_modules/wen-camera。本地使用时也可直接复制完整插件目录。
  2. 打开“示例项目”,在 HBuilderX 的 manifest 中填写自己的 AppID。需要第三方服务时填写自己申请的配置。
  3. 制作包含本插件的自定义基座,或重新云打包 App。标准基座、WGT 热更新不能增加原生模块。
  4. 安装到真机,授予本次操作所需的系统权限,再使用页面中的功能按钮。
  5. 更换原生依赖、权限或平台配置后重新打包。示例源码和文档不附带 Key、Token、账号密码或签名私钥。

示例页面

示例直接在各个 .uvue 页面的 <script setup lang="uts"> 中导入并调用相机插件,无需额外的 api.uts。首页包含状态、能力和原始帧调用;拍摄页直接申请权限、绑定原生预览和发送相机控制;文件页直接调用预览、分享、校验、打包和删除。state.uts 只保存跨页面的当前相机配置,options.uts 保存参数描述。

使用示例

import { nativeCameraRequest } from '@/uni_modules/wen-camera'

nativeCameraRequest('open', JSON.stringify({
  "config": {
    "mode": "photo",
    "lens": "back",
    "audioEnabled": false
  },
  "consent": true
}), (raw: string) => {
  const result = JSON.parseObject(raw)
  if (result == null) return
  if (result.getNumber('code') != 0) {
    uni.showToast({ title: result.getString('message') ?? '操作失败', icon: 'none' })
    return
  }
  console.log(result['data'])
})

API 介绍

原生入口接收 operation、JSON 字符串 payload 和回调。回调统一返回 { code, message?, data? };code 为 0 表示成功。

nativeCameraRequest

nativeCameraRequest(operation: string, payload: string, done: (result: string) => void): void

requestCameraPermissions

requestCameraPermissions(audio: boolean, done: (granted: boolean) => void): void

bindCameraPreview

bindCameraPreview(element: UniNativeViewElement, payload: string, done: (result: string) => void): void

配置参数

配置通过打开/启动操作传入;其他操作参数以示例调用为准。

参数 类型 默认值 说明
mode enum "photo" 工作模式;可选 photo / video / analysis
lens enum "back" 默认镜头;可选 back / front
cameraId string "" 指定逻辑相机 ID;最长 80
allowLensFallback boolean true 缺少镜头时使用其他镜头
allowUseCaseFallback boolean true 允许明确提示后降级
orientation enum "portrait" 屏幕方向;可选 portrait / auto
analysisWidth number 640 分析目标宽度;最小 160;最大 1920
analysisHeight number 480 分析目标高度;最小 120;最大 1080
analysisFps number 8 分析最高帧率;最小 1;最大 30
backpressure enum "latest" 背压策略;可选 latest / block
queueDepth number 2 阻塞模式队列深度;最小 1;最大 4
frameFormat enum "i420" 帧输出格式;可选 i420 / nv21 / luma
rotateFrames boolean true 将帧旋转至显示方向
mirrorFrames boolean false 水平镜像输出帧
cropLeftPercent number 0 裁剪左边距 %;最小 0;最大 80
cropTopPercent number 0 裁剪上边距 %;最小 0;最大 80
cropWidthPercent number 100 裁剪宽度 %;最小 10;最大 100
cropHeightPercent number 100 裁剪高度 %;最小 10;最大 100
lumaSampleStep number 4 亮度统计采样间距;最小 1;最大 32
photoMode enum "latency" 拍照策略;可选 latency / quality
jpegQuality number 92 JPEG 质量;最小 30;最大 100
flash enum "off" 照片闪光灯;可选 off / auto / on
photoMirror boolean false 照片水平镜像
videoQuality enum "hd" 录像目标画质;可选 sd / hd / fhd / uhd
audioEnabled boolean false 录制麦克风音轨
videoBitrate number 0 目标视频码率,0 为自动;最小 0;最大 40000000
maxVideoDurationSec number 60 单段录像最长秒数;最小 1;最大 3600
maxVideoBytes number 67108864 单段录像最大字节数;最小 1048576;最大 1073741824
torch boolean false 默认开启补光
zoomRatio number 1 初始变焦倍率;最小 0.5;最大 20
exposureIndex number 0 曝光补偿档位;最小 -24;最大 24
focusAutoCancelMs number 3000 对焦自动取消毫秒,0 为锁定;最小 0;最大 30000
tapToFocus boolean true 点击预览对焦
volumeKeyCapture boolean true 音量键拍照
previewScale enum "fit" 预览缩放;可选 fit / fill
previewImplementation enum "compatible" 预览实现;可选 compatible / performance
showGrid boolean true 显示九宫格
showStats boolean true 显示帧统计
keepScreenOn boolean true 前台保持亮屏
burstFrameCount number 12 单次原始帧导出上限;最小 1;最大 120
burstIntervalMs number 200 导出帧最小间隔毫秒;最小 34;最大 5000
burstMaxBytes number 16777216 单次帧导出字节上限;最小 1048576;最大 134217728
maxStorageMB number 256 插件私有目录容量上限 MiB;最小 32;最大 2048
maxMediaFiles number 40 照片视频文件数上限;最小 1;最大 500
filenamePrefix string "camera" 文件名前缀;最长 24

JavaScript 封装接口

普通 uni-app 页面可使用插件目录中的 client.js。调用前先完成平台权限申请;异步操作用 await / catch 处理。具体参数类型见同目录的 client.d.ts 或 index.d.ts。

cameraPipeline

从 client.js 导入。

方法与参数 原生 operation
open(config, consent=false) open
status() status
capabilities() capabilities
command(name, value={}) command
latestFrame(afterSequence=0, maxBytes=1048576) frame
files() files
share(path) share
openMedia(path) openMedia
inspectFile(path) inspectFile
diagnostics() diagnostics
deleteFile(path) deleteFile
clearFrame() clearFrame

生成相机配置

createCameraConfig(options) 接收配置对象,补齐 schema 默认值并校验参数。不传参数时使用默认配置。

import { createCameraConfig, cameraPipeline } from '@/uni_modules/wen-camera/client.js'

const config = createCameraConfig({
  mode: 'video',
  videoQuality: 'fhd',
  audioEnabled: true
})
// 用户确认本次采集后,在页面事件中调用。
await cameraPipeline.open(config, true)

使用注意

  • 分辨率、帧率与同时启用的采集用例取决于设备;读取 capabilities 后选择配置。
  • 录像音轨需要麦克风权限。前后台切换、锁屏会释放采集资源,以返回状态为准。
  • 原始帧按需读取,避免在页面上持续传输大段 Base64。

隐私、权限声明

1. 本插件需要申请的系统权限列表

<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>

iOS 用途说明在 app-ios/Info.plist 中,鸿蒙权限在 app-harmony/module.json5 中;宿主仍需按实际业务说明用途并配置能力。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明

用户授权后在本机采集相机画面及可选麦克风音频,文件默认保存在应用内;插件不主动上传。

3. 本插件是否包含广告

不包含广告。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:相机权限 CAMERA,用于预览、拍照、录像和原始帧采集;麦克风权限 RECORD_AUDIO,仅在录制有声视频时使用。 iOS:相机和麦克风授权,对应用途说明为 NSCameraUsageDescription、NSMicrophoneUsageDescription。 HarmonyOS:CAMERA、MICROPHONE、ACCELEROMETER,用于相机采集、录像音轨和设备方向检测。 图片和视频默认保存在应用私有目录,文件导入、导出和分享通过系统授权的方式进行。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。