更新记录

1.0.0（2026-11-03）

• 新增 module 方式无预览拍照：前后摄像头、画质档位 quality（uhd / fhd / hd / sd）、jpegQuality 压缩质量、自定义文件名 / 目录、可选 base64 输出
• 新增 module 方式无预览录像：开始 / 结束录制，画质档位 quality（uhd / fhd / hd / sd）、可选录音、自定义文件名 / 目录
• 新增 isRecording 判断当前是否正在录像
• 新增 deleteFile 删除指定图片 / 视频文件
• 新增 getSupportedSizes 查询摄像头支持的画质档位，按像素总数从大到小排列，quality 可直接传给 takePhoto / startRecord
• 新增 requestPermission 相机（可选录音）运行时权限申请
• 新增 component 方式（nvue）zy-camera-view：内嵌预览 + 预览拍照 / 预览录像 / 前后摄像头切换 / 闪光灯（off、on、auto、torch）
• 预览画面等比显示，不变形、不裁剪，比例不一致时四周留空
• 支持通过 onEvent 接收原生事件：ready / takePhoto / startRecord / stopRecord / switchCamera / flash / error
• 输出目录为 App 外部存储目录 Android/data/<包名>/files/zy-camera（外部存储不可用时回退内部 filesDir）
• 仅支持 Android，运行与调试需使用自定义基座

平台兼容性

uni-app(4.72)

uni-app x(4.72)

插件介绍

Android 相机 UTS 插件。同时提供两种引用方式：module 方式支持无预览拍照、无预览录像与删除指定图片；component 方式（nvue）支持在页面上内嵌相机预览并完成拍照、录像、前后摄像头切换与闪光灯控制。支持 uni-app（vue / nvue 页面）。

使用场景

• 页面需要静默抓拍（考勤、巡检、取证），不能出现取景画面，由 module 直接返回图片路径或 base64
• 后台记录现场视频片段，不需要用户看到预览画面
• nvue 页面需要一块内嵌取景区域，由用户自行构图后拍照 / 录像
• 业务流程结束后清理本次产生的图片、视频文件

使用流程

1. 申请权限：requestPermission({ audio }, callback) 申请相机权限（录像收音时同时申请录音权限）。
2. 无预览拍照：takePhoto({ front, quality, jpegQuality, base64 }, callback)（quality 为画质档位），成功后取 data.path / data.base64。
3. 无预览录像：startRecord({ front, quality, audio }, callback) 开始录制（quality 为画质档位）→ 业务处理 → stopRecord(callback) 结束并取视频路径与时长。
4. 预览拍摄（nvue）：页面放置 <zy-camera-view> 组件 → 收到 ready 事件后调用组件方法 takePhoto / startRecord / stopRecord，结果统一从 onEvent 事件取。
5. 删除文件：deleteFile({ path }, callback) 删除指定图片 / 视频。

用法

import {
    requestPermission,
    takePhoto,
    startRecord,
    stopRecord,
    deleteFile,
    isRecording
} from '@/uni_modules/zy-camera'

申请相机权限

requestPermission({
    audio: false, // 是否同时申请录音权限，默认 false
    success: (res) => {
        console.log(res.granted, res.audioGranted)
    },
    fail: (err) => {
        console.log(err.errCode, err.errMsg)
    }
})

无预览拍照

takePhoto({
    front: false,      // true 使用前置摄像头，默认 false（后置）
    quality: 'fhd',    // 画质档位：'uhd' | 'fhd' | 'hd' | 'sd'，不传则取最大 JPEG 尺寸
    jpegQuality: 95,   // JPEG 压缩质量 1~100，默认 95
    base64: false,     // 是否在结果中附带 base64，默认 false
    fileName: '',   // 文件名，可带或不带 .jpg，默认按时间戳生成
    dir: '',        // 保存目录绝对路径，默认 App 外部存储目录/zy-camera/photo
    success: (res) => {
        console.log(res.path, res.size, res.width, res.height)
    },
    fail: (err) => {
        console.log(err.errCode, err.errMsg)
    }
})

默认保存目录为 App 外部存储目录 /storage/emulated/0/Android/data/<包名>/files/zy-camera/photo（应用专属外部存储，无需存储权限）；外部存储不可用时自动回退到内部 filesDir。

无预览录像

startRecord({
    front: false,
    quality: 'fhd',  // 画质档位：'uhd' | 'fhd' | 'hd' | 'sd'，默认 'fhd'
    audio: false,    // true 需要录音权限
    success: (res) => {
        // 只表示"已开始"，此时文件还没有内容，路径要等 stopRecord
        console.log(res.msg)
    }
})

// 业务处理结束后结束录制
stopRecord({
    success: (res) => {
        console.log(res.path, res.duration, res.size)
    },
    fail: (err) => {
        console.log(err.errCode, err.errMsg)
    }
})

// 当前是否正在录制
console.log(isRecording())

删除指定图片 / 视频

