更新记录

1.1.2（2026-10-31）

兼容蒸汽模式 自动对焦 优化分发 ipa 路径问题

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

UTS 人脸引导视频录制（自动对焦、前后摄像头）

用于人脸引导视频采集，保留圆形取景框、眨眼／张嘴文字和语音提示、重新录制、视频预览与保存相册。组件提供原生相机预览和录像，不进行人脸识别或活体判定。

HBuilderX 5.26+；Android 6.0+ / iOS 15.0+；版本 1.1.2。本目录是 uni-app x 的标准组件入口。普通 uni-app 使用同步维护的 austin-face-recorder，放在 .nvue 页面；其录制参数、事件和六个方法保持一致。普通 .vue 页面需跳转到 .nvue 录制页。

第 1 步：放入插件

将整个 austin-face-rec-x 目录放到项目的 uni_modules 下，保留其中的 components、utssdk、static 文件。

业务页面导入的是 组件文件，完整路径为：

import AustinFaceRecX from '@/uni_modules/austin-face-rec-x/components/austin-face-rec-x/austin-face-rec-x.uvue'

不需要在业务页面直接导入 utssdk 内的原生文件。

第 2 步：接入页面

最小示例：

<template>
  <view class="page">
    <austin-face-rec-x
      ref="recorderRef"
      class="camera"
      cameraPosition="front"
      resolution="720p"
      focusMode="continuous"
      :mute="true"
      :maxDurationMs="8000"
      :previewCornerRadiusRate="0.5"
      @recordfile="onRecordFile"
      @error="onRecordError"
    />
    <button @click="startRecord">开始录制</button>
    <button @click="stopRecord">结束录制</button>
  </view>
</template>

<script setup lang="uts">
import { ref, ComponentPublicInstance } from 'vue'
import AustinFaceRecX from '@/uni_modules/austin-face-rec-x/components/austin-face-rec-x/austin-face-rec-x.uvue'

const recorderRef = ref<ComponentPublicInstance | null>(null)

function startRecord(): void {
  recorderRef.value?.$callMethod('startRecord')
}
function stopRecord(): void {
  recorderRef.value?.$callMethod('stopRecord')
}
function recorderData(event: any | null): UTSJSONObject | null {
  if (event == null) return null
  if (event instanceof UTSJSONObject) {
    const object = event as UTSJSONObject
    return object.getJSON('detail') ?? object
  }
  return (event as UniCustomEvent<UTSJSONObject>).detail
}
function onRecordFile(event: any | null): void {
  const result = recorderData(event)
  if (result == null) return
  const filePath = result.getString('filePath') ?? ''
  const durationMs = result.getNumber('durationMs') ?? 0
  console.log(filePath, durationMs)
  // 这里取得的是完成文件。上传用原路径，video 预览需转换 file://，见下方说明。
}
function onRecordError(event: any | null): void {
  const error = recorderData(event)
  if (error == null) return
  uni.showToast({ title: error.getString('errMsg') ?? '录制失败', icon: 'none' })
}
</script>

<style>
.page { flex: 1; padding: 20px; }
.camera { width: 300px; height: 300px; }
</style>

组件挂载后自动准备预览并申请相机权限。需要在相机准备完成后自动录像时，监听 ready 再调用 startRecord()；插件附带的完整演示页已接好。

要直接使用原版引导布局，在项目 pages.json 中增加：

{
  "path": "uni_modules/austin-face-rec-x/index",
  "style": { "navigationBarTitleText": "人脸引导视频录制", "disableScroll": true, "pageOrientation": "auto" }
}

该页内置视频预览，不依赖项目另建预览页；图标和语音均来自插件自己的 static 目录。

第 3 步：权限与基座

如果使用演示页的 保存相册 按钮，在项目根目录创建 Info.plist，添加以下相册用途；已有该文件时，只合并 <dict> 内的键，不覆盖其他配置。不使用保存相册时可跳过。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>用于将用户主动保存的录制视频写入相册</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>用于用户主动保存和查看录制视频</string>
  </dict>
</plist>

配置位置见 DCloud iOS 原生配置说明。

首次导入或更新原生代码后，重新制作并安装包含本插件的自定义基座，再运行 .uvue 页面。正式包使用相同的插件与权限配置；iOS 真机打包仍使用项目自己的签名证书和描述文件。

相机画面、录制清晰度与对焦效果需要有摄像头的设备。模拟器只能覆盖其支持的相机与文件流程，iOS 模拟器没有可用摄像头时会返回错误。

第 4 步：体验与调整

打开演示页并允许相机权限，按原有流程自动开始录制，依次显示正脸、眨眼和张嘴提示。录制结束后可预览、保存或重新录制。

分辨率不会替代对焦。部分前置摄像头为固定焦距，不能强制提供硬件不支持的自动对焦；设备不支持指定分辨率或对焦模式时按可用能力处理，视频实际像素见完成事件的 width、height。

横屏录制

1. 在 pages.json 的录制页 style 中设置 "pageOrientation": "auto" 随设备旋转；固定横屏使用 "landscape"，固定竖屏使用 "portrait"。
2. iOS 项目若限制了方向，在项目根目录 Info.plist 的 <dict> 内合并下列配置，并重新打基座。已有该键时只补齐横屏项；iPad 同理使用 UISupportedInterfaceOrientations~ipad。

<key>UISupportedInterfaceOrientations~iphone</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
  <string>UIInterfaceOrientationLandscapeLeft</string>
  <string>UIInterfaceOrientationLandscapeRight</string>
</array>

录制前先转到目标方向。每段视频固定使用开始时的方向，录制中转屏不会旋转已开始的片段；下一次录制采用新方向。演示页横屏为相机左侧、引导和操作右侧，竖屏保留原布局。视频带方向信息，预览与上传使用原文件，不要根据 orientationDegrees 再次旋转。

页面配置见 DCloud 横竖屏配置。

Props

建议沿用示例中的 camelCase 属性名。

组件方法

通过组件 ref 的 $callMethod() 调用，方法名保持原版：

事件

平台的 recordfile、recordstop 先后顺序可能不同。业务选择一个完成事件处理即可；同时监听时按 filePath 去重，避免重复上传。

ready 的可选能力字段

完成结果字段

iOS 通过系统录制完成回调生成结果，不再按“文件是否已出现”猜测完成。成功事件返回的是已经写完、可读取且非空的视频，不要自行改成 _doc/face_record.mp4，也不要拼接 Pandora、AppID 或应用容器目录。

预览时只转换播放器的 src，不要修改上传使用的 filePath。附带演示页已处理：

const videoSrc = filePath.startsWith('/') ? 'file://' + filePath : filePath
// <video :src="videoSrc" />
// uni.uploadFile({ filePath, ... }) 继续使用原路径。

绝对沙盒路径不是永久网络地址。需要长期保存时由业务管理文件与相对标识；不要跨安装、升级直接复用旧容器的绝对地址。上传、预览或保存完成后，文件清理也由业务按需处理。

错误字段