更新记录

0.1.0（2026-07-19） 下载此版本

初次提交

平台兼容性

uni-app x(4.66)

其他

laoqianjunzi-face

laoqianjunzi-face 是一个面向 uni-app x 的 UTS 人脸能力插件，围绕当前插件内的 FaceHub API 提供统一的人脸引擎初始化、预览编排、图片检测、实时跟踪、智能活体、人脸注册识别与人脸库导入导出能力。

本文档仅说明当前插件已经公开的能力与用法，示例和 API 均以 uni_modules/laoqianjunzi-face/utssdk/interface.uts 为准。

功能概览

• 统一初始化与释放人脸引擎
• 基于 laoqianjunzi-face 的实时预览宿主组件
• 相机预览拍照，直接回收本地图片路径与 Base64
• 单图快速验脸、深度检测、批量检测、特征提取
• 实时人脸跟踪，输出矩形框、姿态、清晰度、活体状态等数据
• 智能活体动作校验，支持 realFace、lookLeft、lookRight、blink、nod、holdStill
• 本地人脸库注册、识别、TopN 检索、删除、清空、导入、导出
• 纯本地数据流转，不主动上传图像与特征向量

支持平台

来自 package.json 的当前声明：

推荐环境：

• HBuilderX 5.07+
• uni-app x 4.66+
• 页面或组件内使用时，优先放在 uni-app x 项目中

权限与前置条件

插件当前声明的权限如下：

• Android：CAMERA、RECORD_AUDIO
• iOS：Camera、Microphone、Photo Library
• Harmony：CAMERA
• Web：首次打开预览时由浏览器请求摄像头权限

使用前请确认：

• 页面已经挂载 laoqianjunzi-face 组件，作为实时预览宿主
• 先调用 initializeFaceHub，再调用预览、跟踪、活体等实时能力
• 图片检测类 API 传入的是本地可读文件路径，例如 uni.chooseImage 返回的路径或 captureFacePhoto 返回的 filePath
• 页面需要滚动时，在 App 端必须使用 <scroll-view> 包裹

目录结构

插件内与使用方最相关的目录：

• utssdk/interface.uts：类型定义与公共 API 约束
• utssdk/index.uts：统一导出入口
• components/laoqianjunzi-face/：预览宿主组件
• pages/index.uvue：完整演示页

快速开始

1. 引入 API 与预览组件

页面脚本中引入统一入口：

import * as FaceHub from '@/uni_modules/laoqianjunzi-face/utssdk/index.uts'

预览组件采用 easycom 方式，模板里直接写：

<laoqianjunzi-face
  class="camera-preview"
  :autoStart="false"
  :enableAudio="false"
  :position="'front'"
></laoqianjunzi-face>

2. 页面最小示例

下面示例展示初始化、打开预览、开始跟踪与页面卸载清理：

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll" :scroll-y="true">
  <!-- #endif -->
    <view class="page">
      <view class="panel">
        <text class="title">laoqianjunzi-face 最小示例</text>
        <laoqianjunzi-face
          class="camera-preview"
          :autoStart="false"
          :enableAudio="false"
          :position="'front'"
        ></laoqianjunzi-face>
      </view>
      <view class="button-row">
        <view class="action-btn" @tap="initEngine">
          <text class="action-btn-text">初始化</text>
        </view>
        <view class="action-btn" @tap="openPreview">
          <text class="action-btn-text">打开预览</text>
        </view>
      </view>
      <view class="button-row">
        <view class="action-btn" @tap="startTracking">
          <text class="action-btn-text">开始跟踪</text>
        </view>
        <view class="action-btn" @tap="closePreview">
          <text class="action-btn-text">关闭预览</text>
        </view>
      </view>
      <text class="result-text">{{ resultText }}</text>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script lang="uts">
import * as FaceHub from '@/uni_modules/laoqianjunzi-face/utssdk/index.uts'

export default {
  data() {
    return {
      resultText: '等待操作'
    }
  },
  onUnload() {
    FaceHub.stopSmartLiveness({})
    FaceHub.stopFaceTracking({})
    FaceHub.closeFacePreview({})
    FaceHub.releaseFaceHub({})
  },
  methods: {
    writeResult(label: string, payload: any) {
      try {
        this.resultText = label + '\n' + JSON.stringify(payload)
      } catch (_error) {
        this.resultText = label
      }
    },
    initEngine() {
      FaceHub.initializeFaceHub({
        activeModel: 'light',
        autoWarmup: true,
        success: (result) => {
          this.writeResult('初始化成功', result)
        },
        fail: (error) => {
          this.writeResult('初始化失败', error)
        }
      })
    },
    openPreview() {
      FaceHub.openFacePreview({
        position: 'front',
        frameFormat: 'rgba',
        maxFps: 10,
        success: (result) => {
          this.writeResult('预览已打开', result)
        },
        fail: (error) => {
          this.writeResult('打开预览失败', error)
        }
      })
    },
    startTracking() {
      FaceHub.startFaceTracking({
        minIntervalMs: 260,
        onTrack: (result) => {
          this.writeResult('跟踪结果', result)
        },
        fail: (error) => {
          this.writeResult('跟踪失败', error)
        }
      })
    },
    closePreview() {
      FaceHub.closeFacePreview({
        success: (result) => {
          this.writeResult('预览已关闭', result)
        }
      })
    }
  }
}
</script>

