更新记录

1.2.0（2026-10-23）

适配蒸汽模式

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

UTS 生物识别认证与应用锁（指纹、Face ID、隐私页）

为 Android / iOS App 提供系统身份验证和可复用的页面锁。将业务内容放入锁组件，即可获得验证后显示、离开时隐藏、超时重新验证和原生后台隐私保护。

HBuilderX 5.26+；版本 1.2.0；插件 ID：austin-bio-x。普通授权 39.99 元，源码授权 499.99 元。

Web、小程序、鸿蒙和 nvue 不在本版支持范围。不依赖第三方 SDK、服务端 Key 或额外苹果证书。

第 1 步：导入插件，配置权限

把完整的 uni_modules/austin-bio-x 放入项目，保留 utssdk 与 components。

Android 自动合并普通权限，无需另外弹出相机授权：

<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" />

iOS 在宿主 manifest.json 合并 Face ID 用途说明。

uni-app x：

{
  "app-ios": {
    "distribute": {
      "privacyDescription": {
        "NSFaceIDUsageDescription": "用于身份验证和解锁隐私页面"
      }
    }
  }
}

普通 uni-app：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSFaceIDUsageDescription": "用于身份验证和解锁隐私页面"
        }
      }
    }
  }
}

首次导入或更新原生实现后，重新制作、安装并选择自定义基座。iOS 按常规方式使用 P12 和描述文件签名，本插件不使用 P8。

第 2 步：接通 App 前后台通知（应用锁必做）

在已有 App 生命周期中增加下面的调用，保留自己的其他逻辑。每个 App 接一次，所有锁组件自动共用；不需要在业务页面重复转发。

uni-app x 的 App.uvue：

import { notifyBiometricAppState } from '@/uni_modules/austin-bio-x/app-lifecycle.uts'

onAppShow((_options) => {
  notifyBiometricAppState(true)
  // 保留自己的前台逻辑。
})
onAppHide(() => {
  notifyBiometricAppState(false)
  // 保留自己的后台逻辑。
})

普通 uni-app 的 App.vue：

import { notifyBiometricAppState } from '@/uni_modules/austin-bio-x/app-lifecycle.ts'

export default {
  onShow() { notifyBiometricAppState(true) },
  onHide() { notifyBiometricAppState(false) }
}

已有 onShow/onHide 时直接把调用合进去。.uvue 使用 .uts，.vue 使用 .ts，不要混用；组件必须与 App 使用同一份状态模块。未接通时锁组件保持锁定，显示“应用锁暂未就绪”。单独使用 authenticate() 不需要这一步。

第 3 步：打开演示，按按钮测试

在 pages.json 的 pages 数组中追加两个页面：

{ "path": "uni_modules/austin-bio-x/index", "style": { "navigationBarTitleText": "生物识别认证", "disableScroll": true } },
{ "path": "uni_modules/austin-bio-x/privacy", "style": { "navigationBarTitleText": "隐私空间", "disableScroll": true } }

打开演示：

uni.navigateTo({ url: '/uni_modules/austin-bio-x/index' })

1. 手机先设置锁屏密码，录入指纹或 Face ID。
2. 点 开始验证，在系统弹窗完成或取消验证，页面直接显示结果。
3. 点 打开隐私页 → 验证并解锁，通过后出现演示资料。
4. 返回手机桌面，再进入 App：默认重新锁定；点 立即锁定 可手动测试。
5. 返回演示首页，展开 认证与样式设置，选择 15 秒，重新打开隐私页解锁。离开不超过 15 秒可恢复显示，超时则需重新验证。后台期间始终隐藏内容。

真机验证系统认证与后台预览。Android 安全窗口启用期间系统可能不允许截图；iOS 可在最近任务中检查遮挡效果。

第 4 步：直接沿用页面，或只引入锁组件

沿用页面：复制 privacy.uvue 到 pages/private/index.uvue，普通 uni-app 使用 privacy.vue。把该文件的组件导入改成下方示例中的绝对导入，注册新路由，再将演示资料替换成自己的内容即可。整个插件目录继续保留。

