更新记录

1.0.4（2026-07-22）

视频录制预览页面

平台兼容性

uni-app(5.21)

uni-app x(5.21)

Zoom Camera UTS

zoom-camera 是一个面向 uni-app App-nvue 的原生相机预览与视频录制组件，支持 Android 和 iOS。组件提供录像参数配置、开始/停止录像、录像结果回调，以及 Android 端的拍照、切换摄像头、闪光灯、缩放和分辨率查询等扩展能力。

功能特性

• 原生相机画面实时预览
• 支持开始、停止视频录制
• 支持设置保存目录、文件名、清晰度、分辨率、码率和帧率
• 支持录制声音
• 支持 Android、iOS
• Android 端支持拍照、前后摄像头切换、闪光灯、缩放和相机能力查询

平台兼容性

组件依赖原生相机能力，请使用自定义基座或云打包后的 App 测试，无法在普通 HBuilderX 标准基座中直接使用。

环境要求

• HBuilderX 5.07 及以上
• 使用 nvue 页面
• 真机具备可用摄像头

安装

将插件导入项目的 uni_modules 目录后，可通过 easycom 直接使用，无需手动导入组件。

<zoom-camera></zoom-camera>

权限说明

插件已声明以下权限：

• Android：android.permission.CAMERA
• Android：android.permission.RECORD_AUDIO
• iOS：NSCameraUsageDescription
• iOS：NSMicrophoneUsageDescription

首次使用时系统会请求相机权限；启用录音时还会请求麦克风权限。业务页面应根据权限结果向用户提供明确提示，并处理用户拒绝授权的情况。

基础用法

以下示例展示相机预览、开始录像、停止录像和接收录像文件路径的完整流程。

<template>
  <view class="page">
    <zoom-camera
      ref="camera"
      class="camera"
      record-save-path="_doc/Zoom-Camera"
      :record-file-name="fileName"
      :record-add-audio="true"
      record-video-quality="fullhd"
      :record-video-width="1920"
      :record-video-height="1080"
      :record-video-bit-rate="12000000"
      :record-video-frame-rate="30"
      @videoresult="onVideoResult"
    />

    <view class="actions">
      <button :disabled="isRecording" @click="startRecord">开始录像</button>
      <button :disabled="!isRecording" @click="stopRecord">停止录像</button>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      fileName: '',
      isRecording: false
    }
  },
  methods: {
    startRecord() {
      this.fileName = `video_${Date.now()}.mp4`
      this.$nextTick(() => {
        this.$refs.camera.startVideoCaptureByProps()
      })
    },
    stopRecord() {
      this.$refs.camera.stopVideoCapture()
    },
    onVideoResult(event) {
      const result = event.detail || event

      if (result.status === 'start') {
        this.isRecording = true
        return
      }

      if (result.status === 'end') {
        this.isRecording = false
        if (result.error) {
          uni.showToast({ title: result.error, icon: 'none' })
          return
        }
        console.log('录像文件：', result.filePath)
      }
    }
  },
  beforeDestroy() {
    this.$refs.camera?.releaseCamera()
  }
}
</script>

<style>
.page {
  flex: 1;
}

.camera {
  flex: 1;
}

.actions {
  height: 80px;
  flex-direction: row;
  align-items: center;
  justify-content: space-around;
}
</style>

组件属性

视频质量

record-video-quality 支持以下值：

设备不支持指定分辨率、帧率或质量时，插件会根据设备能力选择可用配置。不同设备的最终输出参数可能存在差异。

事件

videoresult

录像状态变化或录像结束时触发。

<zoom-camera @videoresult="onVideoResult" />

事件结果字段：

iOS 与 Android 的原生事件包装可能不同。建议使用 const result = event.detail || event 兼容读取。

通用方法

以下方法可在 Android 和 iOS 使用。

startVideoCaptureByProps()

根据组件属性开始录像，录像状态通过 videoresult 事件返回。

this.$refs.camera.startVideoCaptureByProps()

startVideoCaptureByConfig(...)

使用参数直接开始录像。

