# @azure/ai-vision-face-ui 中文文档 规范地址：https://npmcn.com/package/%40azure/ai-vision-face-ui/ 版本：1\.5\.2 npm 元数据更新时间：2026-11-06T23:02:35.109Z 中文译文更新时间：2026-11-07T17:14:40.598Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40azure/ai-vision-face-ui 原文对照：https://npmcn.com/package/%40azure/ai-vision-face-ui/?lang=original 项目主页：https://github.com/Azure-Samples/azure-ai-vision-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：121 kB，8 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2025-07-24T19:25:21.855Z - 最新版本发布：2026-11-06T23:02:34.949Z - 近 30 天下载量：3878（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：12（近 12 个月 6 个） ## 中文简介 Azure AI 远景面 (UI) 网络 SDK ## 安装 ```sh npm install @azure/ai-vision-face-ui ``` 也可以使用：`pnpm add @azure/ai-vision-face-ui`、`yarn add @azure/ai-vision-face-ui`、`bun add @azure/ai-vision-face-ui` ## README # 开始使用 Azure AI 愿景 Face UI Web SDK 在这个样本中,你会学会如何构建和运行面部活性检测应用程序. ## 目录 - [导言](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-introduction) - [先决条件](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-prerequisites) - [安装](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-installation) - [网络部分和运行时间资产](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-web-component-and-runtime-assets) - [将面部活性探测器纳入自己的应用程序](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-integrate-face-liveness-detector-into-your-own-application) - [获取会话符号](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-obtaining-a-session-token) - [注入网络组件](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-injecting-the-web-component) - [重试活性检查](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-retrying-a-liveness-check) - [使用 Iframe 中的 SDK](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-using-the-sdk-inside-an-iframe) - [部署](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-deployment) - [本地化](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-%F0%9F%8C%8D-localization) - [设置区域](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-%F0%9F%8C%90-setting-a-locale) - [UX 自定义](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-ux-customization) - [增加亮度图像](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-increase-your-brightness-image) - [字体大小](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-font-size) - [字体家族](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-font-family) - [继续按钮](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-continue-button) - [反馈信息](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-feedback-messages) - [财务问题](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-faq) - [问:怎么才能得到现场直播的结果?](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-q-how-can-i-get-the-results-of-the-liveness-session) - [问:我的重试失败, 否则会话不会再次启动 。 发生什么事了?](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-q-my-retry-fails-or-the-session-will-not-start-a-second-time-what-is-wrong) - [问:我如何实现资产部署自动化?](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-q-how-can-i-automate-deployment-of-the-assets) ## 导言 Azure AI Vision Face UI Web SDK是一个客户端库,旨在将面相活性功能整合到网络应用中. 它与Azure AI Face APIS无缝地工作,以确定一张相片在视频流中的真实性. - API 参考 : [AzureAI Vision FaceUI 乌兹别克](https://aka.ms/azure-ai-vision-face-liveness-client-sdk-web-api-reference-modules) ## 先决条件 1. Azure Face API 资源订阅 . 2. 安装节点从 [https://nodejs.org/en/download/prebuilt-installer (中文(简体) )](https://nodejs.org/en/download/prebuilt-installer) ## 安装 1. 在 app 文件夹的 root 中创建 .npmrc 文件以拉取软件包 `https://pkgs.dev.azure.com/msface/SDK/_packaging/AzureAIVision/npm/registry/` 登记. 这里有示例.npmrc文件([https://github.com/Azure-Samples/azure-ai-vision-sdk/blob/main/samples/web/angularjs/.npmrc 互联网档案馆的存檔,存档日期2013-12-20](https://github.com/Azure-Samples/azure-ai-vision-sdk/blob/main/samples/web/angularjs/.npmrc)) (中文(简体) ). 2. 使用 API 获取 .npmrc 文件需要的 Base64 访问令牌 : [Liveness 会话操作 - 获取客户端资产访问](https://learn.microsoft.com/rest/api/face/liveness-session-operations/get-client-assets-access-token?view=rest-face-v1.3-preview) 3. 要通过国家防范机制安装 SDK, 请在应用程序文件夹的根部运行以下命令 : ```sh npm install @azure/ai-vision-face-ui@latest ``` ## 网络部分和运行时间资产 Web SDK安装包含两个浏览器侧包: - `@azure/ai-vision-face-ui` 向公众提供 `` 组件及其类型定义. - `@azure-ai-vision-face/ui-assets` 提供闸门运行时间资产, 包括本地化、 JavaScript 加载器和 WebAssembly 下级 `facelivenessdetector-assets/`。 。 。 . 部署完整 `facelivenessdetector-assets` 网站目录 树根。 该组件检测WebAssembly SIMD支持并选择 可用时 SIMD 运行时间, 兼容的非 SIMD 运行时间 倒计时。 只复制一个装入器或 `.wasm` 文件因此可以断开 其他浏览器上的经验. 如果你创建活性会话 `clientType: "web"`,同时安装 `@azure-ai-vision-face/ui-server` 在您的应用程序服务器上, 从相同的 登记簿和登记簿 `@azure-ai-vision-face/ui-assets`。 。 。 . 每场比赛都要写 `wasmInjectionBuffer` 在你进入WASM之前 服务器将其发送到浏览器; 查看软件包 README 是否使用. ```sh npm install @azure-ai-vision-face/ui-server@ ``` Gated 发行不使浏览器资产秘密: JavaScript 和 浏览器下载的WASM可以检查. 永远不要暴露面孔 前端代码中的 API 密钥,并通过 你的应用服务器。 紧接着 [面相活性架构](https://learn.microsoft.com/azure/ai-services/face/concept-face-liveness-detection#how-it-works), (中文(简体) ), 服务器创建短寿命会话并发送授权 前端的符号; 前端运行 SDK, 而服务器 获取现场结果 . ## 将面部活性探测器纳入自己的应用程序 首先,确保您已经安装了 npm 包,如 [安装](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-installation) 节. ### 获取会话符号 启动现场会议需要会议授权。 见 `fetchTokenOnServer` 内 `server.js` 演示的文件方法. 关于如何利用Azure AI Vision Face服务来调节活性流动的更多信息,请访问: [https://aka.ms/azure-ai-vision-face-lifence-toural (英语)](https://aka.ms/azure-ai-vision-face-liveness-tutorial) ### 注入网络组件 在获得有效的会话授权键后,您可以整合网络组件, `` 元素,使用 JavaScript . ```javascript const azureAIVisionFaceUI = document.createElement("azure-ai-vision-face-ui"); document.getElementById("your-container-id").appendChild(azureAIVisionFaceUI); azureAIVisionFaceUI.start("***FACE_API_SESSION_TOKEN***") .then(resultData => { // The resultData which is LivenessDetectionSuccess interface. // The result of analysis is queryable from the service using sessions result API // https://learn.microsoft.com/rest/api/face/liveness-session-operations/get-liveness-session-result?view=rest-face-v1.2-preview.1&tabs=HTTP }) .catch(errorData => { // In case of failures, the promise is rejected. The errorData which is LivenessDetectionError interface, contains the reason for the failure. }); ``` ### 重试活性检查 一个会话符号代表一个活性会话。 您可以让用户在该会话内进行不止一次尝试, 只要您停留在同一已装入的页面上, 无需向您的后端询问新的符号 . 要重试, 删除已有的 `` 元素,创建新元素,并调用 `start()` 再来一次 **不变** 符号 。 不重装页面以重试 . ```javascript function retryLivenessCheck() { // 1. Remove the previous detector instance. document.querySelector("azure-ai-vision-face-ui")?.remove(); // 2. Create a fresh instance on the same page and reuse the same token. const azureAIVisionFaceUI = document.createElement("azure-ai-vision-face-ui"); document.getElementById("your-container-id").appendChild(azureAIVisionFaceUI); azureAIVisionFaceUI.start("***FACE_API_SESSION_TOKEN***") // same token as the first attempt .then(resultData => { /* ... */ }) .catch(errorData => { /* ... */ }); } ``` 什么时候问你的后端 **新设** 符号而不是重用当前符号 : - 您正在开始一个真正的新动态会话( 新用户或新检查) . - 该页面已全部重新装入( 见 [使用 Iframe 中的 SDK](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-using-the-sdk-inside-an-iframe) 重新装入为何重要). - `start()` 以 `LivenessError.InvalidToken`。这意味着当前符号已经达到了允许使用的尾声,下一次尝试需要一个新的会话的新符号. 在运行 SDK 的页面被重新装入后, 无法重用一个符号 。 重新装入开始流出, 因此它需要一个新会话的符号 . ### 使用 Iframe 中的 SDK SDK在iframe内部的工作与在一页上层的工作相同. 在iframe中本身并不是特例,也不改变道具或再试如何工作. 重试最重要的一件事是 SDK 运行的页面是 **已全部重新装入** 尝试之间: - 如果您的重试能保持页面活性, 只重新创建 `` 元素(如 [重试活性检查](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-retrying-a-liveness-check)),同一同物继续工作. 无论是SDK处于顶级还是Iframe内部都是如此. - 如果你的重试 **重新装入页面** (例如,通过设置iframe's `src` 再一次,导航它,或呼叫 `location.reload()` 这是一个新的开端,需要从新的会议中获得一个象征。 重新装入后重用上一个符号不会成功 . 这是有意的:一个会话符号被绑在单个会话上,因此不能被带入新装入的页面并在那里再使用. 如果一个母页在iframe中托管了SDK并拥有"再试"控制,则更倾向于告诉iframe重新尝试到位,而不是重新加载. 一个简单的方法就是向iframe发送一个消息,让iframe重新运行重试步骤: ```javascript // In the parent page, on "Try again": iframe.contentWindow.postMessage({ type: "retry-liveness" }, iframeOrigin); // Inside the iframe page: window.addEventListener("message", (event) => { if (event.origin !== expectedParentOrigin) return; // always validate the sender's origin if (event.data?.type !== "retry-liveness") return; retryLivenessCheck(); // re-creates the element, reuses the same token, no reload }); ``` JavaScript样本中包含一个工作母体+iframe实例. ### 部署 基本资产,例如WebAssembly二进制和本地化文件安装在 `node_modules/@azure-ai-vision-face/ui-assets/facelivenessdetector-assets`。部署完整的目录到 `/facelivenessdetector-assets` 在您的应用程序的公开根. ## \* 本地化 Azure AI Vision Face UI SDK通过支持多种语言来拥抱全球多样性. 支持的地语和语言词典的完整列表可供使用 [这里](https://github.com/Azure-Samples/azure-ai-vision-sdk/tree/main/samples/Localization.md) ### • 设置区域 要使用特定的地块,将地块属性指定为azure-ai-vision-face-ui组件. 如果该地语有译名,则使用;否则,SDK会默认为英语. - 示例 - 扶持葡萄牙语 ```javascript const azureAIVisionFaceUI = document.createElement("azure-ai-vision-face-ui"); azureAIVisionFaceUI.locale = "pt-PT"; // Setting Portuguese locale document.getElementById("your-container-id").appendChild(azureAIVisionFaceUI); ``` ## UX 自定义 您可以使用以下选项自定义页面布局 : ### 增加亮度图像 自定义默认的“ 增加屏幕亮度 ” 图像, 提供自己的图像 。 确保正确部署图像用于制作. azureAI Vision FaceUI. Braightness ImagePath = 新ImagePath; 互联网档案馆的存檔,存档日期2013-12-21; ### 字体大小 自定义所有文本的默认字体大小。 默认为1.5雷姆 azureAI Vision FaceUI.fontSize = 新Size; 互联网档案馆的存檔,存档日期2013-12-21; ### 字体家族 自定义所有文本的默认字体家族 。 默认值为 `font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;` azureAI Vision FaceUI.font Family = 新家庭; ### 继续按钮 通过提供你自己的 CSS 样式来自定义“ 继续” 按钮的外观和感觉 。 更改文本, 使用 `languageDictionary` 属性并覆盖“继续”密钥. azureAI Vision FaceUI. Continue ButtonStyles = 新CSS; 互联网档案馆的存檔,存档日期2013-12-21; ### 反馈信息 通过提供您自己的 CSS 样式来自定义反馈信息的外观和感觉 . azureAIVisionFaceUI. feedbackMessageStyles = 新的CSS; 互联网档案馆的存檔,存档日期2013-12-02; ## 财务问题 ### 问:怎么才能得到现场直播的结果? 一旦会话完成并兑现承诺,出于安全原因,客户端不会收到结果,无论面孔是活的还是假的. 您可以通过调用会话结果 API 查询后端服务的结果以获取结果 [https://aka.ms/face/lifeness-session/get-lifeness-session-result 页面存档备份,存于互联网档案馆](https://aka.ms/face/liveness-session/get-liveness-session-result) ### 问:我的重试失败, 否则会话不会再次启动 。 发生什么事了? 这几乎总是 下到如何重试 和它使用的标志: - **在整页重新装入后重用一个符号 .** 会话符号绑定在一个会话上,一旦运行 SDK 的页面被重新装入,则无法再使用 。 如果您的“ 再次尝试” 重新装入页面( 或通过重新设置 iframe) `src`,导航它,或呼叫 `location.reload()`),请为这一尝试从新会话中求取一个符号。 见 [使用 Iframe 中的 SDK](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-using-the-sdk-inside-an-iframe)。 。 。 . - **不重装的重试得到支持,并且是推荐的模式.** 继续加载页面, 删除 `` 元素,创建新元素,并调用 `start()` 也一样 见 [重试活性检查](https://npmcn.com/package/%40azure/ai-vision-face-ui/#readme-retrying-a-liveness-check)。 。 。 . - **`start()` 以 `LivenessError.InvalidToken`。 。 。 .** 当前符已到被允许使用的结束. 在下次尝试前从新会话中获取新符号 . 请注意,在 Iframe 内运行不会改变这一切。 决定因素是页面是否被重新装入,而不是SDK是否处于iframe. ### 问:我如何实现资产部署自动化? - 反应 用于部署 您可以在您的软件包中添加构建后脚本。 json 将 facelidness detector - assets 复制到公众 ``` "scripts": { "postbuild": "cpy node_modules/@azure-ai-vision-face/ui-assets/facelivenessdetector-assets/**/* public/facelivenessdetector-assets --parents" } ``` - 角质 请看 [AngularJS 整合实例](https://github.com/Azure-Samples/azure-ai-vision-sdk/tree/main/samples/web/angularjs/src/face/face.component.ts) 时间 `samples/angularjs/src/face/face.component.ts` 用于部署, 您可以在配置文件的构建区域中添加配置 facelidness detector- assets ``` "build": { "options": { "assets": [ { "glob": "**/*", "input": "./node_modules/@azure-ai-vision-face/ui-assets/facelivenessdetector-assets", "output": "/facelivenessdetector-assets" } ], } } ``` ## 常见问题 ### @azure/ai-vision-face-ui 是什么？ Azure AI 远景面 \(UI\) 网络 SDK ### 如何安装 @azure/ai-vision-face-ui？ 在项目目录运行 npm install @azure/ai-vision-face-ui，或使用 pnpm add / yarn add / bun add。 ### @azure/ai-vision-face-ui 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @azure/ai-vision-face-ui 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @azure/ai-vision-face-ui 可以商用吗？ @azure/ai-vision-face-ui 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @azure/ai-vision-face-ui 的下载量有多少？ 根据 npm 官方下载统计，@azure/ai-vision-face-ui 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,878 次，日均约 129 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @azure/ai-vision-face-ui 还在维护吗？ 最新版本 1\.5\.2 发布于 2026/11/07（今天）；至今共发布 12 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/07/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。