第4章 基础密码输入框实现：OutlinedTextField + passwordVisualTransformation + 键盘类型

原理

密码输入框的核心需求是在用户键入时隐藏真实字符，同时保留已输入内容的长度信息。Jetpack Compose 通过 Data Binding 与 VisualTransformation 分离实现了这一机制：OutlinedTextField 提供 Material Design 带边框文本框的 UI 骨架，passwordVisualTransformation() 作为视觉转换器将每个字符替换为圆点（•），键盘类型（KeyboardType.Password 与 KeyboardActions）确保软键盘不显示明文预测、不存储敏感词。

三者的协作关系：Compose 将 TextField 内部维护的 VisualTransformation 应用到显示层的字符序列，而底层状态（mutableStateOf 存储的 value）始终保留原始明文。这也意味着密码文本在内存中仍为明文，仅 UI 层被蒙版。

实现流程

1. 在 Composable 作用域内声明 var password by remember { mutableStateOf("") }。
2. 配置 OutlinedTextField 的 visualTransformation = passwordVisualTransformation()。
3. 设置 keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)。
4. 选配 keyboardActions = KeyboardActions(onDone = { … }) 处理输入完成事件。
5. 添加 leadingIcon / trailingIcon 装饰（如眼型图标切换可见性，本案例后续章节扩展）。
6. 绑定值：value = password, onValueChange = { password = it }。

核心代码

以下是一个完整的可运行示例，包含了备忘录状态的密码输入框（不含明文切换开关），演示最简安全密码输入实现。

@Composable
fun BasicPasswordField(
    label: String = "密码",
    onPasswordChanged: (String) -> Unit = {}
) {
    var password by remember { mutableStateOf("") }
    OutlinedTextField(
        value = password,
        onValueChange = { newValue ->
            password = newValue
            onPasswordChanged(newValue)
        },
        label = { Text(label) },
        visualTransformation = passwordVisualTransformation(),
        keyboardOptions = KeyboardOptions(
            keyboardType = KeyboardType.Password,
            imeAction = ImeAction.Done
        ),
        keyboardActions = KeyboardActions(
            onDone = { /* 可执行登录/提交动作 */ }
        ),
        singleLine = true,
        modifier = Modifier.fillMaxWidth()
    )
}

在调用方使用时，只需传入回调即可获得实时密码明文：BasicPasswordField(onPasswordChanged = { println("密码: $it") })。

关键 API 与参数对照

调试部署

• 验证显示：输入任意字符，观察是否全部显示为“•”。若出现明文，检查是否遗漏 visualTransformation 或赋予了 TextFieldValue 中的自定义转型。
• 验证键盘：激活输入框后，确认软键盘不展示预测栏，且“回车”键显示为“完成”或“搜索”等非“换行”按钮。若键盘仍显示预测，检查 keyboardType 是否被嵌套的 BasicTextField 覆盖。
• 获取明文：在 onValueChange 或外部回调中打印 password 变量，确认收到的确实是真实字符而非“•”。这是验证显示/数据分离的关键。
• 部署环境：最低 API Level 建议 21+（Android 5.0），Compose BOM 版本 ≥ 2024.01.00。模拟器与真机行为一致，但部分国产定制 ROM 可能改变键盘行为，需真机回归。

常见错误

1. 忘记 remember 状态：直接 var password = "" 会导致每次重组时状态重置，输入丢失。必须使用 remember { mutableStateOf("") }。
2. 误用键盘类型：将 keyboardType = KeyboardType.Text 或 Number 会导致键盘显示预测，残留密码片段。应使用 Password。
3. visualTransformation 与 TextFieldValue 冲突：若使用 TextFieldValue 作为状态，并手动设置 visualTransformation，需确保 TextFieldValue 的 visualTransformation 字段未被覆盖。通常推荐直接使用 String 状态。
4. IMEAction 不触发：键盘动作依赖于 keyboardActions 参数的注册；若未提供，点击“完成”无响应。但基础密码框可以省略，不影响密码输入功能。
5. 密码长度检验：部分开发者误以为 passwordVisualTransformation 会自动截断或校验长度——它只改显示，不限制输入。应在 onValueChange 内手动 bound。

性能与稳定性优化

• 内存：密码状态存活于 remember 块，若 Composable 从组合中移除，状态会自动 GC。但建议在页面销毁时主动置空，尤其对于金融类 App。
• 稳定性：使用 rememberSaveable 替代 remember 可以保留输入框状态跨配置变更（如屏幕旋转），但注意密码会保留在保存归档中（存在泄露风险）。若强度要求高，应采取 remember + 配置变更时重建。
• 无障碍：视觉转换后的密码输入框对屏幕阅读器不友好——TalkBack 默认不会朗读每个圆点，但会读出“密码，文本，结束”。可为 modifier.semantics 增加自定义描述。