this.$refs.camera.startVideoCaptureByConfig(
  '_doc/Zoom-Camera',
  `video_${Date.now()}.mp4`,
  true,
  0,
  0,
  'fullhd',
  1920,
  1080,
  12000000,
  30,
  0
)

参数顺序：

stopVideoCapture()

停止录像。文件写入完成后，通过 videoresult 事件返回 status: 'end' 和文件信息。

this.$refs.camera.stopVideoCapture()

releaseCamera()

停止未完成的录制并释放相机资源。页面销毁或不再显示相机时应主动调用。

this.$refs.camera.releaseCamera()

setRotation(rotation)

设置预览及录制方向。rotation 为字符串或 null，具体效果取决于设备方向和系统相机实现。

this.$refs.camera.setRotation('90')

Android 扩展方法

以下方法仅 Android 端提供。调用前请通过条件编译隔离，避免在 iOS 运行时调用不存在的方法。

拍照

this.$refs.camera.captureImage(
  {
    savePath: '_doc/Zoom-Camera',
    format: 'jpg',
    quality: 90
  },
  (result) => {
    console.log('图片路径：', result.filePath)
  },
  (result) => {
    console.log('Base64：', result.base64)
  }
)

切换摄像头

不传 cameraId 时在前后摄像头之间切换。

this.$refs.camera.switchCamera()
// 或指定摄像头
this.$refs.camera.switchCamera({ cameraId: 1 })

闪光灯与手电筒

this.$refs.camera.setFlash('auto')
this.$refs.camera.setTorch('on')
this.$refs.camera.setTorch('off')

常用模式包括 on、off、auto 和 torch，实际支持情况取决于摄像头硬件。

相机缩放

this.$refs.camera.getMaxZoomFactor((result) => {
  console.log('最大缩放值：', result.value)
})

this.$refs.camera.getZoomFactor((result) => {
  console.log('当前缩放值：', result.value)
})

this.$refs.camera.setZoomFactor(2)

相关方法：

• getMinZoomFactor(callback)
• getMaxZoomFactor(callback)
• getZoomFactor(callback)
• setZoomFactor(value)

查询摄像头与分辨率

this.$refs.camera.android_getCameras((result) => {
  console.log('摄像头列表：', result.cameras)
})

this.$refs.camera.android_getSupportedVideoSizes((sizes) => {
  console.log('录像分辨率：', sizes)
})

相关方法：

• android_getCameras(callback)
• android_getSupportedPictureSizes(callback)
• android_getSupportedVideoSizes(callback)
• android_getSupportedPreviewSizes(callback)
• android_setCameraParams(params)
• setVideoQuality(quality)

注意事项

1. 组件仅支持 App-nvue 页面，不支持 App-vue、H5、小程序和 uni-app x。
2. 建议在真机上测试录像能力，模拟器通常无法完整验证相机、麦克风和硬件编码。
3. 开始录像前必须确保组件已经完成布局并处于可见状态，宽高不能为 0。
4. 调用停止录像后，应等待 videoresult 返回 status: 'end'，再读取、上传或移动视频文件。
5. 页面销毁、切换页面或隐藏相机前应调用 releaseCamera()，避免相机资源被占用。
6. 录音依赖麦克风权限；不需要声音时可将 record-add-audio 设为 false。
7. iOS 最终视频通常为 MOV 容器，建议文件名使用 .mov；Android 使用 .mp4。
8. 高分辨率、高码率和高帧率会显著增加存储、内存和设备发热，请按业务场景合理设置。

常见问题

相机区域黑屏

请依次检查：

• 当前页面是否为 nvue 页面
• 是否已授予相机权限
• 组件是否具有非零宽高且处于可见状态
• 是否使用包含本插件的自定义基座或云打包 App
• 其他页面或应用是否正在占用相机

点击开始录像后立即失败

通过 videoresult 的 error 字段查看具体错误。常见原因包括相机或麦克风权限被拒绝、保存目录不可用、分辨率不受设备支持，或相机尚未完成初始化。

停止录像后获取不到文件

stopVideoCapture() 是异步操作。不要在调用后立即读取文件，应等待 videoresult 返回 status: 'end'，并以返回的 filePath 为准。