更新记录
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、亮度帧采集。
功能介绍
- 拍照、录像、暂停继续、镜头切换、变焦、曝光和对焦。
- 原生预览与 uni-app x 页面内预览,网格、闪光灯及镜像设置。
- I420、NV21、亮度帧,按需读取、旋转、裁剪与连续帧导出。
- 照片、录像、帧文件的本机预览、分享、校验和清理。
平台兼容性
| 项目 | 要求 |
|---|---|
| HBuilderX | 5.26 或更新版本 |
| uni-app / uni-app x | Vue 3;原生 App |
| Android | API 23 起;部分系统能力有更高版本要求 |
| iOS | 15.0 起;以设备能力及宿主配置为准 |
| HarmonyOS | 使用 app-harmony 源码及其声明的 SDK / 权限 |
| Web / 小程序 | 不提供原生能力 |
插件测试使用方法
- 在插件市场绑定自己的项目 AppID,将插件导入项目的
uni_modules/wen-camera。本地使用时也可直接复制完整插件目录。 - 打开“示例项目”,在 HBuilderX 的 manifest 中填写自己的 AppID。需要第三方服务时填写自己申请的配置。
- 制作包含本插件的自定义基座,或重新云打包 App。标准基座、WGT 热更新不能增加原生模块。
- 安装到真机,授予本次操作所需的系统权限,再使用页面中的功能按钮。
- 更换原生依赖、权限或平台配置后重新打包。示例源码和文档不附带 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. 本插件是否包含广告
不包含广告。

收藏人数:
购买源码授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 18
赞赏 0
下载 12771027
赞赏 1959
赞赏
京公网安备:11010802035340号