# @capacitor-mlkit/face-detection 中文文档

规范地址：https://npmcn.com/package/%40capacitor-mlkit/face-detection/

版本：8\.2\.2
npm 元数据更新时间：2026-10-31T07:03:38.544Z
中文译文更新时间：2026-11-09T05:39:11.581Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capacitor-mlkit/face-detection
原文对照：https://npmcn.com/package/%40capacitor-mlkit/face-detection/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/mlkit/face-detection/
源码仓库：https://github.com/capawesome-team/capacitor-mlkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：187 kB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2023-07-20T16:31:52.345Z
- 最新版本发布：2026-10-31T07:03:38.213Z
- 近 30 天下载量：6309（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 9 个）

## 中文简介

在Android和iOS上为ML Kit Face检测所安装的电容插件.

## 安装

```sh
npm install @capacitor-mlkit/face-detection
```

也可以使用：`pnpm add @capacitor-mlkit/face-detection`、`yarn add @capacitor-mlkit/face-detection`、`bun add @capacitor-mlkit/face-detection`

## README

# 电容 ML Kit 面部检测插件

非官方电容插件 [ML Kit 面部检测](https://developers.google.com/ml-kit/vision/face-detection)\[^1\]

[![Thousands of teams ship faster with Capawesome Cloud Native Builds and Live Updates](https://capawesome.io/assets/banners/cloud-teams-ship-faster-with-capacitor.png)](https://capawesome.io/)

## 使用大小写

通常在应用程序需要定位图像中面相时使用面相检测插件,例如:

-   **图片组织**: 检测哪些相片包含面相并位于何处, 例如可以剪切周围的缩略图 .
-   **自我效应**:使用被检测到的面部地标和轮廓来将贴纸或其他虚拟元素放在面上.
-   **微笑检测**:利用分类结果确定一个人微笑或睁开眼睛的概率.
-   **脸部跟踪**: 使用跟踪选项对相接相框的每个面相保持一致的ID.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |
| 7.x.x (中文(简体) ) | 7.x.x (中文(简体) ) | 折旧 |
| 6.x.x (中文(简体) ) | 6.x.x (中文(简体) ) | 折旧 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/face-detection` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capacitor-mlkit/face-detection
npx cap sync
```

**请注意**: 此插件 **只支持可口可乐Pods** iOS的依赖性管理。 Swift 软件包管理器( SPM) 不支持 ML Kit SDK, 参见 [本评论](https://github.com/googlesamples/mlkit/issues/180#issuecomment-1298964099)。 。 。 .

### 机器人

#### 依赖关系

您需要添加以下元数据 **内** 页:1 `application` 在您的标签 `AndroidManifest.xml`数字 :

```xml
<meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="face"/>
<!-- To use multiple models: android:value="face,model2,model3" -->
```

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$mlkitFaceDetectionVersion` 版本 `com.google.mlkit:face-detection` (默认 : `16.1.7`(中文(简体) )
-   `$playServicesMlkitFaceDetectionVersion` 版本 `com.google.android.gms:play-services-mlkit-face-detection` (默认 : `17.1.0`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

### iOS系统

#### 最低部署目标

确定部署目标 `ios/App/Podfile` 至少改为 `15.5`数字 :

```ruby
platform :ios, '15.5'
```

## 配置

此插件不需要配置 .

## 演示

这里有一个实例: [robingenz/电容-mlkit-plugin-demo](https://github.com/robingenz/capacitor-mlkit-plugin-demo)

## 使用量

以下例子说明如何在图像中检测面相.

### 在图像中检测面相

在局部路径上用图像检测人类相貌. 可以配置精度/速率取舍,并实现地标,轮廓,分类(微笑和眼睛打开概率),并实现面相跟踪. 仅在Android和iOS上提供:

```typescript
import {
  FaceDetection,
  PerformanceMode,
  LandmarkMode,
  ContourMode,
  ClassificationMode,
} from '@capacitor-mlkit/face-detection';

const processImage = async () => {
  const { faces } = await FaceDetection.processImage({
    path: 'path/to/image.jpg',
    performanceMode: PerformanceMode.Fast,
    landmarkMode: LandmarkMode.All,
    contourMode: ContourMode.All,
    classificationMode: ClassificationMode.All,
    minFaceSize: 0.1,
    enableTracking: false,
  });
  return faces;
};
```

## API 密码

-   [`processImage(...)`](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-processimage)
-   [接口](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-enums)

### 进程图像(...)

```typescript
processImage(options: ProcessImageOptions) => Promise<ProcessImageResult>
```

从提供的图像中检测出人相.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ProcessImageOptions](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-processimageoptions)` |

**回返情况:** `Promise<[ProcessImageResult](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-processimageresult)>`

**自:** 5.1.0 国家

* * *

### 接口

#### 进程图像结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`faces`** | `Face[]` | 被检测出的脸. | 5.1.0 国家 |

#### 脸

代表被检测到的面相 `FaceDetector`。 。 。 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`bounds`** | `[Rect](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-rect)` | 返回检测到的面相的轴对齐矩形. | 5.1.0 国家 |
| **`landmarks`** | `FaceLandmark[]` | 返回一张面部地标列表. | 5.1.0 国家 |
| **`contours`** | `FaceContour[]` | 返回面相轮廓列表 . | 5.1.0 国家 |
| **`trackingId`** | `number` | 如果启动跟踪, 返回跟踪ID . | 5.1.0 国家 |
| **`headEulerAngleX`** | `number` | 返回关于图像水平轴的面相旋转。 阳性发作X是脸朝上看. | 5.1.0 国家 |
| **`headEulerAngleY`** | `number` | 返回图像垂直轴上的面相旋转。 阳性 euler y 是当面朝正在处理的图像的右侧转去时. | 5.1.0 国家 |
| **`headEulerAngleZ`** | `number` | 返回图像中指向轴的相向旋转。 正euler z是图像平面内逆时针旋转. | 5.1.0 国家 |
| **`smilingProbability`** | `number` | 返回 0.0 至 1.0 之间的值,使面部有微笑的概率. | 5.1.0 国家 |
| **`leftEyeOpenProbability`** | `number` | 返回 0.0 至 1.0 之间的值,使面部左眼有可能被打开. | 5.1.0 国家 |
| **`rightEyeOpenProbability`** | `number` | 返回 0.0 至 1.0 之间的值,使面部右眼有可能被打开. | 5.1.0 国家 |

#### 矩形

[矩形](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-rect) 为矩形持有四个整数坐标.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`left`** | `number` | 矩形左侧的X坐标. | 5.1.0 国家 |
| **`top`** | `number` | 矩形顶部的Y坐标. | 5.1.0 国家 |
| **`right`** | `number` | 矩形右侧的X坐标. | 5.1.0 国家 |
| **`bottom`** | `number` | 矩形下方的Y坐标. | 5.1.0 国家 |

#### 正面标记

代表一个脸部地标. 地标指被检测到的相貌上的一个点,如眼睛,鼻子,或口.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `[LandmarkType](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-landmarktype)` | 获得 [正面标记](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-facelandmark)。 。 。 .[地标类型](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-landmarktype) 类型. | 5.1.0 国家 |
| **`position`** | `[Point](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-point)` | 获得地标位置的2D分,其中(0,0)为图像左上角. | 5.1.0 国家 |

#### 点

[点](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-point) 持有两个坐标

| Prop | 类型 |
| --- | --- |
| **`x`** | `number` |
| **`y`** | `number` |

#### 相貌轮廓

代表面相轮廓. 轮廓是检测到的面相上点的列表,如口.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `[ContourType](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-contourtype)` | 获得 [相貌轮廓](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-facecontour)。 。 。 .[轮廓](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-contourtype) 类型. | 5.1.0 国家 |
| **`points`** | `Point[]` | 获取此面相轮廓的 2D 点列表, 其中 (0, 0) 是图像的左上角 . | 5.1.0 国家 |

#### 进程图像选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`path`** | `string` | 图像文件的本地路径 . |  | 5.1.0 国家 |
| **`performanceMode`** | `[PerformanceMode](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-performancemode)` | 定义在进行面孔检测时控制精度/速度权衡的选项. | `PerformanceMode.Fast` | 5.1.0 国家 |
| **`landmarkMode`** | `[LandmarkMode](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-landmarkmode)` | 定义是否启用面额地标的选项 . | `LandmarkMode.None` | 5.1.0 国家 |
| **`contourMode`** | `[ContourMode](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-contourmode)` | 定义是否启用外观轮廓的选项. | `ContourMode.None` | 5.1.0 国家 |
| **`classificationMode`** | `[ClassificationMode](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-classificationmode)` | 定义诸如"微笑"\*和"开眼"等属性的特征化选项. | `ClassificationMode.None` | 5.1.0 国家 |
| **`minFaceSize`** | `number` | 设置最小的想要的面相大小,以头宽与图像宽度的比例表示. | `0.1` | 5.1.0 国家 |
| **`enableTracking`** | `boolean` | 启用面部跟踪,在连续处理帧时,每个面部将保持一致的ID. 跟踪应被禁用,用于处理一系列非连续的静态图像. | `false` | 5.1.0 国家 |

### 数字

#### 地标类型

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`MouthBottom`** | `0` | 主体下唇形中央. | 5.1.0 国家 |
| **`LeftCheek`** | `1` | 主体左口角与被主体左眼外角的中点. 对于完整剖面来说,这成为了鼻基,鼻尖,左耳叶和左耳尖的中间体. | 5.1.0 国家 |
| **`LeftEar`** | `3` | 被试者左耳尖和左耳叶的中点. | 5.1.0 国家 |
| **`LeftEye`** | `4` | 主体中心为左眼腔. | 5.1.0 国家 |
| **`MouthLeft`** | `5` | 主体是唇相会的左口角. | 5.1.0 国家 |
| **`NoseBase`** | `6` | 被试者鼻孔相接面部的中点. | 5.1.0 国家 |
| **`RightCheek`** | `7` | 被试者右口角与被试者右眼外角的中点. 对于完整的剖面,这成为了鼻基,鼻尖,右耳叶和右耳尖的中间体. | 5.1.0 国家 |
| **`RightEar`** | `9` | 受试者右耳尖和右耳叶的中点. | 5.1.0 国家 |
| **`RightEye`** | `10` | 受试者右眼腔中心. | 5.1.0 国家 |
| **`MouthRight`** | `11` | 主体是唇相会的右口角. | 5.1.0 国家 |

#### 轮廓

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Face`** | `1` | 主体相貌的轮廓. | 5.1.0 国家 |
| **`LeftEyebrowTop`** | `2` | 题材上方出自"左眉". | 5.1.0 国家 |
| **`LeftEyebrowBottom`** | `3` | 主体左眉的下部轮廓. | 5.1.0 国家 |
| **`RightEyebrowTop`** | `4` | 受试者右眉毛上起相轮. | 5.1.0 国家 |
| **`RightEyebrowBottom`** | `5` | 主体右眉的下部轮廓. | 5.1.0 国家 |
| **`LeftEye`** | `6` | 受试者左眼腔的轮廓. | 5.1.0 国家 |
| **`RightEye`** | `7` | 受试者右眼腔的外观轮廓. | 5.1.0 国家 |
| **`UpperLipTop`** | `8` | 受试者上唇形顶部轮廓. | 5.1.0 国家 |
| **`UpperLipBottom`** | `9` | 主体上唇下方轮廓. | 5.1.0 国家 |
| **`LowerLipTop`** | `10` | 受试对象下唇上方轮廓. | 5.1.0 国家 |
| **`LowerLipBottom`** | `11` | 受试对象下唇下方轮廓. | 5.1.0 国家 |
| **`NoseBridge`** | `12` | 学科鼻桥分解纲要. | 5.1.0 国家 |
| **`NoseBottom`** | `13` | 学科鼻桥分解纲要. | 5.1.0 国家 |
| **`LeftCheek`** | `14` | 左颊之中. | 5.1.0 国家 |
| **`RightCheek`** | `15` | 右颊中央. | 5.1.0 国家 |

#### 绩效模式

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Fast`** | `1` | 在选项中表示对速度的偏好,以作出准确性与速度取舍。 这往往会发现面相较少,在确定位置等值时可能不太精确,但运行会更快. | 5.1.0 国家 |
| **`Accurate`** | `2` | 表示在选项中偏好准确性,以准确性与速度权衡。 这将倾向于检测出更多的面相,在以速度为代价确定位置等值时可能更为精确. | 5.1.0 国家 |

#### 地标模式

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`None`** | `1` | 不进行标志性检测. | 5.1.0 国家 |
| **`All`** | `2` | 探测器 [正面标记](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-facelandmark) 为了一个特定的脸. | 5.1.0 国家 |

#### 轮廓模式

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`None`** | `1` | 不进行轮廓检测 . | 5.1.0 国家 |
| **`All`** | `2` | 探测器 [相貌轮廓](https://npmcn.com/package/%40capacitor-mlkit/face-detection/#readme-facecontour) 为了一个特定的脸。 注意它会返回轮廓 最多5个面孔 | 5.1.0 国家 |

#### 分类模式

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`None`** | `1` | 不进行分类. | 5.1.0 国家 |
| **`All`** | `2` | 进行"眼开"和"笑"分类. | 5.1.0 国家 |

## 财务问题

### 此插件支持哪些平台 ?

这个 `processImage(...)` 方法只在Android和iOS上可用. 网络平台不支持基础的ML Kit Face SDK.

### 插件是否识别图片中是谁 ?

不,插件执行面部检测,而不是面部识别. 它在图像中检测出面相的位置以及地标,轮廓,头旋转等属性,并笑出概率,但并不识别个体. 与 `enableTracking` 选项中,您只能在连续的相框中为同一面相保持一致的ID.

### 地标和轮廓有什么区别?

地标是被检测出的脸上的一个单点,如眼,鼻,口等. 轮廓(英語:A Contour)是一列可以勾勒出面部特征的分数,如面部椭圆形,眉毛,眼睛或唇. 通过 `landmarkMode` 通过 `contourMode` 选项。 注意: 轮廓只返回最多5个面相 .

### 我怎么才能发现一个人是笑着还是睁开眼睛?

设定 `classificationMode` 选项到 `All`。然后检测到的面孔中包含 `smilingProbability`, (中文(简体) ), `leftEyeOpenProbability`,以及 `rightEyeOpenProbability` 属性,每个值在 0.0至 1.0 之间.

### 此插件与 Face Mesh 检测插件有何不同 ?

这个插件检测面相,有边框,地标,轮廓,以及Android和iOS的分类. 这个 [ML Kit 面膜检测](https://capawesome.io/docs/sdks/capacitor/mlkit/face-mesh-detection/) 插件返回一个由468个3D点和三角形信息组成的稠密网格,用于检测到的面相,但只在Android上可用.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [ML Kit 面膜检测](https://capawesome.io/docs/sdks/capacitor/mlkit/face-mesh-detection/): 探测器在图像中以468个3D分来面对 meshes.
-   [ML 基特自拍分裂](https://capawesome.io/docs/sdks/capacitor/mlkit/selfie-segmentation/): 以 ML Kit自拍片段为背景的自拍片段.
-   [ML Kit 主题分割](https://capawesome.io/docs/sdks/capacitor/mlkit/subject-segmentation/): 以ML Kit主题片段从背景中分离出主题.
-   [ML Kit Pose 检测](https://capawesome.io/docs/sdks/capacitor/mlkit/pose-detection/): 探测出的尸体与同一场景中的相貌并列.

## 术语和隐私

此插件使用 [Google ML Kit (Google ML Kit) 页面存档备份,存于互联网档案馆](https://developers.google.com/ml-kit)数字 :

-   [术语和隐私](https://developers.google.com/ml-kit/terms)
-   [Android 数据披露](https://developers.google.com/ml-kit/android-data-disclosure)
-   [iOS 数据披露](https://developers.google.com/ml-kit/ios-data-disclosure)

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/face-detection/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/face-detection/LICENSE)。 。 。 .

\[^1\]: 这个项目不附属于Google LLC或其任何子公司或子公司,也不获得其认可、支持、赞助或批准.

## 常见问题

### @capacitor-mlkit/face-detection 是什么？

在Android和iOS上为ML Kit Face检测所安装的电容插件\.

### 如何安装 @capacitor-mlkit/face-detection？

在项目目录运行 npm install @capacitor-mlkit/face-detection，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capacitor-mlkit/face-detection 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capacitor-mlkit/face-detection 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capacitor-mlkit/face-detection 可以商用吗？

@capacitor-mlkit/face-detection 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @capacitor-mlkit/face-detection 的下载量有多少？

根据 npm 官方下载统计，@capacitor-mlkit/face-detection 在 2026/10/09 – 2026/11/07 这 30 天内被下载 6,309 次，日均约 210 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capacitor-mlkit/face-detection 还在维护吗？

最新版本 8\.2\.2 发布于 2026/10/31（9 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 9 个；首次发布于 2023/07/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。