更新记录

1.0.0（2026-09-22）

cc-fingerprint 指纹认证 UTS 插件使用说明

插件简介

cc-fingerprint 是一个 HarmonyOS 指纹认证 UTS 插件，通过鸿蒙原生 @kit.UserAuthenticationKit 实现指纹检测与验证功能。

适用于需要在鸿蒙端实现指纹登录、指纹解锁等生物识别场景的 uni-app 项目。

平台兼容性

环境要求

• HBuilderX >= 4.24.0
• HarmonyOS SDK >= 6.0.0(20)
• uni-app Vue3 项目

目录结构

cc-fingerprint/
├── package.json                    # 插件配置
├── index.js                        # JS 桩文件（H5/小程序平台模块解析用）
├── index.d.ts                      # TypeScript 类型声明
├── utssdk/
│   ├── interface.uts               # 接口定义（不加密）
│   ├── app-harmony/
│   │   └── index.uts               # 鸿蒙原生实现
│   └── app-android/
│       └── index.uts               # 安卓桩实现

API 说明

1. getFingerprintStatus()

检测设备指纹状态（硬件支持 + 已录入）。

返回值：Promise<FingerprintStatus>

interface FingerprintStatus {
  supported: boolean  // 设备是否支持指纹
  enrolled: boolean   // 是否已录入指纹
}

示例：

const status = await getFingerprintStatus()
if (status.supported && status.enrolled) {
  console.log('指纹可用')
} else if (status.supported && !status.enrolled) {
  console.log('设备支持指纹但未录入')
} else {
  console.log('设备不支持指纹')
}

2. fingerVerify(options)

触发指纹验证，弹出系统指纹认证界面。

参数：

interface FingerVerifyOptions {
  message?: string              // 指纹弹窗提示文案，默认"请验证指纹"
  success?: (res: any) => void  // 验证成功回调
  fail?: (err: any) => void     // 验证失败/取消回调
}

示例：

fingerVerify({
  message: '请验证指纹以完成登录',
  success(res) {
    console.log('验证成功', res)
  },
  fail(err) {
    console.log('验证失败', err.errMsg)
  }
})

错误码说明：

3. openFingerprintSettings()

尝试打开系统指纹设置页。

返回值：Promise<boolean>

• 鸿蒙端始终返回 false（无法直接跳转系统设置），由调用方显示文字引导
• 安卓端通过 plus.runtime.openURL 打开安全设置

示例：

const success = await openFingerprintSettings()
if (!success) {
  uni.showModal({
    title: '开启指纹',
    content: '请前往：设置 → 生物识别和密码 → 指纹',
    showCancel: false
  })
}

鸿蒙端权限

插件使用以下鸿蒙系统权限（在 module.json5 中声明）：

{
  "name": "ohos.permission.ACCESS_BIOMETRIC",
  "reason": "$string:biometric_permission_reason",
  "usedScene": {
    "abilities": ["EntryAbility"],
    "when": "inuse"
  }
}

该权限为 system_grant 类型，安装时自动授予，无需用户手动授权。

推荐用法：混合方案

实际项目中，安卓和鸿蒙的指纹实现方式不同，建议封装统一的工具类：

// utils/fingerprint.js

// 鸿蒙端引入 UTS 插件
// #ifdef APP-HARMONY
import { getFingerprintStatus as harmonyGetStatus, fingerVerify as harmonyVerify, openFingerprintSettings as harmonyOpenSettings } from '@/uni_modules/cc-fingerprint'
// #endif

export function getFingerprintStatus() {
  return new Promise((resolve) => {
    // #ifdef APP-HARMONY
    harmonyGetStatus().then(resolve)
    return
    // #endif

    // #ifdef APP-PLUS
    // 安卓端使用 uni SOTER API
    uni.checkIsSupportSoterAuthentication({
      success(supportRes) {
        const hasFp = (supportRes.supportMode || []).some(m => m === 'fingerPrint')
        if (!hasFp) { resolve({ supported: false, enrolled: false }); return }
        uni.checkIsSoterEnrolledInDevice({
          checkAuthMode: 'fingerPrint',
          success(enrollRes) { resolve({ supported: true, enrolled: !!enrollRes.isEnrolled }) },
          fail() { resolve({ supported: true, enrolled: false }) }
        })
      },
      fail() { resolve({ supported: false, enrolled: false }) }
    })
    // #endif

    // #ifdef H5
    resolve({ supported: false, enrolled: false })
    // #endif
  })
}

export function fingerVerify(options = {}) {
  const { message = '请验证指纹', success, fail } = options

  // #ifdef APP-HARMONY
  harmonyVerify({ message, success, fail })
  return
  // #endif

  // #ifdef APP-PLUS
  uni.startSoterAuthentication({
    requestAuthModes: ['fingerPrint'],
    challenge: String(Date.now()),
    authContent: message,
    success, fail
  })
  // #endif
}

Demo 工程

桌面 cc-fingerprint-demo 目录包含完整的使用示例工程，可直接用 HBuilderX 打开运行。

运行步骤：

1. HBuilderX 打开 cc-fingerprint-demo 目录
2. 运行 → 运行到手机或模拟器 → 鸿蒙（需连接鸿蒙真机或模拟器）
3. 在 demo 页面中测试指纹检测、验证、设置功能

技术实现要点

• 使用 @kit.UserAuthenticationKit 的 getUserAuthInstance 发起认证
• 32 字节随机挑战值替代硬编码，提升安全性
• 兼容 HarmonyOS 6.1 部分设备返回码 12500000（有 token 时判定成功）
• 认证前预检：不支持或未录入时不拉起认证界面
• 防重入：settled 标志位防止回调重复触发

平台兼容性

uni-app(5.24)

uni-app x(5.24)

其他