沿用组件：创建自己的 .uvue 页面，使用下面的最小示例。完成第 2 步的 App 通知后，active 还需随宿主页的显示和隐藏变化，用于处理路由切换。

<template>
  <view class="page">
    <bio-lock :active="active" :grace-seconds="15" :lock-token="lockToken"
      title="客户资料已锁定" reason="验证身份后查看客户资料"
      primary-color="#2563EB" @unlocked="onUnlocked" @locked="onLocked">
      <view class="private-content">
        <text>替换成自己的业务组件</text>
        <button @click="lockNow">立即锁定</button>
      </view>
    </bio-lock>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { onShow, onHide, onUnload } from '@dcloudio/uni-app'
import BioLock from '@/uni_modules/austin-bio-x/components/bio-lock/bio-lock.uvue'
import { AuthenticateResult } from '@/uni_modules/austin-bio-x'
const active = ref(false)
const lockToken = ref(0)
function lockNow(): void { lockToken.value += 1 }
function onUnlocked(result: AuthenticateResult): void {
  // 一次新的系统认证成功；业务接口继续检查登录态与账号权限。
}
function onLocked(reason: string): void {
  // 可在此清空页面保存的敏感数据。
}
onShow(() => { active.value = true })
onHide(() => { active.value = false })
onUnload(() => { active.value = false })
</script>

<style>
.page { flex: 1; }
.private-content { padding: 24px; }
</style>

普通 Vue3 将 lang="uts" 改为 lang="ts"，组件导入后缀改为 .vue，并为 .page 补充 display: flex; flex-direction: column; height: 100vh;，使锁组件占满页面。Vapor 与 VDOM 共用 .uvue。

将真实数据请求放进受保护的业务子组件，在它挂载后加载；锁定和隐藏时子组件会卸载。不要在锁组件外提前展示敏感资料。宽限期恢复只恢复内容，不再次发出 unlocked 事件，因此业务子组件应能重新挂载和加载。

锁组件参数与事件

锁定状态只保存在当前组件内，不持久化认证结果。重新进入页面、重建组件或重启 App 都要重新验证。模式、宽限配置改变会重新锁定，不复用原策略下的结果。

保护范围：组件保护包裹的页面内容，不自动接管未包裹的路由、后台接口或所有原生弹窗。Android 安全窗口会限制当前 Activity 的截图和最近任务捕获，只要受保护页面的组件仍挂载，隐藏到导航栈中也会继续保持安全窗口；最后一个组件卸载或显式关闭保护后，恢复插件添加的标记。iOS 使用原生遮挡层保护进入后台时的窗口预览，不承诺阻止前台截图。页面锁不等于加密存储或服务器鉴权。

系统认证 API

直接调用 setBiometricPrivacy 时，为每个使用方提供唯一且非空的 ownerId，显示受保护内容前开启，内容卸载后成对释放。iOS 从真实后台返回时，先完成锁定或隐藏内容的渲染，再在 nextTick 中用同一个 owner 再次调用 true，确认可以移除原生遮挡；遗漏确认会继续遮挡。通常直接使用锁组件即可。

AuthenticateOptions：

AuthenticateResult 包含 ok、platform、authType、requestedMode、requestId、errCode、nativeErrCode、errorType、canRetry、errMsg、note、fallbackUsed、fallbackKnown。fallbackKnown=false 表示系统未公开本次实际方式，不能据此认定用了指纹或面容。

BiometricStatus 包含 supported、enrolled、available、biometryType、deviceCredentialSupported、faceIdPermissionDeclared、platform、错误信息和 recommendedAction。enrolled=false 且错误不是 not_enrolled 时，可能只是无法预查询，最终以认证回调为准。BiometricActionResult 为 ok、platform、action、errCode、errMsg。

Android 6～9（API 23～28）仅支持本插件的生物识别策略；允许设备密码的策略返回不支持，Android 10+ 才可使用。iOS 的混合策略和 Android 10 不一定公开本次实际认证方式，Android 11+ 按系统公开结果返回。不能强制指定只用人脸、只用指纹或直接弹出密码。

iOS 设置跳转只打开当前 App 设置；录入 Face ID / Touch ID 需在系统设置中完成。ok=true 仅表示提交了跳转请求。

错误处理