4. 使用状态提升实现输入框组件：TextField的value和onValueChange

Compose 中的 TextField 是一个无状态组件——它本身不保存输入文本，而是通过 状态提升 将数据与行为完全交由父组件控制。本章围绕 value 与 onValueChange 这一经典模式，讲清楚原理、实现流程、调试要点以及常见陷阱，确保你在实际项目中既能快速搭建输入控件，也能保证稳定性与可测试性。

4.1 原理：为什么需要状态提升

在 Compose 中，组件推荐使用 单向数据流：状态向下、事件向上。TextField 的 value 参数接收当前的输入文本，onValueChange 是一个回调，当用户输入时由组件触发，将新文本传递给父级。父级更新状态后，新的值再通过 value 传回组件，完成刷新。

这种模式带来三个关键好处：

• 单一可信源：输入文本仅存在于父级 State 中，避免多副本不一致。
• 可复用性：将输入逻辑与 UI 表现分离，同一 TextField 可以绑定任意数据源。
• 可测试性：可以轻松模拟 onValueChange 传参，验证状态变化。

4.2 实现流程

1. 声明状态：在可组合函数中用 remember { mutableStateOf("") } 保存输入文本。
2. 绑定 value：将状态值赋给 TextField 的 value 参数。
3. 处理变更：在 onValueChange 中调用状态更新函数（如 text = newText）。
4. 可选的格式校验：在更新前对 newText 做过滤、长度限制等。

@Composable
fun MyTextField() {
    var inputText by remember { mutableStateOf("") }

    TextField(
        value = inputText,
        onValueChange = { newText ->
            // 状态提升：只接收并传递新值
            inputText = newText
        },
        label = { Text("请输入内容") },
        modifier = Modifier.fillMaxWidth()
    )
}

4.3 高级用法：带过滤的输入框

利用 onValueChange 可以在状态更新前拦截并修改输入内容。例如限制只允许数字输入：

var phone by remember { mutableStateOf("") }

TextField(
    value = phone,
    onValueChange = { newValue ->
        // 只保留数字字符
        val digitsOnly = newValue.filter { it.isDigit() }
        if (digitsOnly.length <= 11) {
            phone = digitsOnly
        }
    },
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Phone)
)

4.4 调试与常见错误

4.5 性能与稳定性优化

1. 避免不必要的重组：将 TextField 用 remember 包裹其 modifier 和 label，或者使用 derivedStateOf 计算衍生值。
2. 使用 TextFieldValue：对于需要精确控制光标或选择范围的情况，用 TextFieldValue 代替纯字符串。
3. 延迟校验：把输入校验放到协程中通过 snapshotFlow 或 debounce 处理，避免每次按键都执行。
4. 状态提升边界：如果输入状态只在当前屏幕内使用，用 remember 即可；如果需要在不同屏幕间共享（如搜索），提升到 ViewModel 中使用 StateFlow。

4.6 状态提升数据流示意图

4.7 验证与部署检查清单

• ✅ value 绑定的是 mutableStateOf 或 StateFlow 等可观察状态，而非普通变量。
• ✅ onValueChange 中调用了状态更新函数（= 赋值或 .value = ...）。
• ✅ 对于中文/日文等 IME 输入，使用 TextFieldValue 避免光标异常。
• ✅ 避免在 onValueChange 中执行异步操作；如需校验，用 LaunchedEffect 或 snapshotFlow。
• ✅ 在 Preview 中检查 TextField 与 value 绑定是否正确。