# @biopassid/face-sdk 中文文档
规范地址：https://npmcn.com/package/%40biopassid/face-sdk/
版本：1\.3\.46
npm 元数据更新时间：2025-12-19T13:29:00.258Z
中文译文更新时间：2026-11-08T03:24:48.848Z
软件包许可：ISC
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40biopassid/face-sdk
原文对照：https://npmcn.com/package/%40biopassid/face-sdk/?lang=original
项目主页：https://github.com/biopass-id/face-sdk#readme
源码仓库：https://github.com/vsofttecnologia/face-sdk-js
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：854 kB，71 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2022-04-01T19:40:20.060Z
- 最新版本发布：2025-12-19T13:29:00.022Z
- 近 30 天下载量：2048（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 3 个）
## 中文简介
#
[](http://www.biopassid.com/)
## 安装
```sh
npm install @biopassid/face-sdk
```
也可以使用：`pnpm add @biopassid/face-sdk`、`yarn add @biopassid/face-sdk`、`bun add @biopassid/face-sdk`
## README
#
[](http://www.biopassid.com/)
#### BioPass ID Face SDK JavaScript. (原始内容存档于2018-09-29).
[](https://npmcn.com/package/%40biopassid/face-sdk/#)[](https://www.npmjs.com/package/@biopassid/face-sdk) [](https://www.instagram.com/biopassid/) [ ](https://www.biopassid.com/)[](https://www.biopassid.com/contacts)
[关键特性](https://npmcn.com/package/%40biopassid/face-sdk/#readme-key-features) 二. 支助 [自定义](https://npmcn.com/package/%40biopassid/face-sdk/#readme-customizations) 二. 支助 [演示](https://npmcn.com/package/%40biopassid/face-sdk/#readme-demo) 二. 支助 [第一步](https://npmcn.com/package/%40biopassid/face-sdk/#readme-firststeps) 二. 支助 [安装](https://npmcn.com/package/%40biopassid/face-sdk/#readme-nstalling) 二. 支助 [如何使用](https://npmcn.com/package/%40biopassid/face-sdk/#readme-how-to-use) 二. 支助 [示例](https://npmcn.com/package/%40biopassid/face-sdk/#readme-example) 二. 支助 [支助](https://www.biopassid.com/contacts)
## 关键特性
- 脸部检测
- 我们保证只有一张面孔
- 脸部定位
- 确保您在抓取时的面部位置, 以便更好的注册和匹配 .
- 自动抓取
- 当一个面孔被检测到时,捕获将在您配置的几秒内进行.
- 分辨率控制
- 配置图像大小思考图像质量与API响应时间之间的取舍.
- 光谱比控
- 完全自定义的接口
## 自定义
[](https://www.biopassid.com/sdk/facesdk)[ ](https://www.biopassid.com/sdk/facesdk)[](https://www.biopassid.com/sdk/facesdk)
在不损害用户体验的情况下,增强应用程序的安全性.
所有可用的定制 :
- 标题文本
- 帮助文本
- 正在装入文本
- 字体家族
- 面框
- 重叠
- 默认相机
- 抓取按钮
启用或禁用组件 :
- 标点文字
- 帮助文本
- 抓取按钮
- 按钮图标
- 翻转相机按钮
- 闪光按钮
更改所有颜色 :
- 重叠颜色和不透明
- 抓取按钮颜色
- 抓取按钮文本颜色
- 翻转相机颜色
- 闪光按钮颜色
- 文本颜色
## 演示
探索我们的特性 让你的应用程序做更多.
[网络演示](https://demo.biopassid.com/sdk) - BioPass ID Face SDK JavaScript 和 API's
[](https://demo.biopassid.com/sdk)
## 第一步
首先在您的应用程序的静态文件目录中创建一个名为模型的文件夹 。 装入并添加此两个文件
[微小 面相 检测器 模型- 硬度1](https://storage.googleapis.com/facecapturesdk/tiny_face_detector_model-shard1.shard)
[微小的 面部 检测器 模型- 重量 明显](https://storage.googleapis.com/facecapturesdk/tiny_face_detector_model-weights_manifest.json)
您的文件夹结构将像这样 :
```bash
/assets
/js
/css
/models
- tiny_face_detector_model-shard1
- tiny_face_detector_model-weights_manifest.json
/index.html
```
## 安装
> 通过捆绑器
安装依赖 :
```bash
npm i --save @biopassid/face-sdk
```
在您的工程中使用 :
```bash
import { camera } from '@biopassid/face-sdk'
```
> 通过CDN
将脚本添加到工程中, 模块将注入一个名为 faceSdk 的对象内:
```bash
```
## 如何使用
> 基本用途
```bash
import { camera } from '@biopassid/face-sdk'
```
> 添加面部验证
取Picture函数有一个叫"面相检测Adapter"的参数,这个函数负责进行验证处理,FaceSDK有一个用于面相检测的标准适配器. 还需要运行负责装入模型的函数
```bash
import { camera, faceDetectionAdapter, loadFaceDetectorModels } from '@biopassid/face-sdk'
const { takePicture } = camera();
async function handleTakePicture() {
await loadFaceDetectorModels(); // Carregamento dos modelos
const resp = await takePicture({
element: document.querySelector("#elementId"),
faceDetectionAdapter: faceDetectionAdapter,
})
}
```
> 添加自动抓取
要添加自动捕获,只需在选项参数内激活功能.
```bash
import { camera, faceDetectionAdapter, loadFaceDetectorModels } from '@biopassid/face-sdk'
const { takePicture } = camera();
async function handleTakePicture() {
await loadFaceDetectorModels();
const resp = await takePicture({
element: document.querySelector("#elementId"),
faceDetectionAdapter: faceDetectionAdapter,
options: {
faceDetection: {
autoCapture: true
}
},
})
}
```
> 国际化
可以通过参数i18n定义在面部检测时显示的文本.
```bash
import { camera, faceDetectionAdapter } from '@biopassid/face-sdk'
const { takePicture } = camera();
async function handleTakePicture() {
const resp = await takePicture({
element: document.querySelector("#elementId"),
faceDetectionAdapter: faceDetectionAdapter,
i18n: {
noFacesDetected: "Nenhuma face detectada",
multipleFacesDetected: "Multiplas faces detectadas",
moveFaceLeft: "Mova o rosto para a esquerda",
moveFaceRight: "Mova o rosto para a direita",
moveFaceUp: "Mova o rosto para cima",
moveFaceDown: "Mova o rosto para baixo",
moveFaceBack: "Mova o rosto para trás",
moveFaceCloser:: "Mova o rosto para frente"
keepStill: "Mantenha o rosto parado",
},
options: {
faceDetection: {
autoCapture: true
}
},
})
}
```
## 示例
> 带有全部属性的示例
所有元素都是可选的
```js
const resp = await takePicture({
element: document.querySelector("#camera"),
options: {
mask: {
enabled: true,
type: "face",
backgroundColor: "black",
backgroundOpacity: 0.6,
frameColor: "white",
frameThickness: 3,
},
backButton: {
enabled: true,
size: "30px",
backgroundColor: "transparent",
label: {
enabled: false,
content: "",
fontSize: "1rem",
fontWeight: "normal",
color: "white",
},
icon: {
enabled: true,
source: null,
color: "white",
size: "30px",
},
padding: "0",
},
captureButton: {
enabled: true,
size: "30px",
backgroundColor: "white",
label: {
enabled: false,
content: "",
fontSize: "1rem",
fontWeight: "normal",
color: "black",
},
icon: {
enabled: true,
source: null,
color: "black",
size: "30px",
},
padding: string,
},
cancelButton: {
enabled: true,
size: "30px",
backgroundColor: "red",
label: {
enabled: false,
content: "",
fontSize: "1rem",
fontWeight: "normal",
color: "white",
},
icon: {
enabled: true,
source: null,
color: "white",
size: "30px",
},
padding: "0",
},
confirmButton: {
enabled: true,
size: "30px",
backgroundColor: "white",
label: {
enabled: false,
content: "",
fontSize: "1rem",
fontWeight: "normal",
color: "black",
},
icon: {
enabled: true,
source: null,
color: "black",
size: "30px",
},
padding: string,
},
legend: {
title: {
enabled: true,
content: "Captura Facial",
fontSize: "1.5rem",
fontWeight: "600",
color: "white",
},
subtitle: {
enabled: true,
content: "",
fontSize: "1rem",
fontWeight: "normal",
color: "white",
},
},
faceDetection: {
enabled: true,
autoCapture: false,
timeToCapture: 3000,
timeToCaptureFeedbackColor: "#FF0000",
multipleFacesEnabled: true,
scoreThreshold: 0.1,
},
width: "100%",
height: "100%",
modelsDirectory: "/models",
cameraPresets: {
aspectRatio: 16 / 9,
preferredResolution: 480,
deviceId: null,
facingMode: "environment",
},
fontFamily: "inherit",
formatImage: "image/jpeg",
},
});
```
### 选项
要了解更多 SDK 的选项和方法,你可以查看我们完整的文件
[文档](https://docs.biopassid.com/#2ea0bce8-d144-4c8b-a44b-de3107ab9db1)
## 更改日志
## 1.3.46 (中文(简体) )
### 中断更改
- 在通过CDN使用插件时,功能被存储在一个名为faceSdk的对象上.
```html
```
## 常见问题
### 如何安装 @biopassid/face-sdk？
在项目目录运行 npm install @biopassid/face-sdk，或使用 pnpm add / yarn add / bun add。
### @biopassid/face-sdk 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @biopassid/face-sdk 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @biopassid/face-sdk 可以商用吗？
@biopassid/face-sdk 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @biopassid/face-sdk 的下载量有多少？
根据 npm 官方下载统计，@biopassid/face-sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,048 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @biopassid/face-sdk 还在维护吗？
最新版本 1\.3\.46 发布于 2025/12/19（10 个月前）；至今共发布 78 个版本，其中过去 12 个月发布了 3 个；首次发布于 2022/04/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。