5、BiometricPrompt高级配置：设置认证标题、副标题、描述信息、取消按钮文本

好，咱们接着往下聊。上一节我们把BiometricPrompt的基本调用跑通了，但说实话，那个默认弹窗长得太素了——就一个系统图标加一行“请验证指纹”，用户体验上差点意思。今天我来教你怎么给它“化妆”。

说白了，BiometricPrompt的构造函数里有一个BiometricPrompt.PromptInfo对象，这个对象就是用来配置弹窗上所有文字内容的。标题、副标题、描述、取消按钮，全在这里面搞定。

5.1 PromptInfo.Builder：弹窗的“装修队”

先看一段最基础的配置代码，我习惯把这块单独抽成一个方法：

private BiometricPrompt.PromptInfo buildPromptInfo() {
    return new BiometricPrompt.PromptInfo.Builder()
            .setTitle("虹膜验证")
            .setSubtitle("请将眼睛对准屏幕上方")
            .setDescription("系统将使用虹膜识别验证您的身份")
            .setNegativeButtonText("取消")
            .build();
}

嗯，就这么几行。但你别小看它，每个字段都有讲究。我在项目里踩过坑，一个一个跟你说。

5.2 标题（setTitle）：别超过15个字

标题是弹窗里最显眼的文字，系统会加粗显示。我个人建议控制在10-15个汉字以内，太长会被截断。比如“虹膜验证”四个字就挺好，简洁有力。

避坑指南：我曾经在某个项目里写了“请进行虹膜识别以完成身份验证”，结果在部分国产手机上标题被截成了“请进行虹膜识别以完成身...”，后面三个点，用户看了莫名其妙。后来我统一改成“身份验证”或“虹膜验证”，再也没出过问题。

5.3 副标题（setSubtitle）：补充说明的好地方

副标题在标题下方，字号小一号，颜色也淡一些。这里适合写操作指引，比如“请将眼睛对准屏幕上方”或者“请摘下眼镜/美瞳”。

你想想看，用户第一次用虹膜识别，根本不知道眼睛该往哪放。副标题就是干这个的——告诉用户具体动作。

5.4 描述信息（setDescription）：详细说明区

描述信息是弹窗里最长的文本区域，可以写2-3行。这里适合放安全提示或操作细节，比如：

• “系统将使用虹膜识别验证您的身份”
• “请确保光线充足，眼睛与屏幕距离30-40厘米”
• “虹膜数据仅存储在设备本地，不会上传至服务器”

我个人建议描述信息不要超过50个字。写太多用户根本不会看，反而增加了弹窗高度，显得臃肿。

5.5 取消按钮（setNegativeButtonText）：必须设置

这个字段是必填项，不设置会直接崩溃。为什么？因为Android系统要求生物识别弹窗必须给用户一个取消的途径。

我曾经在测试阶段忘了设这个，结果一调用BiometricPrompt就闪退，日志里报IllegalArgumentException。查了半天才发现是取消按钮文本没写。

5.6 完整配置示例

把上面这些串起来，一个完整的配置大概是这样的：

private void showBiometricPrompt() {
    BiometricPrompt.PromptInfo promptInfo = new BiometricPrompt.PromptInfo.Builder()
            .setTitle("虹膜验证")
            .setSubtitle("请将眼睛对准屏幕上方")
            .setDescription("系统将使用虹膜识别验证您的身份。\n请确保光线充足，眼睛与屏幕距离30-40厘米。")
            .setNegativeButtonText("取消")
            .build();

    BiometricPrompt biometricPrompt = new BiometricPrompt(
            this,
            Executors.newSingleThreadExecutor(),
            new BiometricPrompt.AuthenticationCallback() {
                @Override
                public void onAuthenticationSucceeded(@NonNull BiometricPrompt.AuthenticationResult result) {
                    super.onAuthenticationSucceeded(result);
                    runOnUiThread(() -> Toast.makeText(MainActivity.this, "验证成功", Toast.LENGTH_SHORT).show());
                }

                @Override
                public void onAuthenticationFailed() {
                    super.onAuthenticationFailed();
                    runOnUiThread(() -> Toast.makeText(MainActivity.this, "验证失败，请重试", Toast.LENGTH_SHORT).show());
                }

                @Override
                public void onAuthenticationError(int errorCode, @NonNull CharSequence errString) {
                    super.onAuthenticationError(errorCode, errString);
                    runOnUiThread(() -> Toast.makeText(MainActivity.this, "错误: " + errString, Toast.LENGTH_SHORT).show());
                }
            }
    );

    biometricPrompt.authenticate(promptInfo);
}

5.7 各字段长度建议汇总

为了方便你快速参考，我整理了一张表：

字段	建议字数	示例	是否必填
标题	10-15字	“虹膜验证”	是
副标题	15-20字	“请将眼睛对准屏幕上方”	否
描述信息	30-50字	“系统将使用虹膜识别验证您的身份”	否
取消按钮	2-4字	“取消”	是

5.8 知识体系图

下面这张图帮你理清PromptInfo的配置结构：

5.9 我踩过的坑：取消按钮文本的“隐形陷阱”

最后再分享一个真实案例。有一次我写了个功能，取消按钮文本设成了“使用密码”，想着给用户多一个选择。结果测试反馈说点击“使用密码”后没反应。

查了半天才发现，setNegativeButtonText()只是显示文本，真正的点击逻辑要在AuthenticationCallback的onAuthenticationError()里处理——当用户点击取消按钮时，系统会回调onAuthenticationError()，错误码是BiometricPrompt.ERROR_NEGATIVE_BUTTON。

所以如果你想让取消按钮做点别的事，记得在回调里判断错误码：

@Override
public void onAuthenticationError(int errorCode, @NonNull CharSequence errString) {
    if (errorCode == BiometricPrompt.ERROR_NEGATIVE_BUTTON) {
        // 用户点击了取消按钮，可以跳转到密码输入页面
        startActivity(new Intent(MainActivity.this, PasswordActivity.class));
    } else {
        // 其他错误
        Toast.makeText(MainActivity.this, "错误: " + errString, Toast.LENGTH_SHORT).show();
    }
}

嗯，这个坑我印象特别深，因为当时被测试小姐姐追着改了三版才搞定。你提前知道就好，别走我的老路。

---

公众号:蓝海资料掘金营，微信deep3321