人脸检测（FaceDetector）使用指导：数人脸、看微笑和睁眼

• 它能做什么
• 准备工作
• 案例一：检测人脸数量
• 案例二：读取第一张脸的微笑和睁眼概率
• 案例三：打开摄像头实时检测人脸
• 案例四：每张脸都戴上帽子
• 结果数据说明
• 常见问题
• 完整 .aia 源码与操作指导

« 返回

机器学习套件(ML Kit)组件在在线版和教育版中提供，离线版（含机房版）不包含。

它能做什么

人脸检测找出照片里的所有人脸，给出每张脸的位置框、微笑概率、左右眼睁开概率和头部三轴转角，可用于自拍时提示闭眼、统计人数、按人脸裁剪等。它是检测不是识别：不判断这个人是谁。

准备工作

• 表情分类：「表情分类」打开（默认）才会给出微笑与睁眼概率。
• 精确模式：更准但更慢；「最小人脸比例」默认 0.1，脸太小的不报。
• 联机调试：安卓上用 AI 伴侣调试需要安装 MLKit 版 AI 伴侣（应用宝，包名 cn.fun123.appinventor）；普通版伴侣不含识别引擎，调用时会触发「屏幕.出现错误时」（错误码 4722）。直接打包 APK 安装测试不受影响。
• 安装包体积：只有用到本组件的 App 才会打包它的识别引擎与模型，体积以编译结果为准。
• 鸿蒙：部分支持：人脸位置与头部转角可用；鸿蒙系统不提供微笑、睁眼概率和跟踪编号，这几项为 null；实时摄像头检测暂不支持，「打开实时摄像头」会触发「检测失败时」。

案例一：检测人脸数量

相册和拍照都调同一个过程；检测成功事件直接给出人脸数：

procedure 检测(路径) {
  图像_预览.Picture = 路径
  人脸检测1.AccurateMode = 复选框_精确.Checked
  人脸检测1.DetectFromFile(路径)
}
when 图像选择器_相册.AfterPicking() { 检测(图像选择器_相册.Selection) }
when 照相机1.AfterPicture(图像位址) { 检测(图像位址) }
when 人脸检测1.DetectionSuccess(结果JSON, 人脸数) {
  标签_状态.Text = join("检测到 ", 人脸数, " 张人脸")
}

案例二：读取第一张脸的微笑和睁眼概率

解析结果 JSON 的 faces 数组，取第一项的概率与转角（概率是 0～1，乘 100 换成百分比）：

when 人脸检测1.DetectionSuccess(结果JSON, 人脸数) {
  if 人脸数 > 0 {
    var 第一张 = select(dictget(Web客户端1.JsonTextDecodeWithDictionaries(结果JSON), "faces", list()), 1)
    标签_结果.Text = join("微笑概率：", round(dictget(第一张, "smilingProbability", 0) * 100), "%")
    标签_详情.Text = join("左眼睁开：", round(dictget(第一张, "leftEyeOpenProbability", 0) * 100), "%  右眼睁开：", round(dictget(第一张, "rightEyeOpenProbability", 0) * 100), "%")
  }
}

案例三：打开摄像头实时检测人脸

界面放一个黑底的垂直布局当预览区，点「实时检测」时把它设为「预览容器」再「打开实时摄像头」。画面上直接框出人脸、标出微笑概率（「显示标注」默认开）；「实时检测到人脸」按「实时事件间隔」（默认 200 毫秒）触发，里面只更新几个标签，不要做重活：

when 按钮_实时.Click() {
  人脸检测1.UseFrontCamera = 复选框_前置.Checked
  人脸检测1.PreviewContainer = 垂直布局_预览
  人脸检测1.StartLiveCamera()
}
when 按钮_停止.Click() { 人脸检测1.StopLiveCamera() }
when 人脸检测1.LiveFaces(人脸数, 图片宽度, 图片高度, 结果JSON) {
  if 人脸数 == 0 {
    标签_状态.Text = "实时：画面里没有人脸"
  } else {
    var 第一张 = select(dictget(Web客户端1.JsonTextDecodeWithDictionaries(结果JSON), "faces", list()), 1)
    标签_状态.Text = join("实时：", 人脸数, " 张人脸")
    标签_结果.Text = join("微笑概率：", round(dictget(第一张, "smilingProbability", 0) * 100), "%")
  }
}

案例四：每张脸都戴上帽子

人脸检测的贴图锚点用人脸框：FACE_TOP 上沿中点、FACE_CENTER 中心、FACE_BOTTOM 下沿中点（开启「特征点」后还能用眼睛、鼻底、嘴角等）；宽度按人脸框宽计，随歪头旋转。画面里有几张脸就贴几顶：

when 按钮_帽子.Click() { 人脸检测1.AddSticker("帽子", "tophat.png", "FACE_TOP", 1.1, 0, -0.3) }
when 按钮_摘下.Click() { 人脸检测1.RemoveSticker("帽子") }
when 按钮_保存.Click() { 人脸检测1.CaptureLiveFrame() }
when 人脸检测1.LiveFrameCaptured(图片地址) {
  图像_照片.Picture = 图片地址
}

结果数据说明

结果JSON：{"faceCount":1,"faces":[{"bounds":{"left":…,"top":…,"right":…,"bottom":…},"headEulerAngleX":5.1,"headEulerAngleY":-3.2,"headEulerAngleZ":0.8,"smilingProbability":0.92,"leftEyeOpenProbability":0.97,"rightEyeOpenProbability":0.95,"trackingId":null}]}。转角 X 为上下点头、Y 为左右转头、Z 为歪头，单位度。

常见问题

完整 .aia 源码与操作指导

下载 .aia 源码

导入 FaceDetectorDemo.aia 后可以直接打包 APK 运行；用 AI 伴侣联机调试请安装 MLKit 版 AI 伴侣。源码文件已通过正式编辑器载入、后台导入和 APK 编译校验；真机识别效果请以实际设备为准。

案例界面与积木源码在仓库 docs/markdown/reference/components/guide/examples/FaceDetectorDemo/，SHA-256：b6a778d18e4eb796b5ef9abd2380143097a7002f1ef0acfa456fbaea7fbb7700。