tmui4x 2.0(Vapor)

主题

TMUI4x2026-09-21
1410
5.9m

x-facerec-u 离线人脸识别(单独付费) ​

离线人脸识别：检测、入录、图片 / 相机帧 1:N 匹配，并提供嵌入式实时识别 UI 组件。可选用内置模型，不必自备。

兼容性 ​

HarmonyIOSAndroidWEB小程序
支持支持支持不支持不支持

组件（推荐） ​

<x-facerec-u> 是标准 UI 组件，直接嵌入页面即可实时识别：相机采集、SCRFD 检测、ArcFace 1:N、跟踪、人脸框绘制全在原生层闭环，帧不跨插件搬运。命中底库绘绿框标「人名 可信度%」，未命中绘橙框标「未识别」。识别依赖 loadModels 先就绪（组件与 API 共享同一原生单例与底库）。

html
<x-facerec-u ref="facerecRef" style="width:100%;height:320px"
  :auto-open="true" camera-position="front" :detect-interval="120" :draw-box="true"
  @ready="onReady" @recognize="onRecognize" @capture="onCapture" @error="onError"></x-facerec-u>
属性说明默认
camera-positionfront / back，运行中改值热切换front
torch闪光灯（前置通常不支持）false
detect-interval相邻两次识别最小间隔 ms，框由原生插值平滑跟随120
draw-box是否绘制人脸框与人名标签true
auto-open视图初始化后自动请求权限并开流true
事件说明
@ready相机开流成功（含切换镜头重开）
@recognize识别结果（faces：trackId/name/score/recognized/box）
@capturetakePhoto() 抓拍完成，含 imagePath 与最近识别结果
@error权限/相机/抓拍错误

组件方法（ref 调用）：open() / close() / takePhoto() / setTorch(on) / setDetecting(on) / isDetecting() / switchCamera()。开相机即开始检测，setDetecting(false) / close() 都会关掉相机，不再保留「预览在、识别停」的中间态。

调用 ​

ts
import { loadModels, enroll, recognizeImage, recognizeFrame } from "@/uni_modules/x-facerec-u"

loadModels({
  detModel: "det_500m",
  recModel: "w600k_mbf",
  similarityThresh: 0.4,
  confidenceThresh: 0.5,
  maxFaces: 1,
  success: (res) => {
    console.log(res.gallerySize)
  }
})

enroll({
  userId: "u1001",
  name: "张三",
  imagePath: facePath,
  success: (res) => {
    console.log(res.quality)
  }
})

recognizeImage({
  imagePath: probePath,
  success: (res) => {
    if (res.matches.length > 0) {
      console.log(res.matches[0].userId, res.matches[0].score)
    }
  }
})

recognizeFrame({
  width: 640,
  height: 480,
  format: "nv21",
  frameBuffer: data,
  rotation: 90,
  success: (res) => {
    console.log(res.matches)
  }
})

实时识别优先用上方 <x-facerec-u> 组件或 openCamera 弹层，二者均在原生层闭环，无需自己搬帧。

方法 ​

名称需要说明
loadModelsdetModel?、recModel?、modelRoot?、阈值等，见下方加载模型，不传 modelRoot 用内置
unloadModels可选回调卸载模型
detectFacesimagePath只检测人脸框和关键点，不比对底库
enrolluserId、imagePath，可选 name、replace入录到底库；replace=true 覆盖该用户旧样本
recognizeImageimagePath用图片做 1:N 识别，返回 matches / unknownFaces
recognizeFramewidth、height、format、frameBuffer 或 frameBase64、rotation?用相机帧做 1:N 识别
listUsers可选回调列出底库用户
removeUseruserId删除指定用户
clearGallery可选回调清空底库
setOptionsconfidenceThresh?、similarityThresh?、livenessThresh?、maxFaces?运行中改阈值
openCameracameraPosition?、torch?、detectInterval?、drawBox?、事件回调打开原生全屏弹层实时识别（不想改页面布局时用）
getRuntimeInfo无同步返回运行时与是否已就绪
getState无返回 idle / loading / ready / error

