更新记录

1.0.0（2026-10-04）

支持打开前后摄像头，拍照，录像，闪光灯，变焦，浮窗

平台兼容性

uni-app(3.8.5)

uni-app x(3.8.5)

其他

fa-camera 插件使用说明

功能简介

fa-camera 是 uni-app nvue 原生摄像头组件（UTS 插件），基于 Android Camera2 实现，提供完整的摄像头预览与拍摄能力：

• 摄像头与预览尺寸查询
• 打开 / 释放相机预览
• 拍照（JPEG 文件路径或 Base64）
• 静默获取当前帧
• 视频录制（MP4 / H.264 / AAC）
• 前后摄像头切换
• 点击聚焦、双指缩放
• 常亮闪光灯控制

平台支持

本插件为 uni-app 兼容模式组件（UTS 组件），仅支持在 uni-app 项目的 nvue 页面中使用；不支持 uni-app x，不支持 App 的 vue 页面（非 nvue）。

环境要求

• HBuilderX 3.6.18 及以上（UTS 组件最低要求）
• 运行、云打包或自定义基座调试均可；真机验证需使用包含该插件的自定义基座或云打包

接入方式

1. 在 uni-app 项目中，通过 HBuilderX「插件市场」搜索 fa-camera 并导入（uni_modules 方式，无需在 manifest.json 的「App 原生插件配置」中操作）。
2. 在 nvue 页面模板中引入组件：

<template>
    <view class="page">
        <fa-camera ref="camera" class="camera"
            @openresult="onResult" @pictureresult="onResult" @cameraerror="onError" />
    </view>
</template>

<style>
    .camera {
        width: 300px;
        height: 400px;
        background-color: #000000;
    }
</style>

3. 通过 this.$refs.camera 调用组件方法，异步结果通过组件事件（@事件名）返回，事件回调参数 event.detail 为结果对象。

本插件为原生组件，必须使用 nvue 页面（.nvue 文件）；标准运行基座不包含原生插件，运行调试需使用自定义基座或云打包。

API 说明

公共约定：所有事件结果均包含 success 字段；失败时包含 code 与 message。结果通过 event.detail 获取。

组件方法

组件事件

调用示例

// 打开预览（自动请求相机权限）
this.$refs.camera.openCamera()

// 获取摄像头列表
this.$refs.camera.getCameras()

// 拍照（返回 JPEG 缓存文件路径）
this.$refs.camera.takePicture({ base64: false, quality: 80 })

// 静默获取当前帧
this.$refs.camera.getCurrentImage({ base64: false, quality: 80 })

// 切换摄像头
this.$refs.camera.switchCamera(targetCameraId)

// 开始 / 停止录像
this.$refs.camera.startRecord({
    videoWidth: 1280,
    videoHeight: 720,
    videoEncodingBitRate: 3000000,
    videoFrameRate: 30
})
this.$refs.camera.stopRecord()

// 缩放与闪光灯
this.$refs.camera.setZoomFactor(2)
this.$refs.camera.flashOpen()

// 释放相机
this.$refs.camera.release()

// 监听事件（示例：拍照结果）
onPictureResult(event) {
    const result = event.detail
    if (result.success) {
        console.log(result.img)
    }
}

权限说明

权限被拒绝时，对应事件会返回 success: false 及可读错误信息（如 CAMERA_PERMISSION_DENIED、RECORD_AUDIO_PERMISSION_DENIED）。

注意事项

• 摄像头 id 是设备返回的标识，请结合 facing（back / front / external）使用，不要假定固定为 0 或 1。
• 拍照、取帧和录像文件写入应用缓存目录，属于应用私有存储，插件不会自动上传；缓存可能被系统清理，请及时处理文件。返回路径不带 file:// 前缀，用于上传或展示时按宿主 API 要求处理。
• 录像期间请勿同时执行拍照、切换镜头、缩放或闪光灯操作。
• 设备不支持数字缩放时，@zoomresult / @maxzoomresult 返回 value: 1、supported: false。
• 插件不采集任何数据，不包含任何网络请求。