deleteFile({
    path: imagePath, // 支持 file:// 前缀
    success: (res) => {
        console.log(res.deleted, res.path)
    },
    fail: (err) => {
        console.log(err.errCode, err.errMsg)
    }
})

查询设备支持的画质档位

返回该摄像头实际支持的档位（uhd / fhd / hd / sd），width / height 是各档位的标准分辨率，quality 可直接传给 takePhoto / startRecord：

getSupportedSizes({
    front: false,   // 查询前置摄像头传 true
    success: (res) => {
        // res.list 按像素总数从大到小排列，可直接取 res.list[0] 作为最高画质
        // 示例：[{ quality:'uhd', width:3840, height:2160 }, { quality:'fhd', width:1920, height:1080 }, ...]
        console.log(res.list)
    },
    fail: (err) => {
        console.log(err.errCode, err.errMsg)
    }
})

该方法只读取摄像头能力信息，不打开相机、不占用相机资源，也不会与预览 / 录制冲突。

nvue 页面内嵌预览相机

组件默认全局注册，直接使用标签。必须指定明确宽高，否则原生画面无法渲染。

画面等比显示：完整、不变形、不裁剪，与组件比例不一致时四周留空；前后摄像头切换时镜像与方向自动纠正。

插件（组件与 module 方式均）必须使用自定义基座运行与打包。

<zy-camera-view
    ref="camera"
    style="width:750rpx;height:420px"
    :front="false"
    flash="off"
    @onEvent="onEvent"
/>

onEvent(e) {
    const detail = e.detail // { type, code, msg, dataJson }
    const data = JSON.parse(detail.dataJson || '{}')
    if (detail.code != 0) {
        console.log('失败：' + detail.type + ' ' + detail.code + ' ' + detail.msg)
        return
    }
    // type 取值：ready / takePhoto / startRecord / stopRecord / switchCamera / flash / error
}

// 组件方法
this.$refs.camera.start({ front: true, flash: 'off' })
this.$refs.camera.takePhoto({ quality: 'fhd', jpegQuality: 95, base64: false })
this.$refs.camera.startRecord({ quality: 'fhd', audio: false })
this.$refs.camera.stopRecord()
this.$refs.camera.switchCamera()
this.$refs.camera.setFlashMode('torch')
this.$refs.camera.stop()

闪光灯方法名为 setFlashMode（off / on / auto / torch），不能写成 setFlash，会与组件属性 flash 冲突。

插件方法

组件方法

回调结果结构（module）

// takePhoto 成功回调 res
{
    code : 1,             // 恒为 1
    msg : '拍照成功',      // 描述信息
    path : '',            // 图片文件绝对路径
    name : '',            // 文件名（含后缀）
    size : 0,             // 文件大小（字节）
    width : 0,            // 图片实际宽度（像素）
    height : 0,           // 图片实际高度（像素）
    base64 : ''           // 传 base64:true 时为 data:image/jpeg;base64,...，否则空串
}

// startRecord 成功回调 res（开始录制不返回文件信息，此刻文件还没有内容）
{
    code : 1,
    msg : '录制已开始'
}

// stopRecord 成功回调 res
{
    code : 1,
    msg : '录像已结束',
    path : '',
    name : '',
    size : 0,             // 文件大小（字节）
    duration : 0          // 录制时长（毫秒）
}

// deleteFile 成功回调 res
{
    code : 1,
    msg : '文件已删除',
    path : '',            // 已去掉 file:// 前缀的路径
    deleted : true        // true=本次确实删除，false=文件本来就不存在
}

// getSupportedSizes 成功回调 res
{
    code : 1,
    msg : '共 3 档画质',
    front : false,           // 实际查询的朝向
    list : [                 // 按像素总数降序
        { quality : 'uhd', width : 3840, height : 2160 },
        { quality : 'fhd', width : 1920, height : 1080 },
        { quality : 'hd',  width : 1280, height : 720 }
    ]
}

// 失败回调 err（UniError）
{
    errSubject : 'zy-camera',
    errCode : 9200002,    // 见错误码表
    errMsg : '未获得相机权限'
}

事件结构（component）

// onEvent 的 e.detail
{
    type : 'takePhoto',   // ready / takePhoto / startRecord / stopRecord / switchCamera / flash / error
    code : 0,             // 0 表示成功，非 0 为错误码
    msg : '拍照成功',      // 描述信息
    dataJson : '{}'       // 具体数据 JSON 字符串，需自行 JSON.parse
}

// dataJson 解析后的字段
// ready        : { front : false, width : 1280, height : 720, flash : 'off' }
// takePhoto    : { path : '', name : '', size : 0, width : 0, height : 0, base64 : '' }
// startRecord  : {}（开始录制不回文件信息）
// stopRecord   : { path : '', name : '', size : 0, duration : 0 }
// switchCamera : { front : true }
// flash        : { flash : 'torch' }
// error        : {}

错误码

权限说明