参数 ​

loadModels

字段说明默认
modelRoot自定义模型目录，空则用内置内置
detModeldet_500m / det_2.5g / det_10gdet_500m
recModelw600k_mbf；w600k_r50 需自备w600k_mbf
confidenceThresh检测阈值0.5
similarityThresh识别阈值0.4
livenessThresh活体阈值0.5
enrollMinQuality入录最低质量0.6
maxFaces每帧最多人脸1
galleryDir底库目录应用私有目录

recognizeFrame：width / height / format（nv21 / bgra / rgba）/ frameBuffer 或 frameBase64 / rotation / orientation。

平台差异 ​

  1. 无 Web / 微信。
  2. 帧格式与 x-camrea-u 对齐：Android nv21，iOS bgra，鸿蒙 rgba。前置镜头注意 mirrored / orientation。

版本 ​

版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。

更新日志 ​

0.3.0（2026-08-20） ​

  • 模块更名 x-facerec-s → x-facerec-u：由 API 插件升级为「标准 UI 组件 + API」双形态
  • 新增 <x-facerec-u> 嵌入式组件：相机预览 + 人脸框 overlay 直接嵌页面， 采集/检测/识别/跟踪/绘框全在原生层闭环，不再依赖 x-camrea-u 跨插件搬帧
  • 组件属性 camera-position / torch / detect-interval / draw-box / auto-open， 事件 @ready / @recognize / @capture / @error， 方法 open / close / takePhoto / setTorch / setDetecting / switchCamera
  • 原有全部 API（loadModels / enroll / recognizeImage / recognizeFrame / openCamera 等）保留，组件与 API 共享同一原生单例与底库
  • 修复 Android 打开测试页闪退、鸿蒙实时识别延迟大且检不出人： 移除 ORT XNNPACK 执行提供器（Android 上建会话原生段错误、鸿蒙上反而更慢），回归纯 CPU EP（NEON），与 iOS 63ms 同款配置
  • 原生库更名 libx_facerec_u.so，JNI/NAPI 符号与 Kotlin 包名同步更新
  • 修复 Android / Harmony 实时检得出人脸却对不上底库、检测框反着跑： 前摄不再把镜像写进推理像素（与相册录入同朝向），只在 overlay 水平翻转框
  • Android 实时分析帧不再开 CameraX 输出旋转：该选项会裁掉 FOV 且打乱 YUV 平面，导致预览在、检不出人
  • 修复 Android 嵌入式检测框偏小（只框到眼嘴）：自行按预览尺寸建 ViewPort（native-view 里 getViewPort 常为空）， 分析帧 16:9 + cropRect；嵌入式 TextureView；CSS 盒×像素比校正 overlay 尺度

0.2.0（2026-08-08） ​

  • 接入 ONNX Runtime 真实推理（SCRFD 检测 + 5 点对齐 + ArcFace 特征）
  • 三端各自准备 ORT：Android Maven 1.28 / iOS xcframework 1.28 / Harmony OHOS 1.27
  • 构建脚本步骤 [0] 调用 third_party/onnxruntime/prepare_*.sh（不再从 sherpa 顺手抽库）
  • 内置模型：det_500m / det_2.5g / det_10g + w600k_mbf（约 35MB）
  • loadModels() 可不传 modelRoot，自动使用内置模型
  • Android aar / Harmony har / iOS Frameworks 均含对应平台 ORT + 模型

0.1.0（2026-08-08） ​

  • 初版框架：Android / iOS / HarmonyOS 三端骨架
  • 共享 C++ 核心 + JSON Bridge；交叉编译脚本
  • API：loadModels / enroll / detectFaces / recognizeImage / recognizeFrame / 底库管理
最近更新