更新记录

1.0.0（2026-03-09）

• 原生相机预览
• 视频录制
• 最大录制时长限制
• 前后摄像头切换
• 录制进度回调
• 录制文件回调
• iOS 文件路径兜底处理

平台兼容性

uni-app(4.73)

uni-app x(4.83)

xx-face-recorder

xx-face-recorder 是一个 uni-app 原生录制组件，支持 Android / iOS。

• 相机权限申请
• 相机预览
• 自动开始录制
• 录制进度回调
• 录制完成后输出视频路径
• ref 方法调用示例

点击“试用插件”即可直接查看完整模板页示例（index.nvue）

包含整个模板页面的使用示例，内置 nvue 模板页、页面样式、图标、音频和基础录制逻辑。
打自定义基座后运行，控制台会直接打印录制结果，简单直接，方便二次接入。

功能特性

• 原生相机预览
• 视频录制
• 最大录制时长限制
• 前后摄像头切换
• 录制进度回调
• 录制文件回调
• iOS 文件路径兜底处理

权限要求

iOS

• NSCameraUsageDescription
• NSMicrophoneUsageDescription

Android

• android.permission.CAMERA
• android.permission.RECORD_AUDIO

说明：

• 当 mute=true 时，模板页默认不采集麦克风
• 当前模板页默认传入的是 :mute="true"

组件用法

<xx-face-recorder
  ref="recorderRef"
  camera-position="front"
  resolution="720p"
  :mute="true"
  :max-duration-ms="8000"
  @ready="onRecorderReady"
  @recordstart="onRecordStart"
  @recordprogress="onRecordProgress"
  @recordfile="onRecordFile"
  @recordstop="onRecordStop"
  @error="onRecordError"
/>

Props

API

事件

recordprogress 示例：

{
  "durationMs": 1600
}

recordfile / recordstop 示例：

{
  "filePath": "/path/to/face_xxx.mp4",
  "durationMs": 8000
}

补充：

• Android 端可能额外返回 width、height、sizeBytes
• iOS 端可能额外返回 path
• 模板页实际主要使用 filePath 和 durationMs

方法

模板页字段

重点字段：

lastRecordFilePath

• 最近一次录制成功后得到的视频文件路径
• 上传、预览、调试都可以直接用它

lastRecordDurationMs

• 最近一次录制成功的时长，单位毫秒
• 常用于展示录制结果或业务上报

模板页示例方法

模板页里保留了几组最常见的调用示例，index.nvue 和 index.uvue 都可以直接对照参考：

使用示例

1. 通过 ref 调用方法

const recorder = this.$refs.recorderRef

recorder.startPreview()
recorder.startRecord()
recorder.stopRecord()
recorder.switchCamera('back')

const filePath = recorder.getCurrentFilePath()
console.log('当前文件路径：', filePath)

2. 只打印录制结果

async onRecordFile(evt) {
  const filePath = await this.resolveRecordFilePath(evt)
  const durationMs = this.extractDurationMs(evt)
  console.log('录制文件路径：', filePath)
  console.log('录制时长：', durationMs)
}

3. 录制完成后预览视频

async onRecordStop(evt) {
  const filePath = await this.resolveRecordFilePath(evt)
  if (!filePath) return

  uni.previewMedia({
    current: 0,
    sources: [
      {
        url: filePath,
        type: 'video',
      },
    ],
  })
}

模板页关键方法

这些方法建议保留：

• normalizeEventPayload
• readPayloadValue
• resolveRecordFilePath
• ensureCameraPermission
• handleRecordResult

控制台日志

• [identification][permission-result]
• [identification][ready]
• [identification][record-start]
• [identification][record-stop]
• [identification][record-file-ready]
• [identification][record-error]
• [identification][record-file]