机器学习套件(ML Kit)组件
- 能力一览
- 文字识别
  - 快速上手
  - 属性
  - 事件
  - 方法
- 条码识别
  - 快速上手
  - 属性
  - 事件
  - 方法
- 文档扫描（暂未开放）
  - 快速上手
  - 属性
  - 事件
  - 方法
- 手写识别
  - 快速上手
  - 属性
  - 事件
  - 方法
- 人脸检测
  - 快速上手
  - 属性
  - 事件
  - 方法
- 姿势检测
  - 快速上手
  - 属性
  - 事件
  - 方法
- 语言识别
  - 快速上手
  - 属性
  - 事件
  - 方法
- 人像分割
  - 快速上手
  - 属性
  - 事件
  - 方法
- 图像标注
  - 快速上手
  - 属性
  - 事件
  - 方法
- 目标检测（暂未开放）
  - 快速上手
  - 属性
  - 事件
  - 方法
- 离线翻译
  - 快速上手
  - 属性
  - 事件
  - 方法
- 面部网格
  - 快速上手
  - 属性
  - 事件
  - 方法
- 智能回复
  - 快速上手
  - 属性
  - 事件
  - 方法
- 实体抽取
  - 快速上手
  - 属性
  - 事件
  - 方法
- 自定义图像分类（暂未开放）
  - 快速上手
  - 属性
  - 事件
  - 方法
- 自定义目标检测（暂未开放）
  - 快速上手
  - 属性
  - 事件
  - 方法
- 手势识别
  - 快速上手
  - 属性
  - 事件
  - 方法
- 即教即识
  - 快速上手
  - 属性
  - 事件
  - 方法

机器学习套件(ML Kit)组件

基于 Google ML Kit 的离线识别能力（手势识别、即教即识基于同属 Google 的 MediaPipe，ML Kit 的面部网格、姿势检测本身也是用它做的），内置组件，直接从设计器「机器学习套件(ML Kit)」分类拖出来用。

适用版本：本系列组件在在线版和教育版中提供，离线版（含机房版）不包含。
随 App 打包：只有用到某个组件的 App 才会打包它的识别模型与引擎，没用到的 App 体积不变。
AI 伴侣联机调试：识别引擎体积较大，普通版 AI 伴侣不包含，联机调试请安装 MLKit 版 AI 伴侣（应用宝，包名 cn.fun123.appinventor）；普通版伴侣里调用会触发「屏幕.出现错误时」（错误码 4722）提示换伴侣。编译 APK 不受影响，直接打包安装运行即可。
鸿蒙：每个组件下面写明了鸿蒙上的支持情况。暂不支持的组件在鸿蒙工程里照常打开和编译，调用方法时触发失败事件说明原因。

能力一览

一句话总结：这套组件把 Google ML Kit 与 MediaPipe 的离线 AI 能力（看图认物、读字、理解语言、手写输入）搬进积木——拖出来就能用，识别在本机完成不上传，只有用到模型的 App 才会增加体积。

组件	一句话总结	常用方法 → 主要事件	实时摄像头	底层技术	模型与联网	鸿蒙支持
文字识别	离线 OCR：图片和摄像头里的字都能认，支持中英日韩和天城文	`识别图片文件`→`识别成功`；`打开实时摄像头`→`实时识别到文字`	✓	ML Kit Vision 文字识别 v2	模型随包，完全离线	完整支持图片（系统 OCR，语种由系统决定）；实时暂不支持
条码识别	离线扫条码/二维码，按内容直接给结构化结果（网址、WiFi、名片、短信…）	`开始扫码`→`扫描到条码` 及各内容事件；`识别图片文件`	✓	ML Kit Vision 条码识别	模型随包，完全离线	完整支持（系统 ScanKit，内容解析对齐）
手写识别	画布上手写的字直接变文本，300+ 语言	`开始识别`→`获得文本时`；`下载模型`	—	ML Kit Digital Ink 数字手写	手写引擎随包；语言包首用联网下载，之后离线（国内可能失败）	暂不支持
人脸检测	找到脸并给出表情与朝向（是检测不是识别，不认是谁）	`检测图片文件`→`检测成功`；`打开实时摄像头`→`实时检测到人脸`	✓	ML Kit Vision 人脸检测	模型随包，完全离线	部分支持：位置与头部转角可用；微笑/睁眼概率、实时、贴纸不支持
姿势检测	33 个人体关键点，做体感游戏、健身计数、动作打分	`检测图片文件`→`检测成功`；`打开实时摄像头`→`实时检测到姿势`	✓	ML Kit Pose（MediaPipe BlazePose）	模型随包，完全离线（精确模式换更准模型）	部分支持：17 个主要关键点；精确模式、实时不支持
语言识别	判断一段文本是什么语言（100+ 种）	`识别语言`→`识别出语言`	—	ML Kit 自然语言·语言识别	模型随包，完全离线	暂不支持
人像分割	一键抠人像、换背景、背景虚化，直接出 PNG	`抠出人像`/`换图片背景`/`背景虚化`→`获得结果时`	✓	ML Kit 人像分割	模型随包，完全离线	完整支持图片（系统主体分割，人宠物皆可）；实时不支持
图像标注	说出照片里有什么（400+ 通用类别+置信度）	`标注图片文件`→`获得标签`；`打开实时摄像头`→`实时获得标签`	✓	ML Kit Vision 图像标注	模型随包，完全离线	暂不支持
离线翻译	50+ 语言互译，全程本机完成不上传	`翻译`→`获得译文时`；`下载模型`	—	MLKit 自然语言·端侧翻译	语言包约 30MB/语言，首用联网下载，之后离线（国内可能失败）	暂不支持
面部网格	468 点面部网格（含 x/y/z），AR 贴纸、美颜、眨眼张嘴检测的基础	`检测图片文件`→`获得面部网格`；`关键点`/`全部关键点JSON`；`打开实时摄像头`→`实时检测到面部网格`	✓	MediaPipe Face Mesh	模型随包，完全离线	暂不支持
智能回复	输入法式快捷回复，1~3 条候选（仅英语）	`生成回复建议`→`获得回复建议`	—	MLKit 自然语言·智能回复	模型随包，完全离线	暂不支持
实体抽取	从文本里挑出地址、日期时间、电话、邮箱、金额、快递单号等并给位置	`抽取实体`→`获得实体`；`下载模型`	—	ML Kit 自然语言·实体抽取	语言模型首用联网下载，之后离线（国内可能失败）	完整支持（系统自然语言能力，类型编号相同并有扩展）
手势识别	认 7 种内置手势（握拳、点赞、剪刀手…）+ 21 个手部关键点	`检测图片文件`→`获得手势`；`打开实时摄像头`→`实时检测到手`	✓	MediaPipe Hands	模型随包，完全离线（Android 7.0+）	暂不支持
即教即识	现拍现教：每个类别拍几张样本，App 就能实时分辨新东西	`从摄像头采集样本`→`样本已添加`；`打开实时摄像头`→`实时分类`；`保存模型`/`加载模型`	✓	MediaPipe 图像特征提取（Teachable Machine 同思路）	特征提取模型随包，完全离线（Android 7.0+）	暂不支持

文字识别指导
条码识别指导
手写识别指导
人脸检测指导
姿势检测指导
语言识别指导
人像分割指导
图像标注指导
离线翻译指导
面部网格指导
智能回复指导
实体抽取指导
手势识别指导
即教即识指导

文字识别

离线图片文字识别（OCR）。识别模型随 App 打包，设备无需 Google Play 服务，断网也能用。支持拉丁字母（英文等）、中文（简繁）、日文、韩文、天城文（印地语等）五种脚本。AI 伴侣联机调试需使用 MLKit 版伴侣。

鸿蒙：完整支持图片识别：调用系统文字识别，语种由系统决定（中英文为主），「识别脚本」只保存取值、不切换模型。实时摄像头识别暂不支持，「打开实时摄像头」会触发「识别失败」事件说明原因。

使用指导拍照或选图离线识别中英文文字查看 →

快速上手

when Screen1.Initialize() {
  TextRecognizer1.Script = "chinese"
}
when 图像选择器1.AfterPicking() {
  标签1.Text = "识别中…"
  TextRecognizer1.RecognizeFromFile(图像选择器1.Selection)
}
when TextRecognizer1.RecognitionSuccess(文本, 结果JSON) {
  标签1.Text = 文本
}
when TextRecognizer1.RecognitionFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在识别。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
识别脚本: 识别脚本，决定用哪套模型。可选值：latin（拉丁字母，英文/法文/西文等，默认）、chinese（中文，简体繁体都能认，也能认其中夹杂的拉丁字母）、japanese（日文）、korean（韩文）、devanagari（天城文，印地语/马拉地语/尼泊尔语等）。非拉丁脚本的模型都能顺带认出夹杂的英文。填了认不出的值会回退到 latin。
显示标注: 是否在预览画面上框出识别到的每一行文字。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

实时识别到文字(文本,结果JSON): 实时识别的结果，按「实时事件间隔」限频触发，参数与「识别成功」相同；画面里没有文字时 text 为空。
识别失败(操作,错误信息): 文字识别失败。
识别成功(文本,结果JSON): 文字识别成功。text 为全文，resultJson 为包含文字块、行、元素和坐标的 JSON 文本。

方法

识别Base64图片(Base64文本): 识别 Base64 图片中的文字。支持纯 Base64 或 data:image/…;base64, 前缀。
识别图片文件(路径): 识别图片文件中的文字。参数可以是资源文件、file://、content:// 或本地路径。
打开实时摄像头(): 打开摄像头实时识别文字，画面显示在「预览容器」里，并在画面上框出每一行文字。结果按「实时事件间隔」触发「实时识别到文字」事件，对准就能读，不用先拍照。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

条码识别

离线条码 / 二维码识别。既能识别图片里的条码，也能打开摄像头实时扫描。模型随 App 打包，设备无需安装 Google Play 服务，断网也能用。支持 QR、Data Matrix、PDF417、Aztec 等二维码，以及 EAN-13/8、UPC-A/E、Code-39/93/128、ITF、Codabar 等一维条码。识别结果除通用的「扫描到条码」事件外，还会按内容类型触发网址 / WiFi / 名片 / 短信等专用事件。