<style>
.page-scroll {
  flex: 1;
  background-color: #eef3f7;
  flex-direction: column;
}

.page {
  padding: 24rpx;
  background-color: #eef3f7;
  flex-direction: column;
}

.panel {
  padding: 24rpx;
  margin-bottom: 16rpx;
  border-radius: 24rpx;
  background-color: #ffffff;
  flex-direction: column;
}

.title {
  margin-bottom: 16rpx;
  font-size: 32rpx;
  font-weight: 700;
  color: #183046;
}

.camera-preview {
  height: 360rpx;
  flex-direction: column;
}

.button-row {
  margin-bottom: 12rpx;
  flex-direction: row;
}

.action-btn {
  flex: 1;
  height: 84rpx;
  justify-content: center;
  align-items: center;
  border-radius: 18rpx;
  background-color: #1d5a83;
  flex-direction: row;
}

.action-btn-text {
  font-size: 26rpx;
  font-weight: 700;
  color: #ffffff;
}

.result-text {
  font-size: 24rpx;
  line-height: 36rpx;
  color: #3f5568;
}
</style>

推荐调用流程

实时预览与跟踪

1. 页面挂载 laoqianjunzi-face
2. 调用 initializeFaceHub
3. 调用 openFacePreview
4. 调用 startFaceTracking 或 startSmartLiveness
5. 页面销毁时执行 stopFaceTracking、stopSmartLiveness、closeFacePreview、releaseFaceHub

图片验脸与识别

1. 通过 uni.chooseImage 或 captureFacePhoto 获取本地图片路径
2. 调用 quickCheckFaceImage 做快速预检
3. 调用 inspectFaceImage 获取详细检测结果
4. 调用 extractFaceFeatureByFile 提取特征，或直接 registerFaceByFile / identifyFaceByFile

人脸库使用

1. registerFaceByFile 写入 userId
2. identifyFaceByFile 返回最优匹配
3. identifyFaceTopNByFile 获取候选列表
4. exportFaceLibrary 导出后可在下次会话中 importFaceLibrary

预览组件

组件名称：laoqianjunzi-face

该组件负责提供摄像头预览宿主视图。实时预览、跟踪、智能活体等能力都依赖它先完成挂载。

Props

API 一览

引擎生命周期

预览与拍照

图片检测

实时分析

人脸库与识别

模型管理

当前实现中，如果目标平台已经内置模型，downloadFaceModel 会直接返回成功，并通过 onProgress 给出 100% 进度。

核心返回结构

LaoqianjunziFaceEngineState

如果你不想在业务层接触冗余字段，日常状态判断只需关心 ready、previewOpen、trackingActive、smartLivenessActive。

LaoqianjunziFaceTrackSummary

实时跟踪的关键字段：

• faceCount：当前帧检测到的人脸数
• hasFace：是否存在人脸
• primaryRect：主人脸框
• primaryUserId：识别命中的主用户 ID
• primaryScore：匹配分数
• yaw / pitch / roll：姿态角
• eyeLeft / eyeRight：眼睛状态
• smile：微笑分数
• mouthOpened：是否张嘴
• allHeadBody：是否完整进入画面
• liveness：活体状态文本
• clarity / reality：质量分值
• qualityPassed：质量是否通过
• overlays：用于绘制叠加框的数据
• frame：原始帧摘要

LaoqianjunziFaceLivenessProgress

LaoqianjunziFaceLibraryProfile

回调约定

所有 API 都遵循 success / fail / complete 风格。

• success：返回对应能力的结构化结果
• fail：返回 LaoqianjunziFaceFail
• complete：无论成功失败都会执行，参数与最终结果保持一致

失败对象结构：

错误码

使用建议

• 实时能力依赖预览宿主组件，建议页面一进入就先挂载 laoqianjunzi-face
• openFacePreview 前先执行 initializeFaceHub，否则会收到 9013301
• captureFacePhoto、startFaceTracking、startSmartLiveness 都要求预览已打开，否则会收到 9013302
• 识别类业务推荐先 registerFaceByFile 建库，再 identifyFaceByFile 或 identifyFaceTopNByFile
• 如果需要自定义命中阈值，优先使用 identifyFaceTopNByFile，当前实现默认阈值是 0.72
• Web 端请先确保预览组件已挂载，再调用 openFacePreview

示例页面

插件内置了完整演示页：

• 路径：uni_modules/laoqianjunzi-face/pages/index
• 文件：uni_modules/laoqianjunzi-face/pages/index.uvue

演示页覆盖以下流程：

• 初始化引擎、读取状态、打开和关闭预览
• 预览拍照并回灌为图片检测输入
• 实时跟踪与智能活体
• 选择本地图片做快速验脸、深度检测、特征提取
• 注册、识别、TopN 检索、删除、导出、导入、清空人脸库

如果你想直接验证插件能力，优先运行这个页面。