鸿蒙：完整支持：调用系统扫码（ScanKit）；网址、WiFi、名片等内容类型按通行格式解析后触发对应事件，系统扫码界面自带取景与手电筒。

使用指导识别图片或摄像头里的条码，按内容类型分别处理查看 →

快速上手

when 图像选择器1.AfterPicking() {
  CodeScanner1.RecognizeFromFile(图像选择器1.Selection)
}
when CodeScanner1.GotBarcode(原始内容, 格式, 内容类型, 显示内容, 详情JSON) {
  标签1.Text = 原始内容
}
when CodeScanner1.NoBarcodeFound(操作) {
  标签1.Text = "这张图里没有找到条码"
}

属性

正在识别: 是否正在识别图片。
连续扫描: 实时扫描是否连续识别。false（默认）扫到第一个条码就自动停止摄像头；true 则持续扫描，适合连续扫多个条码的场景（同一个条码在 1.5 秒内不会重复触发）。
码制: 要识别的条码类型，多个用英文逗号分隔。填 all 表示全部类型（默认）。可选值：qr、datamatrix、pdf417、aztec、ean13、ean8、upca、upce、code39、code93、code128、itf、codabar。只勾选实际需要的类型可以显著提升识别速度。
预览容器: 用来显示摄像头预览画面的可见组件，一般选一个水平布局或垂直布局。在设计器里选好即可，「开始扫描」会把画面放进它里面。该布局需要有明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
正在扫描: 摄像头实时扫描是否正在进行。
手电筒: 闪光灯（手电筒）开关，仅在实时扫描进行中有效。

事件

扫描到条码(原始内容,格式,内容类型,显示内容,详情JSON): 扫描到条码（任何类型都会触发）。rawValue 是条码原始内容；format 是条码格式（如 QR_CODE、EAN_13）；valueType 是内容类型（如 URL、WIFI、TEXT）；displayValue 是适合直接显示给用户的文本；detailJson 是结构化详情（含边界坐标和该类型的全部字段）。
扫描到日程(说明,描述,地点,开始时刻,结束时刻): 扫描到日历事件二维码。时间为 yyyy-MM-dd HH:mm:ss 文本，缺省时为空。
扫描到名片(名称,电话,邮箱,单位,标题,地址,网址): 扫描到名片（联系人）二维码。多个网址用英文逗号分隔。
扫描到驾照(名,姓,证件号,出生日期,有效期至): 扫描到驾照 / 身份证件条码（主要是北美 PDF417 规范）。
扫描到邮件(地址,主题,正文,类别): 扫描到电子邮件二维码。
扫描到位置(纬度,经度): 扫描到地理位置二维码。
扫描到电话(数值,类别): 扫描到电话号码二维码。
扫描到短信(电话号码,消息): 扫描到短信二维码。
扫描到网址(标题,URL网址): 扫描到网址类二维码。
扫描到WiFi(WiFi名称,密码,加密方式): 扫描到 WiFi 配置二维码。encryption 为 OPEN、WPA 或 WEP。
未找到条码(操作): 图片里没有找到任何条码。operation 是发起识别的方法名。
扫描失败(操作,错误信息): 识别或扫描失败。operation 是出错的方法名。

方法

识别Base64图片(Base64文本): 识别 Base64 图片中的条码。支持纯 Base64，也支持带 data:image/…;base64, 前缀的写法。
识别图片文件(路径): 识别图片文件中的条码。参数可以是素材文件名、本地路径、file:// 或 content:// 地址。
开始扫码(): 打开摄像头开始实时扫描，预览画面显示在「预览容器」属性指定的组件里。扫到条码后触发「扫描到条码」事件；若「连续识别」为否则自动停止。
停止扫描(): 停止摄像头实时扫描并移除预览画面。

文档扫描（暂未开放）

暂未开放：扫描模块由 Google Play 服务下发，无 GMS 的设备用不了；兼容问题解决前该组件已从组件面板隐藏，文档保留供了解。

文档扫描：调起系统扫描界面，自动识别纸张边缘、纠正透视，支持裁剪、滤镜、去阴影污点，可导出 JPG 图片和 PDF 文件。返回的是可以直接使用的文件路径（能直接给「图像」组件显示、「分享」组件发送）。注意：扫描界面由 Google Play 服务提供，设备必须装有 Google Play 服务，首次使用需要联网下载扫描模块；没有 GMS 的设备会触发「扫描失败」事件。

鸿蒙：暂不支持：调用方法会触发「扫描失败」事件说明原因。

使用指导拍纸质文档，自动矫正并导出图片和 PDF查看 →

快速上手

when 按钮_扫描.Click() {
  DocumentScanner1.Scan()
}
when DocumentScanner1.GotScanResult(页数, 图片路径列表, PDF路径) {
  标签1.Text = join("扫描完成，共 ", 页数, " 页")
  if length(图片路径列表) > 0 {
    图像1.Picture = 图片路径列表[1]
  }
}
when DocumentScanner1.ScanCancelled() {
  标签1.Text = "已取消扫描"
}
when DocumentScanner1.ScanFailed(错误信息) {
  标签1.Text = 错误信息
}

属性

允许从相册导入: 是否允许用户在扫描界面里从相册选图片（而不是只能现场拍）。默认允许。
拍摄模式: 拍摄方式：auto 自动检测到纸张就拍（默认），manual 由用户手动按快门。
页数上限: 一次最多扫描多少页。至少 1 页，默认 10 页。
结果格式: 输出格式：jpeg 只出图片、pdf 只出 PDF、both 两种都出（默认）。
扫描模式: 扫描界面的功能档次：base 只有基础的边缘检测和裁剪；filter 增加黑白 / 增强滤镜；full 再增加去阴影去污点、重新拍摄单页等完整能力（默认）。
正在扫描: 扫描界面是否正在进行中。

事件

获得扫描结果(页数,图片路径列表,PDF路径): 扫描完成。pageCount 是页数；imagePaths 是每页 JPG 图片的文件路径列表（输出格式含 jpeg 时才有内容），可以直接给「图像」组件的「图片」属性；pdfPath 是 PDF 文件路径（输出格式含 pdf 时才有内容），可以用「分享」组件发送。
取消扫码时(): 用户取消了扫描（例如按了返回键）。
扫描失败(错误信息): 扫描失败。最常见的原因是设备没有 Google Play 服务，或首次使用时无法联网下载扫描模块。

方法

清空缓存(): 清空本组件生成的所有扫描文件，释放存储空间。返回删除的文件个数。
开始扫描文档(): 打开扫描界面开始扫描。用户扫完点确认会触发「扫描完成」事件，按返回键取消会触发「扫描已取消」事件。

手写识别

手写识别：把用户在画布上写的字识别成文字。支持 300 多种语言 / 20 多种文字系统，也支持识别表情涂鸦和基本几何图形。识别过程完全在设备本地完成。用法极简：在设计器里给「书写画布」属性选一块画布，用户写完直接调「开始识别」即可，语言包没下载会自动下载。注意：语言包首次使用需要联网从 Google 服务器下载（下载后永久离线可用），国内网络可能下载失败。

鸿蒙：暂不支持：鸿蒙系统没有开放手写文字识别接口，调用方法会触发「识别失败时」事件说明原因。

使用指导把画布上手写的字识别成文字查看 →

快速上手

when 按钮_识别.Click() {
  HandwritingRecognizer1.Recognize()
}
when 按钮_清除.Click() {
  HandwritingRecognizer1.Clear()
}
when HandwritingRecognizer1.GotText(文本, 候选JSON) {
  标签1.Text = 文本
}
when HandwritingRecognizer1.RecognizeFailed(错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在识别或下载模型。
书写画布: 用户书写用的画布组件。在设计器里选好即可，之后用户在画布上画线，笔迹会被自动记录下来，画布本身的绘制功能不受影响。
语言代码: 识别语言。可以填标准语言标签，也可以填简称。常用值：zh-Hani 中文（默认，简繁都能认）、zh-Hani-TW 繁体、en-US 英文、ja 日文、ko 韩文、emoji 表情涂鸦、shapes 基本几何图形、autodraw 涂鸦联想。完整语言列表见 ML Kit 数字墨水文档。改了语言需要重新下载对应语言包。
最多结果数: 返回几个候选结果。默认 1 个（最像的那个）。设成 5 之类的值可以在「识别成功」事件的 candidatesJson 里拿到多个候选，做候选字列表。
前文: 上文内容。填上用户已经输入的前一段文字，识别器会据此提升准确率（例如上文是「今天天」，接着写的字更可能被认成「气」）。
笔画数: 当前已经采集到几笔笔迹。可以用它判断用户有没有写东西。

事件

删除模型结果(已删除,错误信息): 「删除模型」的结果。
模型状态(已下载): 「查询模型状态」的结果。
获得文本时(文本,候选JSON): 识别成功。text 是最像的那个结果；candidatesJson 是全部候选结果的 JSON 数组（受「候选数量」属性控制），数组里每一项含 text、score 两个字段，可以用它做候选字列表。
模型下载失败(错误信息): 语言包下载失败。最常见的原因是网络无法访问 Google 服务器。
模型下载完成(): 语言包下载完成（自动下载和手动下载都会触发）。
识别失败时(错误信息): 识别失败。

方法

检查模型(): 查询当前语言的语言包是否已经下载。结果通过「获得模型状态」事件返回。
清除画布(): 清空已采集的笔迹，同时清空画布上的画面，方便重新写。
删除模型(): 删除当前语言的语言包，释放存储空间。结果通过「获得删除结果」事件返回。
下载模型(): 手动下载当前语言的语言包。一般不需要单独调用（「开始识别」会自动下载），但可以用它在应用启动时提前下载好，让第一次识别不用等。
开始识别(): 识别当前笔迹。如果语言包还没下载，会自动先下载再识别（下载期间会先触发「模型下载完成」事件）。识别结果通过「识别成功」事件返回。

人脸检测

离线人脸检测：人脸框、微笑概率、左右眼睁开概率、头部三轴转角，可选关键点与轮廓。模型随 App 打包，设备无需 Google Play 服务。是检测不是识别（不认是谁）。

鸿蒙：部分支持：人脸位置与头部转角可用；鸿蒙系统不提供微笑、睁眼概率和跟踪编号，这几项为 null。实时摄像头检测与 AR 贴图暂不支持，「打开实时摄像头」「保存当前画面」会触发「检测失败时」事件说明原因，添加贴图不起作用。

使用指导检测照片里的人脸、微笑和睁眼查看 →

快速上手

when 图像选择器1.AfterPicking() {
  标签1.Text = "检测中…"
  FaceDetector1.DetectFromFile(图像选择器1.Selection)
}
when FaceDetector1.DetectionSuccess(结果JSON, 人脸数) {
  if 人脸数 > 0 {
    标签1.Text = join("检测到 ", 人脸数, " 张人脸")
    标签_原始结果.Text = 结果JSON
  } else {
    标签1.Text = "没检测到人脸"
  }
}
when FaceDetector1.DetectionFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

精确模式: 是否使用准确模式。假为快速模式，真为准确模式。
正在识别: 是否正在检测。
表情分类: 是否返回微笑、睁眼等分类概率。
轮廓: 是否检测人脸轮廓。
关键点: 是否检测人脸特征点。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
最小人脸比例: 最小人脸尺寸，范围 0 到 1。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面上框出人脸（开启分类时标注微笑概率，开启轮廓时画出轮廓点）。
跟踪: 是否启用人脸跟踪。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

检测失败(操作,错误信息): 人脸检测失败。
检测成功(结果JSON,人脸数): 人脸检测成功。resultJson 为 JSON 文本，faceCount 为人脸数量。
实时检测到人脸(人脸数,图片宽度,图片高度,结果JSON): 实时检测的结果，按「实时事件间隔」限频触发。faceCount 是人脸数（可能为 0）；imageWidth/imageHeight 是摄像头画面尺寸（换算坐标时要用）；resultJson 与「检测成功」事件的格式相同，开启「跟踪」后 trackingId 在连续画面里保持不变。
画面已保存(图片地址): 「保存当前画面」完成。imagePath 是生成的 PNG 文件路径（含贴图），可以直接给「图像」组件的「图片」属性，或用「分享」组件发出去。

方法

添加贴图(名称,图像位址,锚点,宽度比例,横向偏移,纵向偏移): 在实时画面上添加一张贴图（帽子、眼镜、胡子等），跟着人移动、缩放、随头部倾斜旋转。name 是贴图名，同名再添加就是替换；image 是图片素材名（建议用透明背景的 PNG）；anchor 是锚点：FACE_TOP 人脸框上沿中点（戴帽子）、FACE_CENTER 人脸框中心（面具、眼镜）、FACE_BOTTOM 下沿中点（胡子）；开启「特征点」后还可以用 LEFT_EYE、RIGHT_EYE、NOSE_BASE、MOUTH_LEFT、MOUTH_RIGHT、MOUTH_BOTTOM、LEFT_CHEEK、RIGHT_CHEEK、LEFT_EAR、RIGHT_EAR；widthRatio 是贴图宽度相对人脸框宽度的倍数（如 1.2）；offsetX / offsetY 是贴图中心相对锚点的偏移，也按人脸框宽度计（offsetY 为负往上，如 -0.6）。贴图不受「显示标注」影响，做滤镜时可以关掉标注只留贴图。
保存当前画面(): 把实时画面当前这一帧连同贴图存成 PNG 图片，完成后触发「画面已保存」事件。前置摄像头的画面与预览一样是镜像的。只在实时摄像头运行时可用。
清空贴图(): 移除全部贴图。
检测Base64图片(Base64文本): 检测 Base64 图片中的人脸。支持纯 Base64 或 data:image/…;base64, 前缀。
检测图片文件(路径): 检测图片文件中的人脸。参数可以是资源文件、file://、content:// 或本地路径。
移除贴图(名称): 移除一张贴图（按添加时的名称）。
打开实时摄像头(): 打开摄像头实时检测人脸，画面显示在「预览容器」里，并在画面上框出每张脸。结果按「实时事件间隔」触发「实时检测到人脸」事件。自拍类应用记得把「使用前置摄像头」设为真。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

姿势检测

人体姿势检测（ML Kit，离线）。识别 33 个人体关键点及其坐标与置信度，可用于体感游戏、健身计数、动作打分。模型随 App 打包，无需 Google Play 服务。

鸿蒙：部分支持：鸿蒙系统给出 17 个关键点（鼻子、眼、耳、肩、肘、腕、髋、膝、踝），编号与名称沿用这里的 33 点体系，眼角、嘴角、手指、脚跟等点不出现在结果里；「精确模式」不切换模型。实时摄像头检测与 AR 贴图暂不支持，「打开实时摄像头」「保存当前画面」会触发「检测失败时」事件说明原因，添加贴图不起作用。

使用指导识别人体关键点坐标，判断举手查看 →

快速上手

when 图像选择器1.AfterPicking() {
  标签1.Text = "检测中…"
  PoseDetector1.DetectFromFile(图像选择器1.Selection)
}
when PoseDetector1.DetectionSuccess(结果JSON, 关键点数) {
  if 关键点数 > 0 {
    标签1.Text = join("检测到 ", 关键点数, " 个关键点")
    标签_原始结果.Text = 结果JSON
  } else {
    标签1.Text = "没检测到人体"
  }
}
when PoseDetector1.DetectionFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

精确模式: 是否使用精确模型。精确模型关键点更准，但更慢、安装包也更大；默认关闭（基础模型，适合实时检测）。实时检测进行中修改，下一帧起生效。
正在识别: 是否正在检测中。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面上画出人体骨架（关键点与连线）。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

检测失败(操作,错误信息): 姿势检测失败。
检测成功(结果JSON,关键点数): 姿势检测成功。resultJson 为 JSON 文本（landmarks 数组），landmarkCount 为识别到的关键点数量（未识别到人体时为 0）。
画面已保存(图片地址): 「保存当前画面」完成。imagePath 是生成的 PNG 文件路径（含贴图），可以直接给「图像」组件的「图片」属性，或用「分享」组件发出去。
实时检测到姿势(关键点数,图片宽度,图片高度,结果JSON): 实时检测的结果，按「实时事件间隔」限频触发。landmarkCount 是关键点数（画面里没有人时为 0）；imageWidth/imageHeight 是摄像头画面尺寸（换算坐标时要用）；resultJson 与「检测成功」事件的格式相同。

方法

添加贴图(名称,图像位址,锚点,宽度比例,横向偏移,纵向偏移): 在实时画面上添加一张贴图（帽子、眼镜、胡子等），跟着人移动、缩放、随头部倾斜旋转。name 是贴图名，同名再添加就是替换；image 是图片素材名（建议用透明背景的 PNG）；anchor 是锚点：关键点名称，如 NOSE 鼻子（戴帽子用它往上偏移）、LEFT_EYE / RIGHT_EYE 眼睛、LEFT_WRIST / RIGHT_WRIST 手腕、LEFT_SHOULDER 肩膀，完整名称见使用指导；widthRatio 是贴图宽度相对参考宽度（头部的点是两耳距离，身体的点是肩宽）的倍数（如 1.2）；offsetX / offsetY 是贴图中心相对锚点的偏移，也按参考宽度（头部的点是两耳距离，身体的点是肩宽）计（offsetY 为负往上，如 -0.6）。贴图不受「显示标注」影响，做滤镜时可以关掉标注只留贴图。
保存当前画面(): 把实时画面当前这一帧连同贴图存成 PNG 图片，完成后触发「画面已保存」事件。前置摄像头的画面与预览一样是镜像的。只在实时摄像头运行时可用。
清空贴图(): 移除全部贴图。
检测Base64图片(Base64文本): 检测 Base64 图片中的人体姿势。支持纯 Base64 或 data:image/…;base64, 前缀。
检测图片文件(路径): 检测图片文件中的人体姿势。路径可以是素材名、file://、content:// 或本地路径。成功后触发 DetectionSuccess 事件。
移除贴图(名称): 移除一张贴图（按添加时的名称）。
打开实时摄像头(): 打开摄像头实时检测人体姿势，画面显示在「预览容器」里，并在画面上画出骨架。结果按「实时事件间隔」触发「实时检测到姿势」事件，适合健身计数、体感游戏。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

语言识别

语言识别：判断一段文本是哪种语言，支持 100 多种语言。模型随 App 打包，完全离线，设备无需 Google Play 服务，断网也能用。常用于「自动选择翻译目标语言」「按语言分流客服消息」这类场景。

鸿蒙：暂不支持：调用方法会触发「识别语言失败」事件说明原因。

使用指导判断文字是哪种语言，给出中文名查看 →

快速上手

when 按钮_检测.Click() {
  LanguageIdentifier1.IdentifyLanguage(文本输入框_输入.Text)
}
when LanguageIdentifier1.GotLanguage(语言代码, 名称) {
  标签1.Text = join("这是", 名称, "（", 语言代码, "）")
}
when LanguageIdentifier1.NoLanguageFound(文本) {
  标签1.Text = "认不出来，请多输入一些文字"
}
when LanguageIdentifier1.IdentifyFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在识别。
置信度阈值: 置信度阈值，0～1。低于这个值就认为「识别不出来」。默认 0.5；文本很短时可以调低（如 0.2）以提高命中率，但准确率会下降。改了这个属性会重建识别器，立即生效。

事件

识别出语言(语言代码,名称): 识别出语言。languageTag 是 BCP-47 标签（如 zh、en、ja），name 是对应的中文名称（认不出的标签会原样给出 languageTag）。
获得可能的语言(数量,结果JSON): 获得多个候选语言。count 是候选个数；resultJson 是 JSON 数组，每一项含 languageTag、name、confidence 三个字段，按置信度从高到低排列。
识别语言失败(操作,错误信息): 识别失败。operation 是出错的方法名。
未识别出语言(文本): 没能识别出语言（文本太短、或多种语言混杂、或置信度低于阈值）。这不是错误 —— 可以提示用户多输入一些文字，或调低「置信度阈值」属性。

方法

识别语言(文本): 识别文本是哪种语言，只返回最可能的一种。识别成功触发「获得语言」事件；文本太短或语言混杂认不出时触发「未识别出语言」事件。
识别可能的语言(文本): 识别文本可能是哪些语言，返回多个候选及其置信度。结果通过「获得候选语言」事件返回。适合做「这段话可能是 A 也可能是 B」的展示。
语言名称(语言代码): 把语言标签（如 zh、en、ja）转成中文名称。认不出的标签原样返回，方便直接显示。

人像分割

人像分割：把照片里的人和背景分开。可以抠出人像（背景透明）、换纯色背景、换图片背景、背景虚化。模型随 App 打包，完全离线，设备无需 Google Play 服务，断网也能用。结果直接存成 PNG 并返回文件路径，可以直接给「图像」组件显示、「分享」组件发送。

鸿蒙：完整支持图片处理：调用系统主体分割，人、宠物、物品都会被当作主体，拍人像时效果一致。实时换背景暂不支持，「打开实时摄像头」「保存当前画面」会触发「处理失败」事件说明原因。

使用指导抠人像、换背景、背景虚化查看 →

快速上手

when 图像选择器1.AfterPicking() {
  标签1.Text = "处理中…"
  PortraitSegmenter1.ReplaceBackgroundWithColor(图像选择器1.Selection, -16776961)
}
when PortraitSegmenter1.GotResult(图片地址, 宽度, 高度) {
  图像1.Picture = 图片地址
  标签1.Text = join("完成 ", 宽度, "×", 高度)
}
when PortraitSegmenter1.SegmentFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在处理。
实时背景颜色: 「实时背景效果」为 color 时的背景颜色，默认证件照蓝。
实时背景图片: 「实时背景效果」为 image 时的背景图片，会缩放到与摄像头画面一样大。
实时虚化半径: 「实时背景效果」为 blur 时的虚化强度，1～40，默认 15。
实时摄像头运行中: 实时摄像头是否正在运行。
实时背景效果: 实时换背景的效果：blur（虚化，默认）、color（换成「实时背景颜色」）、image（换成「实时背景图片」）。实时进行中修改，下一帧起生效。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
起始字数: 前景判定阈值，0～1。模型给每个像素一个「属于人像」的置信度，高于这个值就算人像。默认 0.5；调高会更保守（边缘可能被切掉），调低会更宽松（可能带上背景）。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

获得结果时(图片地址,宽度,高度): 处理完成。imagePath 是生成的 PNG 文件路径，可以直接给「图像」组件的「图片」属性，或用「分享」组件发送。
分割失败(操作,错误信息): 处理失败。operation 是出错的方法名。

方法

背景虚化(图像位址,半径): 把背景虚化（人像保持清晰），输出 PNG。radius 是虚化强度，建议 8～25；太大很慢。
保存当前画面(): 把实时换背景当前看到的画面存成 PNG 图片，完成后触发「处理完成」事件。前置摄像头的画面与预览一样是镜像的。
清空缓存(): 清空本组件生成的所有图片，返回删除的文件个数。
抠出人像(图像位址): 抠出人像，背景变透明，输出 PNG。image 可以是素材文件名、本地路径、file:// 或 content:// 地址。
换纯色背景(图像位址,颜色): 把背景换成纯色，输出 PNG。color 用颜色块或 &HAARRGGBB 格式的数字。
换图片背景(图像位址,背景图片): 把背景换成另一张图片，输出 PNG。背景图会被缩放到与原图一样大。
打开实时摄像头(): 打开摄像头实时换背景：画面显示在「预览容器」里，人像保持不动，背景按「实时背景效果」虚化、换成纯色或换成图片。调用「保存当前画面」可以把看到的画面存成图片。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

图像标注

图像标注：识别一张图片里有什么，返回 400 多种通用类别及置信度（如花、食物、天空、建筑、猫、狗……）。常用于「拍照识物」类应用。模型随 App 打包，完全离线，设备无需 Google Play 服务，断网也能用。标签同时给出英文原名和中文名。

鸿蒙：暂不支持：鸿蒙系统没有开放通用图像分类接口，图片识别与实时摄像头都会触发「标注失败」事件。

使用指导拍照识物，给出带中文名的标签查看 →

快速上手

when 图像选择器1.AfterPicking() {
  标签1.Text = "识别中…"
  ImageLabeler1.LabelFromFile(图像选择器1.Selection)
}
when ImageLabeler1.GotLabels(最佳标签, 最佳中文名, 标签列表, 中文名列表, 结果JSON) {
  标签1.Text = join("这是：", 最佳中文名)
  列表显示框1.Elements = 中文名列表
}
when ImageLabeler1.NoLabelFound(操作) {
  标签1.Text = "没认出来，试试换张图或调低置信度阈值"
}
when ImageLabeler1.LabelFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在识别。
置信度阈值: 置信度阈值，0～1。低于这个值的标签不返回。默认 0.5。调低会返回更多但更不确定的标签。改了会重建识别器，立即生效。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面左上角显示最可能的标签和置信度。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

获得标签(最佳标签,最佳中文名,标签列表,中文名列表,结果JSON): 识别出标签。topLabel/topName 是置信度最高的那个（英文/中文），labels/names 是全部标签列表（按置信度从高到低），resultJson 是 JSON 数组，每一项含 label、name、confidence、index 四个字段。
标注失败(操作,错误信息): 识别失败。operation 是出错的方法名。
实时获得标签(最佳标签,最佳中文名,标签列表,中文名列表,结果JSON): 实时识别的结果，按「实时事件间隔」限频触发，参数与「获得标签」相同；画面里没有能认出的东西时 topLabel 为空、列表为空。
未识别出标签(操作): 没识别出任何标签（图片内容不在 400 类里，或都低于置信度阈值）。这不是错误 —— 可以试着调低「置信度阈值」属性。

方法

标注Base64图片(Base64文本): 识别 Base64 图片里有什么。支持纯 Base64，也支持带 data:image/…;base64, 前缀的写法。
标注图片文件(路径): 识别图片文件里有什么。参数可以是素材文件名、本地路径、file:// 或 content:// 地址。
标签中文名(英文标签): 把英文标签转成中文名。认不出的原样返回。
打开实时摄像头(): 打开摄像头实时识别画面里的东西，画面显示在「预览容器」里，左上角显示最可能的标签。结果按「实时事件间隔」触发「实时获得标签」事件。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

目标检测（暂未开放）

暂未开放：模型文件在打包环节存在兼容问题，修复前该组件已从组件面板隐藏，文档保留供了解。

目标检测：找出图片里有哪些物体，并给出每个物体的位置（矩形框）。可选择只找最显眼的一个还是找出多个，可选择是否同时给出粗分类（时尚商品/食物/家居/居家好物/植物等 5 大类）。模型随 App 打包，完全离线，设备无需 Google Play 服务，断网也能用。

鸿蒙：完整支持图片检测：调用系统目标检测；类别名为鸿蒙系统的类别（Animal、Plant、Food、Car、Person 等）。实时摄像头检测暂不支持，「打开实时摄像头」会触发「检测失败时」事件说明原因。

使用指导找出物体位置并在图上画框查看 →

快速上手

global scale = 1

when 图像选择器1.AfterPicking() {
  标签1.Text = "检测中…"
  ObjectDetector1.DetectFromFile(图像选择器1.Selection)
}
when ObjectDetector1.GotObjects(数量, 图片宽度, 图片高度, 结果JSON) {
  标签1.Text = join("找到 ", 数量, " 个物体")
  画布1.BackgroundImage = 图像选择器1.Selection
  scale = 画布1.Width / 图片宽度
}
when ObjectDetector1.GotObject(索引, x坐标, y坐标, 宽度, 高度, 标签文字, 置信度, 跟踪编号) {
  画布1.PaintColor = -65536
  画布1.DrawLine(x坐标 * scale, y坐标 * scale, (x坐标 + 宽度) * scale, y坐标 * scale)
  画布1.DrawLine((x坐标 + 宽度) * scale, y坐标 * scale, (x坐标 + 宽度) * scale, (y坐标 + 高度) * scale)
  画布1.DrawLine((x坐标 + 宽度) * scale, (y坐标 + 高度) * scale, x坐标 * scale, (y坐标 + 高度) * scale)
  画布1.DrawLine(x坐标 * scale, (y坐标 + 高度) * scale, x坐标 * scale, y坐标 * scale)
  画布1.DrawText(标签文字, x坐标 * scale, y坐标 * scale)
}

属性

正在识别: 是否正在检测。
分类: 是否同时给出粗分类。真（默认）= 每个物体附带类别名和置信度；假 = 只给位置框（更快）。注意基础模型只有 5 个大类，要精细分类请用「自定义目标检测」组件。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
多个物体: 是否检测多个物体。真（默认）= 找出画面里最多 5 个物体；假 = 只找最显眼的那一个（更快）。改了会重建检测器，立即生效。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面上框出检测到的物体（带类别和置信度）。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

检测失败时(操作,错误信息): 检测失败。operation 是出错的方法名。
获得物体(索引,x坐标,y坐标,宽度,高度,标签文字,置信度,跟踪编号): 每检测到一个物体触发一次，方便逐个画框。index 从 1 开始；x/y 是框的左上角，width/height 是框的宽高（单位：原图像素）；label/confidence 是粗分类结果（「是否分类」为假时 label 为空）；trackingId 是跨帧跟踪编号，单张图片检测时为 -1。
获得物体列表(数量,图片宽度,图片高度,结果JSON): 检测完成的汇总。count 是物体个数；imageWidth/imageHeight 是原图尺寸（画框换算坐标时要用）；resultJson 含每个物体的边界框、跟踪 id 和分类标签。
实时检测到物体(数量,图片宽度,图片高度,结果JSON): 实时检测的结果，按「实时事件间隔」限频触发。count 是物体个数（可能为 0）；imageWidth/imageHeight 是摄像头画面尺寸（换算坐标时要用）；resultJson 与「获得物体列表」事件的格式相同，trackingId 是跨帧跟踪编号，同一个物体在连续画面里保持不变。
未找到物体(操作): 图里没检测到物体。这不是错误 —— 目标检测适合画面里有明确主体的照片，纯风景/纯文字图常常检测不到。

方法

检测Base64图片(Base64文本): 检测 Base64 图片里的物体。支持纯 Base64，也支持带 data:image/…;base64, 前缀的写法。
检测图片文件(路径): 检测图片文件里的物体。参数可以是素材文件名、本地路径、file:// 或 content:// 地址。
打开实时摄像头(): 打开摄像头实时检测物体，画面显示在「预览容器」里，并在画面上框出每个物体。结果按「实时事件间隔」触发「实时检测到物体」事件，同一个物体在连续画面里有不变的跟踪编号。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

离线翻译

离线翻译：支持 50 多种语言互译，翻译过程完全在设备本地完成，不上传文本。用法极简：设好源语言和目标语言，直接调「翻译」即可，语言包没下载会自动下载。注意：语言包首次使用需要联网从 Google 服务器下载（每种语言约 30MB，下载后永久离线可用），国内网络可能下载失败。

鸿蒙：暂不支持：鸿蒙系统没有开放端侧翻译接口，调用方法会触发「翻译失败」事件。

使用指导50 多种语言本地互译，文本不上传查看 →

快速上手

when 按钮_翻译.Click() {
  标签1.Text = "翻译中…"
  OfflineTranslator1.Translate(文本输入框_输入.Text)
}
when OfflineTranslator1.GotTranslation(原文, 译文) {
  标签1.Text = 译文
}
when OfflineTranslator1.ModelDownloadFailed(错误信息) {
  标签1.Text = 错误信息
}
when OfflineTranslator1.TranslateFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在翻译或下载语言包。
仅WiFi下载: 是否只在 WiFi 下下载语言包。真 = 省流量，但用户在移动网络下会一直下载不了（要提示他连 WiFi）；假（默认）= 任何网络都下。
源语言: 源语言标签。常用：zh 中文、en 英文、ja 日文、ko 韩文、fr 法文、de 德文、es 西班牙文、ru 俄文、th 泰文、vi 越南文。完整列表用「支持的语言」块查看。
目标语言: 目标语言标签，取值同「源语言」。

事件

删除模型结果(语言代码,已删除,错误信息): 「删除模型」的结果。
获得已下载模型(数量,语言代码列表): 「列出已下载语言包」的结果。languageTags 是语言标签列表。
模型状态(语言代码,已下载): 「查询模型状态」的结果。
获得译文时(原文,译文): 翻译完成。originalText 是原文，translatedText 是译文。源语言与目标语言相同时会原样返回（不消耗下载）。
模型下载失败(错误信息): 语言包下载失败。最常见的原因是网络无法访问 Google 服务器。
模型下载完成(): 语言包下载完成（自动下载和手动下载都会触发）。
翻译失败(操作,错误信息): 翻译失败。operation 是出错的方法名。

方法

检查模型(语言代码): 查询某个语言的语言包是否已下载。languageTag 留空则查「目标语言」。结果通过「获得模型状态」事件返回。
删除模型(语言代码): 删除某个语言的语言包，释放存储空间（每个约 30MB）。languageTag 留空则删「目标语言」。
下载模型(): 手动下载当前语言对的语言包。一般不用单独调（「翻译」会自动下载），但可以在应用启动时提前下好，让第一次翻译不用等。
列出已下载模型(): 列出已经下载到本机的语言包。结果通过「获得已下载语言」事件返回。
支持的语言(): 返回全部支持的语言标签列表，可用于做语言选择下拉框。
翻译(文本): 翻译文本。语言包没下载会自动先下载再翻译（下载成功会先触发「语言包下载完成」事件）。结果通过「翻译完成」事件返回。

面部网格

面部网格：检测 468 个面部关键点（带 x/y/z 坐标），用于 AR 贴纸定位、美颜、面部特效、眨眼张嘴检测。可识别图片，也可打开摄像头实时检测；可按名字取关键点（额头、鼻尖、下巴、眼睛、嘴唇等），也可按区域取点（脸廓、左右眼、眉毛、嘴唇、鼻梁）。模型随 App 打包，完全离线，设备无需 Google Play 服务，断网也能用。注意：这是 ML Kit 的 beta 功能，且要求人脸离镜头较近（约 2 米内）。

鸿蒙：暂不支持：鸿蒙系统没有开放 468 点面部网格接口，图片检测、实时摄像头与保存画面都会触发「检测失败时」事件说明原因，添加贴图不起作用。

使用指导检测 468 个面部关键点，按区域取点查看 →

快速上手

when 图像选择器1.AfterPicking() {
  标签1.Text = "检测中…"
  FaceMesh1.DetectFromFile(图像选择器1.Selection)
}
when FaceMesh1.GotFaceMesh(人脸数, 关键点数量, 人脸框JSON) {
  标签1.Text = join("检测到 ", 人脸数, " 张脸，", 关键点数量, " 个点")
  标签_眼睛.Text = FaceMesh1.RegionPoints("LEFT_EYE", 1)
}
when FaceMesh1.NoFaceFound(操作) {
  标签1.Text = "没检测到人脸，请让脸离镜头近一些、正对镜头"
}
when FaceMesh1.DetectFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

可用区域: 可用的区域名，用英文逗号分隔。可以直接显示给用户做选择。
正在识别: 是否正在检测。
关键点名称: 可用的关键点名，用英文逗号分隔，供「关键点」「关键点距离」使用。左右指被拍人自己的左右。常用：FOREHEAD 额头、CHIN 下巴、NOSE_TIP 鼻尖、LEFT_CHEEK / RIGHT_CHEEK 脸颊、LEFT_EYE_TOP / LEFT_EYE_BOTTOM 左眼上下沿、MOUTH_TOP / MOUTH_BOTTOM 嘴唇外沿、UPPER_LIP_INNER / LOWER_LIP_INNER 内唇（判断张嘴）。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面上画出网格点和五官轮廓。
用途: 检测模式。mesh（默认）= 输出 468 个网格点；boundingbox = 只输出人脸边界框（快得多，不给点）。填了认不出的值会回退到 mesh。改这个属性会重建检测器，立即生效。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

检测失败时(操作,错误信息): 检测失败。operation 是出错的方法名。
获得面部网格(人脸数,关键点数量,人脸框JSON): 检测完成。faceCount 是人脸数；pointCount 是第一张脸的点数（mesh 模式下是 468，boundingbox 模式下是 0）；boundsJson 是第一张脸的边界框。要拿点请在这个事件里调「区域点」或「全部点」方法 —— 结果已缓存，可反复取不同区域。
实时检测到面部网格(人脸数,图片宽度,图片高度): 实时检测的结果，按「实时事件间隔」限频触发。faceCount 是人脸数（可能为 0）；imageWidth/imageHeight 是摄像头画面尺寸（换算坐标时要用）。在这个事件里调「关键点」「关键点距离」「区域关键点」等方法，取到的就是这一帧的数据。坐标是摄像头原始画面的像素，前置摄像头的预览是镜像的，要和预览左右一致时用 imageWidth 减去 x。
画面已保存(图片地址): 「保存当前画面」完成。imagePath 是生成的 PNG 文件路径（含贴图），可以直接给「图像」组件的「图片」属性，或用「分享」组件发出去。
未找到人脸(操作): 图里没检测到人脸。这不是错误 —— 面部网格要求人脸离镜头较近（约 2 米内）且基本正面，远景/大角度侧脸检测不到。

方法

添加贴图(名称,图像位址,锚点,宽度比例,横向偏移,纵向偏移): 在实时画面上添加一张贴图（帽子、眼镜、胡子等），跟着人移动、缩放、随头部倾斜旋转。name 是贴图名，同名再添加就是替换；image 是图片素材名（建议用透明背景的 PNG）；anchor 是锚点：关键点名称（见「关键点名称」属性），如 FOREHEAD 额头、NOSE_TIP 鼻尖、CHIN 下巴、MOUTH_TOP 嘴上沿；widthRatio 是贴图宽度相对脸宽（两颊距离）的倍数（如 1.2）；offsetX / offsetY 是贴图中心相对锚点的偏移，也按脸宽（两颊距离）计（offsetY 为负往上，如 -0.6）。贴图不受「显示标注」影响，做滤镜时可以关掉标注只留贴图。
全部关键点JSON(人脸序号): 取上一次检测结果的全部 468 个点，返回 JSON 数组。⚠️ 数据量大（几十 KB），只在确实需要全部点时用；一般用「区域点」就够了。faceIndex 从 1 开始。
人脸框JSON(人脸序号): 取上一次检测结果里某张脸的边界框，返回一个 JSON 对象，含 left、top、right、bottom、width、height 六个字段。faceIndex 从 1 开始。没有结果时返回一个空的 JSON 对象。
保存当前画面(): 把实时画面当前这一帧连同贴图存成 PNG 图片，完成后触发「画面已保存」事件。前置摄像头的画面与预览一样是镜像的。只在实时摄像头运行时可用。
清空贴图(): 移除全部贴图。
检测Base64图片(Base64文本): 检测 Base64 图片里的面部网格。支持纯 Base64，也支持带 data:image/…;base64, 前缀的写法。
检测图片文件(路径): 检测图片文件里的面部网格。参数可以是素材文件名、设备路径、file:// 或 content:// 地址。
关键点(名称,人脸序号): 取上一次检测结果里某张脸的一个关键点，返回列表 [x, y, z]（单位：图片像素，z 为相对深度，越小越靠近镜头）。名字见「关键点名称」属性，如 FOREHEAD、NOSE_TIP、CHIN。faceIndex 从 1 开始。实时检测时在「实时检测到面部网格」事件里调用，取的就是那一帧。没有结果、名字不对或只检测边界框时返回空列表。
关键点距离(名称1,名称2,人脸序号): 取上一次检测结果里两个关键点在图片上的距离（像素，只算 x、y）。常见用法：LEFT_CHEEK 到 RIGHT_CHEEK 是脸宽；UPPER_LIP_INNER 到 LOWER_LIP_INNER 除以脸宽判断张嘴；LEFT_EYE_TOP 到 LEFT_EYE_BOTTOM 除以脸宽判断眨眼。任一个点取不到时返回 -1。
区域关键点(区域名,人脸序号): 取上一次检测结果里某个区域的点，返回 JSON 数组。regionName 用「可用区域」属性里的名字（如 LEFT_EYE、UPPER_LIP_TOP）。faceIndex 从 1 开始。没有结果或名字不对时返回空数组 []。
移除贴图(名称): 移除一张贴图（按添加时的名称）。
打开实时摄像头(): 打开摄像头实时检测面部网格，画面显示在「预览容器」里，并在画面上画出网格点和五官轮廓。结果按「实时事件间隔」触发「实时检测到面部网格」事件，在事件里用「关键点」「关键点距离」取这一帧的数据，可以做眨眼、张嘴检测或跟随头部的小游戏。自拍类应用记得把「使用前置摄像头」设为真。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

智能回复

智能回复：根据对话上下文生成 1～3 条候选回复（像输入法上方的快捷回复）。⚠️ 只支持英语对话 —— ML Kit 的模型只训练了英语，中文对话会触发「语言不支持」事件。模型随 App 打包，完全离线，设备无需 Google Play 服务。用法：用「添加对方消息」/「添加本人消息」按顺序喂入对话，再调「生成回复建议」。

鸿蒙：暂不支持：调用方法会触发「生成建议失败」事件说明原因。

使用指导根据英文对话生成 1～3 条快捷回复查看 →

快速上手

when 按钮_收到消息.Click() {
  SmartReply1.AddRemoteMessage("Are you free this weekend?", "friend")
  SmartReply1.SuggestReplies()
}
when SmartReply1.GotSuggestions(数量, 候选词) {
  列表显示框_建议.Elements = 候选词
  标签1.Text = join("有 ", 数量, " 条建议")
}
when SmartReply1.LanguageNotSupported() {
  标签1.Text = "智能回复只支持英语对话"
}
when SmartReply1.NoReplyAvailable() {
  标签1.Text = "这句话没有合适的快捷回复"
}
when SmartReply1.SuggestFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在生成建议。
消息数: 当前对话历史里有多少条消息。

事件

获得回复建议(数量,候选词): 获得回复建议（1～3 条）。suggestions 是候选回复文本的列表，可以直接给列表显示框，或做成几个按钮让用户一键发送。
语言不支持(): ⚠️ 对话语言不支持 —— ML Kit 的智能回复只支持英语。中文对话会走到这里。这不是错误，是能力边界。
没有合适回复(): 模型认为没有合适的回复可建议（例如最后一条是本人发的、或内容不适合快捷回复）。这不是错误。
生成建议失败(操作,错误信息): 生成失败。operation 是出错的方法名。

方法

添加本人消息(文本): 添加一条本人发出的消息。按对话发生的先后顺序调用。
添加对方消息(文本,用户编号): 添加一条对方发来的消息。userId 用来区分不同的对话人（群聊时有用），单人对话随便填一个固定值即可，如 “friend”。按对话发生的先后顺序调用。
清空对话(): 清空对话历史。开始一段新对话时调用。
生成回复建议(): 根据当前对话历史生成回复建议。结果通过「获得回复建议」事件返回（1～3 条）。注意：对话的最后一条必须是对方发的，否则没有可回复的内容。

实体抽取

实体抽取：从一段文本里自动找出地址、日期时间、电话、邮箱、网址、金额、快递单号、航班号、ISBN、IBAN、银行卡号等信息，并给出各自在原文中的位置。抽取过程在设备本地完成，不上传文本。注意：语言模型首次使用需要联网从 Google 服务器下载（下载后永久离线可用），国内网络可能下载失败。这是 ML Kit 的 beta 功能。

鸿蒙：完整支持：调用系统自然语言能力，模型由系统提供，「下载模型」直接触发「模型下载完成」；类型编号相同，另有人名 101、验证码 102、身份证号 103 三种鸿蒙独有类型。

使用指导从文字里抽取电话、地址、日期、快递单号查看 →

快速上手

when 按钮_抽取.Click() {
  标签1.Text = "抽取中…"
  EntityExtractor1.Extract(文本输入框_输入.Text)
}
when EntityExtractor1.GotEntities(数量, 结果JSON) {
  标签1.Text = join("找到 ", 数量, " 项")
  标签_原始结果.Text = 结果JSON
}
when EntityExtractor1.NoEntityFound(文本) {
  标签1.Text = "这段文字里没有可识别的信息"
}
when EntityExtractor1.ModelDownloadFailed(错误信息) {
  标签1.Text = 错误信息
}
when EntityExtractor1.ExtractFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在抽取或下载模型。
语言: 文本语言，决定用哪个模型。默认 chinese。可选值：chinese、english、japanese、korean、french、german、spanish、italian、portuguese、dutch、polish、russian、arabic、thai、turkish。填了不支持的值会在抽取时报错并给出可用列表。改这个属性会重建抽取器。
支持的语言: 支持的语言，用英文逗号分隔，可直接显示给用户做选择。

事件

抽取失败(操作,错误信息): 抽取失败。operation 是出错的方法名。
获得实体(数量,结果JSON): 抽取出实体。count 是实体个数；resultJson 是 JSON 数组，每一项含 text、start、end 三个字段，外加一个 entities 子数组（子项含 type、name 两个字段）。start/end 是在原文里的字符位置，可以用来做高亮。一段文字可能同时匹配多个类型，所以 entities 是数组。
模型下载失败(错误信息): 模型下载失败。最常见的原因是网络无法访问 Google 服务器。
模型下载完成(): 模型下载完成（自动下载和手动下载都会触发）。
未找到实体(文本): 文本里没找到任何实体。这不是错误。

方法

下载模型(): 手动下载当前语言的模型。一般不用单独调（「抽取」会自动下载），可用于启动时提前下好。
抽取实体(文本): 从文本里抽取实体。模型没下载会自动先下载再抽取（下载成功会先触发「模型下载完成」事件）。结果通过「获得实体」事件返回。
类型名称(类别): 把实体类型编号转成可读名称（如 8 → PHONE）。一般用不到 —— 事件返回的 JSON 里已经带了名称。

自定义图像分类（暂未开放）

暂未开放：模型文件在打包环节存在兼容问题，修复前该组件已从组件面板隐藏；只是想让 App 认出几类自己的东西，可用即教即识在手机上直接拍样本教。

自定义模型图像分类：用你自己训练的 TFLite 模型识别图片，可以认具体品类（花的品种、菜名、零件型号……），突破基础模型只有 400 个通用类别的限制。模型文件填素材文件名（如 flowers.tflite）或设备绝对路径都行。完全离线，设备无需 Google Play 服务。模型要求：TFLite 图像分类模型，建议带元数据（含标签），可用 Google Teachable Machine 或 AutoML Vision Edge 训练导出。

国内用户注意：Teachable Machine 网站（teachablemachine.withgoogle.com）国内需要访问国外网络才能打开。只是想让 App 认出几类自己的东西，用即教即识在手机上直接拍样本教，不需要电脑和外网。几种方案的区别看图像分类方案对比。

鸿蒙：暂不支持：鸿蒙需要 MindSpore 格式的模型，暂不支持 TFLite 模型（含 Teachable Machine 导出的模型），调用方法会触发「标注失败」事件。

使用指导用自己的 TFLite 模型做图像分类查看 →

快速上手

when Screen1.Initialize() {
  CustomImageLabeler1.ModelFile = "flowers.tflite"
  CustomImageLabeler1.ConfidenceThreshold = 0.6
  CustomImageLabeler1.MaxResultCount = 3
}
when 图像选择器1.AfterPicking() {
  标签1.Text = "识别中…"
  CustomImageLabeler1.LabelFromFile(图像选择器1.Selection)
}
when CustomImageLabeler1.GotLabels(最佳标签, 最佳置信度, 标签列表, 结果JSON) {
  标签1.Text = join(最佳标签, "（", round(最佳置信度 * 100), "%）")
  列表显示框1.Elements = 标签列表
}
when CustomImageLabeler1.NoLabelFound(操作) {
  标签1.Text = "没有结果超过置信度阈值，试试调低阈值"
}
when CustomImageLabeler1.LabelFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在识别。
置信度阈值: 置信度阈值，0～1，默认 0.5。低于这个值的结果不返回。
标签文件: 标签文件（可选），每行一个类别名，第 1 行对应模型输出第 0 类。Teachable Machine 导出的 labels.txt 直接用（行首的「0 」「1 」序号会自动去掉）。设了就用文件里的名字，不设就用模型元数据里的标签 —— Teachable Machine 的模型不带元数据，必须设。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
最多结果数: 最多返回几个结果，默认 5。至少 1。
模型文件: TFLite 模型文件。填素材文件名（如 flowers.tflite，先把文件上传到项目素材）或设备绝对路径（含 / 即视为路径）。改这个属性会重建识别器，立即生效。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面左上角显示最可能的类别和置信度。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

获得标签(最佳标签,最佳置信度,标签列表,结果JSON): 识别出结果。topLabel/topConfidence 是最可能的那个；labels 是全部结果的标签列表（按置信度从高到低）；resultJson 是 JSON 数组，每一项含 label、confidence、index 三个字段。标签文字来自「标签文件」，没设时用模型自带的元数据，所以中文模型直接就是中文。
标注失败(操作,错误信息): 识别失败。常见原因：「模型文件」没设或文件不存在、模型不是 TFLite 图像分类模型；模型没有标签元数据又没设「标签文件」时类别名为空。
实时获得标签(最佳标签,最佳置信度,标签列表,结果JSON): 实时识别的结果，按「实时事件间隔」限频触发，参数与「获得标签」相同；没有结果超过置信度阈值时 topLabel 为空、topConfidence 为 0、列表为空。
未识别出标签(操作): 没有结果超过置信度阈值。这不是错误 —— 可以调低阈值试试。

方法

标注Base64图片(Base64文本): 用自定义模型识别 Base64 图片。支持带 data:image/…;base64, 前缀的写法。
标注图片文件(路径): 用自定义模型识别图片文件。参数可以是素材文件名、设备路径、file:// 或 content:// 地址。
打开实时摄像头(): 打开摄像头用自定义模型实时识别，画面显示在「预览容器」里，左上角显示最可能的类别。结果按「实时事件间隔」触发「实时获得标签」事件。Teachable Machine 训练的模型这样用最直观。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

自定义目标检测（暂未开放）

暂未开放：模型文件在打包环节存在兼容问题，修复前该组件已从组件面板隐藏，文档保留供了解。

自定义模型目标检测：用你自己训练的 TFLite 模型找出图片里的物体、给出位置矩形框并做精细分类，突破基础模型只有 5 个大类的限制。模型文件填素材文件名（如 parts.tflite）或设备绝对路径都行。完全离线，设备无需 Google Play 服务。模型要求：TFLite 目标检测模型，建议带元数据（含标签），可用 AutoML Vision Edge 训练导出。

鸿蒙：暂不支持：鸿蒙需要 MindSpore 格式的模型，暂不支持 TFLite 模型，调用方法会触发「检测失败时」事件。

使用指导用自己的 TFLite 模型检测物体并细分类查看 →

快速上手

global scale = 1

when Screen1.Initialize() {
  CustomObjectDetector1.ModelFile = "parts.tflite"
}
when 图像选择器1.AfterPicking() {
  CustomObjectDetector1.DetectFromFile(图像选择器1.Selection)
}
when CustomObjectDetector1.GotObjects(数量, 图片宽度, 图片高度, 结果JSON) {
  标签1.Text = join("找到 ", 数量, " 个")
  画布1.BackgroundImage = 图像选择器1.Selection
  scale = 画布1.Width / 图片宽度
}
when CustomObjectDetector1.GotObject(索引, x坐标, y坐标, 宽度, 高度, 标签文字, 置信度, 跟踪编号) {
  画布1.PaintColor = -65536
  画布1.DrawLine(x坐标 * scale, y坐标 * scale, (x坐标 + 宽度) * scale, y坐标 * scale)
  画布1.DrawText(标签文字, x坐标 * scale, y坐标 * scale)
}
when CustomObjectDetector1.DetectFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

属性

正在识别: 是否正在检测。
分类: 是否同时给出粗分类。真（默认）= 每个物体附带类别名和置信度；假 = 只给位置框（更快）。自定义模型的分类标签来自模型自带的元数据，所以中文模型直接就是中文。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
模型文件: TFLite 模型文件。填素材文件名（如 parts.tflite，先把文件上传到项目素材）或设备绝对路径（含 / 即视为路径）。改这个属性会重建检测器，立即生效。
多个物体: 是否检测多个物体。真（默认）= 找出画面里最多 5 个物体；假 = 只找最显眼的那一个（更快）。改了会重建检测器，立即生效。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面上框出检测到的物体（带类别和置信度）。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

检测失败时(操作,错误信息): 检测失败。常见原因：「模型文件」没设或文件不存在、模型不是 TFLite 目标检测模型、模型缺少标签元数据。
获得物体(索引,x坐标,y坐标,宽度,高度,标签文字,置信度,跟踪编号): 每检测到一个物体触发一次，方便逐个画框。index 从 1 开始；x/y 是框的左上角，width/height 是框的宽高（单位：原图像素）；label/confidence 是粗分类结果（「是否分类」为假时 label 为空）；trackingId 是跨帧跟踪编号，单张图片检测时为 -1。
获得物体列表(数量,图片宽度,图片高度,结果JSON): 检测完成的汇总。count 是物体个数；imageWidth/imageHeight 是原图尺寸（画框换算坐标时要用）；resultJson 含每个物体的边界框、跟踪 id 和分类标签。
实时检测到物体(数量,图片宽度,图片高度,结果JSON): 实时检测的结果，按「实时事件间隔」限频触发。count 是物体个数（可能为 0）；imageWidth/imageHeight 是摄像头画面尺寸（换算坐标时要用）；resultJson 与「获得物体列表」事件的格式相同，trackingId 在连续画面里保持不变。
未找到物体(操作): 图里没检测到物体。这不是错误 —— 目标检测适合画面里有明确主体的照片，纯风景/纯文字图常常检测不到。

方法

检测Base64图片(Base64文本): 检测 Base64 图片里的物体。支持纯 Base64，也支持带 data:image/…;base64, 前缀的写法。
检测图片文件(路径): 检测图片文件里的物体。参数可以是素材文件名、本地路径、file:// 或 content:// 地址。
打开实时摄像头(): 打开摄像头用自定义模型实时检测物体，画面显示在「预览容器」里，并在画面上框出每个物体。结果按「实时事件间隔」触发「实时检测到物体」事件，同一个物体在连续画面里有不变的跟踪编号。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

手势识别

手势识别：找出画面里的手，给出每只手的 21 个关键点（手腕、各手指的指根、关节、指尖），以及 7 种内置手势：握拳、张开手掌、食指向上、拇指向下、点赞、剪刀手、我爱你。可识别图片，也可打开摄像头实时识别；还能把贴图贴在手上（跟着手移动、按手掌宽度缩放、随手的方向旋转）。适合石头剪刀布、隔空翻页、手势控制小车、手部 AR 特效。基于 Google MediaPipe，模型随 App 打包，完全离线，不需要 Google Play 服务。需要 Android 7.0 以上。

本土化简化版（全程离线运行）：对应 MIT 社区的 HandPose 方案（TensorFlow.js + CustomWebView 拓展，在网页里跑手部模型）和 MIT 石头剪刀布教程（用 Teachable Machine 训练手势）。手势识别是内置组件，不用导入拓展、不依赖网页引擎和国外服务，7 种常用手势不用训练直接认。
左右手：给出的是被拍人自己的左右手，前置、后置摄像头和照片都一样。
石头剪刀布：石头 = Closed_Fist（握拳），布 = Open_Palm（张开手掌），剪刀 = Victory（剪刀手）。

鸿蒙：暂不支持：鸿蒙系统没有开放手部关键点与手势识别接口，图片识别、实时摄像头与保存画面都会触发「检测失败时」事件说明原因，添加贴图不起作用。

使用指导识别手势、数手指、和手机猜拳查看 →

快速上手

when Screen1.Initialize() {
  HandGesture1.StartLiveCamera()
}
when HandGesture1.LiveHands(手数, 图片宽度, 图片高度, 结果JSON) {
  if 手数 > 0 {
    标签1.Text = join(HandGesture1.Handedness(1), "：", HandGesture1.GestureName(1))
  } else {
    标签1.Text = "把手伸到镜头前"
  }
}
when HandGesture1.DetectFailed(操作, 错误信息) {
  标签1.Text = 错误信息
}

在设计器里把「预览容器」设为一个垂直布局（宽度充满、高度 300 像素左右）。

属性

正在识别: 是否正在识别图片。
手势代码: 内置手势代码，用英文逗号分隔：Closed_Fist 握拳、Open_Palm 张开手掌、Pointing_Up 食指向上、Thumb_Down 拇指向下、Thumb_Up 点赞、Victory 剪刀手、ILoveYou 我爱你、None 没认出。石头剪刀布：石头 = Closed_Fist，布 = Open_Palm，剪刀 = Victory。
关键点名称: 可用的关键点名，用英文逗号分隔：WRIST 手腕，THUMB_ 拇指、INDEX_FINGER_ 食指、MIDDLE_FINGER_ 中指、RING_FINGER_ 无名指、PINKY_ 小指，后缀 MCP 指根、PIP / IP 中间关节、DIP 末端关节、TIP 指尖。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
最多手数: 最多识别几只手，1～4，默认 2。
最低置信度: 检测置信度阈值，0～1，默认 0.5。调高更不容易误认，调低远处的小手也能找到。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
显示标注: 是否在预览画面上画出手部骨架（关键点与连线）并在左上角标出手势。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

检测失败时(操作,错误信息): 识别失败。operation 是出错的方法名。
获得手势(手数,结果JSON): 识别出图片里的手。handCount 是手的数量；resultJson 含每只手的左右、手势代码与中文名、21 个关键点坐标。也可以在这个事件里调「手势」「关键点」等方法取数据。
画面已保存(图片地址): 「保存当前画面」完成。imagePath 是生成的 PNG 文件路径（含贴图），可以直接给「图像」组件的「图片」属性，或用「分享」组件发出去。
实时检测到手(手数,图片宽度,图片高度,结果JSON): 实时识别的结果，按「实时事件间隔」限频触发。handCount 是手的数量（可能为 0）；imageWidth/imageHeight 是摄像头画面尺寸；resultJson 与「获得手势」相同。在事件里调「手势」「关键点」取这一帧的数据。
未找到手(操作): 图里没找到手。

方法

添加贴图(名称,图像位址,锚点,宽度比例,横向偏移,纵向偏移): 在实时画面上添加一张贴图（帽子、眼镜、胡子等），跟着人移动、缩放、随头部倾斜旋转。name 是贴图名，同名再添加就是替换；image 是图片素材名（建议用透明背景的 PNG）；anchor 是锚点：手部关键点名称（见「关键点名称」属性），如 WRIST 手腕、INDEX_FINGER_TIP 食指尖、MIDDLE_FINGER_MCP 中指根；widthRatio 是贴图宽度相对手掌宽度（食指根到小指根的距离）的倍数（如 1.2）；offsetX / offsetY 是贴图中心相对锚点的偏移，也按手掌宽度（食指根到小指根的距离）计（offsetY 为负往上，如 -0.6）。贴图不受「显示标注」影响，做滤镜时可以关掉标注只留贴图。
保存当前画面(): 把实时画面当前这一帧连同贴图存成 PNG 图片，完成后触发「画面已保存」事件。前置摄像头的画面与预览一样是镜像的。只在实时摄像头运行时可用。
清空贴图(): 移除全部贴图。
检测图片文件(路径): 识别图片文件里的手和手势。参数可以是素材文件名、设备路径、file:// 或 content:// 地址。成功触发「获得手势」，没有手触发「未找到手」。
手势(手序号): 取上一次结果里某只手的手势代码，如 Victory、Closed_Fist（见「手势代码」属性）；没认出或没有这只手时返回 None。handIndex 从 1 开始。
手势名称(手序号): 取上一次结果里某只手的手势中文名，如剪刀手、握拳；没认出返回「无」。handIndex 从 1 开始。
左右手(手序号): 取上一次结果里某只手是左手还是右手（被拍人自己的左右），返回「左手」或「右手」；没有这只手时返回空。handIndex 从 1 开始。
关键点(名称,手序号): 取上一次结果里某只手的一个关键点，返回列表 [x, y, z]（图片像素；z 为相对手腕的深度，越小越靠近镜头）。handIndex 从 1 开始。没有结果或名字不对时返回空列表。
移除贴图(名称): 移除一张贴图（按添加时的名称）。
打开实时摄像头(): 打开摄像头实时识别手势，画面显示在「预览容器」里，并在画面上画出手部骨架、标出手势。结果按「实时事件间隔」触发「实时检测到手」事件，在事件里用「手势」「关键点」取这一帧的数据，石头剪刀布这类游戏就这样做。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。

即教即识

即教即识：在 App 里现拍现教。每个类别对着摄像头拍几张到几十张样本，就能实时分辨物体、手势、表情、零食包装……不用电脑、不用联网、不用写模型。训练好的结果可以保存成文件，下次直接载入；也可以把保存的文件作为素材上传，App 一打开就能认。基于 Google MediaPipe 图像特征提取（模型随 App 打包，完全离线），需要 Android 7.0 以上。

本土化简化版（全程离线运行）：对应 PersonalImageClassifier（PIC）和 TeachableMachine 拓展。那两个拓展要先到国外网站训练（TeachableMachine 运行时还要在线加载模型），即教即识是内置组件，在手机上或本站即教即识训练台里训练，完全离线。几种方案的关系和区别看图像分类方案对比。
原理：每张图先变成一串特征数字，分类时找和它最像的样本（k 近邻），所以加样本立刻生效，不需要等待训练。
随时取结果：「当前类别」「置信度」「各类别置信度」（字典）三个属性保存最近一次分类，实时分类时点按钮读一下就是「识别当前画面」；「切换摄像头」在识别中也能切前后摄像头。
和「自定义图像分类」的区别：自定义图像分类要先在电脑上用 Teachable Machine 等工具训练好 TFLite 模型再导入（Teachable Machine 网站国内打不开）；即教即识在手机上直接教，适合课堂实验、个人小项目。类别多（几十类以上）、要求高精度时，仍建议训练专门的模型。
为教学做了简化：面向课堂和入门，去掉了选网络、加层、学习率、训练轮数这些参数，加了样本立刻生效，几分钟就能教会。需要进阶功能时：
- 想讲神经网络怎么训练、自己调参数：用 PersonalImageClassifier 拓展（它的训练网页需要能访问国外网络）。
- 类别多（几十类以上）、数据集大、要求高精度，或想用现成的专业模型：在电脑上训练 TFLite 模型（Teachable Machine、TensorFlow 等），用自定义图像分类导入。
在电脑上教：即教即识训练台用电脑摄像头拍样本或拖入一批图片，还能测试每类的正确率，导出的模型文件上传为素材，「加载模型」即可使用。
教得好的窍门：每类 10～30 张，拍的时候慢慢变换角度、距离和背景；再教一个「背景」类（什么都不放），没东西时就不会乱认。

鸿蒙：暂不支持：鸿蒙系统没有开放通用图像特征提取接口，添加样本、分类、实时摄像头都会触发「分类出错」事件说明原因。

使用指导在手机上现拍现教，几张样本就能认查看 →

快速上手

when Screen1.Initialize() {
  TeachableClassifier1.StartLiveCamera()
}
when 按钮_杯子.Click() {
  TeachableClassifier1.AddSamplesFromCamera("杯子", 20)
}
when 按钮_笔.Click() {
  TeachableClassifier1.AddSamplesFromCamera("笔", 20)
}
when TeachableClassifier1.SampleAdded(类别, 数量) {
  标签_样本.Text = join(类别, "：", 数量, " 张")
}
when TeachableClassifier1.LiveClassification(类别, 置信度, 结果JSON) {
  if 类别 == "" {
    标签1.Text = "拿不准"
  } else {
    标签1.Text = join(类别, " ", round(置信度 * 100), "%")
  }
}

在设计器里把「预览容器」设为一个垂直布局（宽度充满、高度 300 像素左右）。点「杯子」按钮时把杯子放在镜头前慢慢转动，点「笔」按钮时换成笔，教完就能实时认出。

属性

正在识别: 是否正在处理图片（添加样本或分类）。
类别列表: 已教过的类别列表，按添加顺序。
当前类别: 最近一次分类（图片分类或实时分类）的类别；拿不准或还没分类过时为空。实时分类时随时读取它，就等于「识别一下当前画面」，比如点按钮时读一次做判断。
正在采集: 是否正在从摄像头采集样本。
置信度: 最近一次分类最可能的类别的置信度，0～1；还没分类过时为 0。
各类别置信度: 最近一次分类每个类别的置信度，是一个字典：键是类别名，值是 0～1 的置信度，加起来等于 1。用字典积木按类别名取值；还没分类过时是空字典。
实时摄像头运行中: 实时摄像头是否正在运行。
实时事件间隔: 实时检测事件的最短间隔（毫秒），默认 200，即每秒最多触发 5 次。画面上的标注每帧都更新，不受这个间隔限制；事件里做的事越多，间隔就该设得越大，否则界面会卡。
最低置信度: 最低置信度，0～1，默认 0.6。最可能的类别置信度低于它时，分类结果的类别为空（表示「拿不准」），避免把没教过的东西硬分到某一类。
预览容器: 实时检测时显示摄像头画面的可见组件，一般选一个垂直布局或水平布局，并给它明确的宽高（例如宽度「充满」、高度 300 像素），否则可能看不到画面。
样本总数: 全部类别的样本总数。
显示标注: 是否在预览画面左上角标出当前类别和置信度。
使用前置摄像头: 实时检测是否使用前置摄像头，默认用后置。实时检测进行中修改，下次打开时生效。

事件

分类出错(操作,错误信息): 出错。operation 是出错的方法名。
获得分类(类别,置信度,结果JSON): 图片分类完成。category 是最可能的类别（置信度低于「最低置信度」时为空，表示拿不准）；confidence 是置信度 0～1；resultJson 含每个类别的置信度，如 “scores”: 石头 0.91, 布 0.06, 剪刀 0.03 这样的键值。
实时分类(类别,置信度,结果JSON): 实时分类的结果，按「实时事件间隔」限频触发。参数与「获得分类」相同。
模型加载时(类别数,样本数): 模型加载时。categoryCount 是类别数，sampleCount 是样本总数。
模型已保存(路径): 模型已保存。path 是文件的完整路径，下次用「加载模型」传这个路径（或只传文件名）即可。
样本已添加(类别,数量): 某个类别添加了一张样本。count 是这个类别现在的样本数。

方法

添加样本(类别,图像位址): 用一张图片给某个类别添加样本。图片可以是素材文件名、设备路径、照相机拍的照片等。完成后触发「样本已添加」。每个类别至少要有 1 张样本才能分类，5～20 张、角度和背景多变一些效果更好。
从摄像头采集样本(类别,数量): 从实时摄像头连续采集 count 张样本给某个类别（每张间隔约 0.15 秒，期间慢慢变换角度、距离），每采到一张触发一次「样本已添加」。要先打开实时摄像头。count 为 1 就是只拍一张。
图片分类(图像位址): 给一张图片分类，完成后触发「获得分类」。至少要教过一个类别。
清除所有数据(): 清空全部类别和样本，从头教。
加载模型(文件名): 载入保存过的模型，替换当前全部类别和样本。可以是「保存模型」给出的路径、只写文件名（App 自己的目录），也可以把模型文件作为素材上传后写素材名，App 一打开就能用。完成后触发「模型加载时」。

警告：文件名请用字母和数字：中文名在手机上能存取，但模型文件作为素材上传时素材名不支持中文，会被自动改名，加载就对不上了。
删除类别(类别): 删除一个类别和它的全部样本。
类别样本数(类别): 某个类别有几张样本；没有这个类别返回 0。
保存模型(文件名): 把训练好的模型（全部类别的样本特征，不含图片）保存成 JSON 文件。fileName 只写文件名（如 model.json）时存在 App 自己的目录里，不需要存储权限；也可以写完整路径。完成后触发「模型已保存」，给出完整路径。

警告：文件名请用字母和数字：中文名在手机上能存取，但模型文件作为素材上传时素材名不支持中文，会被自动改名，加载就对不上了。
打开实时摄像头(): 打开摄像头实时分类，画面显示在「预览容器」里，左上角标出当前类别和置信度。结果按「实时事件间隔」触发「实时分类」事件。训练时也要先打开摄像头，再用「从摄像头采集样本」给每个类别拍样本。
停止采集(): 停止从摄像头采集样本。
关闭实时摄像头(): 关闭实时摄像头并移除预览画面。
切换摄像头(): 切换前置 / 后置摄像头。实时摄像头开着时立即切换，没开时改「使用前置摄像头」，下次打开生效。