如何在Jetpack Compose BasicTextField中实现固定前缀的自定义掩码输入

核心问题分析 #

你原来的代码存在两个关键问题：

1. 直接替换TextFieldValue的文本但未重新计算光标位置，导致光标错位
2. 未处理用户删除固定前缀的情况，也没有限制输入长度

实现步骤 #

1. 固定前缀保护 #

确保输入框始终保留"ABC-"前缀，用户无法删除或修改这部分内容：

• 检查输入文本是否以前缀开头，若不是则直接过滤数字重新构建
• 光标在前缀范围内时，强制将光标定位到前缀末尾

2. 输入过滤与掩码格式化 #

• 只保留用户输入的数字，限制最多12位（对应3组4位的掩码格式）
• 自动在每4位数字后插入横杠，构建ABC-XXXX-XXXX-XXXX格式的文本

3. 光标位置正确映射 #

通过calculateCursorPosition函数，将用户原始的光标位置转换为格式化后的正确位置：

• 处理前缀范围内的光标定位
• 计算有效数字的光标位置，再加上插入的横杠数量得到最终位置

完整代码 #

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.text.BasicTextField
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.TextRange
import androidx.compose.ui.text.input.TextFieldValue
import androidx.compose.ui.tooling.preview.Preview

@Preview(showBackground = true)
@Composable
private fun SampleTextFieldView() {
    var textFieldValue by remember { mutableStateOf(TextFieldValue("ABC-")) }
    BasicFieldView(
        textFieldValue = textFieldValue,
        onValueChange = { newValue ->
            val prefix = "ABC-"
            // 提取前缀后的文本，确保前缀不被删除
            val rawText = if (newValue.text.startsWith(prefix)) {
                newValue.text.substring(prefix.length)
            } else {
                newValue.text.filter { it.isDigit() }
            }
            // 过滤数字并限制最多12位
            val filteredDigits = rawText.filter { it.isDigit() }.take(12)
            // 构建格式化文本
            val formattedText = buildString {
                append(prefix)
                filteredDigits.forEachIndexed { index, digit ->
                    if (index > 0 && index % 4 == 0) {
                        append("-")
                    }
                    append(digit)
                }
            }
            // 计算正确的光标位置
            val cursorPosition = calculateCursorPosition(
                originalCursor = newValue.selection.start,
                prefixLength = prefix.length,
                filteredDigits = filteredDigits,
                rawText = rawText
            )
            // 更新TextFieldValue
            textFieldValue = TextFieldValue(
                text = formattedText,
                selection = TextRange(cursorPosition)
            )
        }
    )
}

@Composable
fun BasicFieldView(
    textFieldValue: TextFieldValue,
    onValueChange: (TextFieldValue) -> Unit,
) {
    Column(modifier = Modifier.fillMaxSize()) {
        BasicTextField(
            modifier = Modifier.fillMaxWidth(),
            value = textFieldValue,
            onValueChange = onValueChange,
            decorationBox = { innerTextField ->
                // 可按需添加提示文本，示例：
                // if (textFieldValue.text == "ABC-") {
                //     Text("输入12位数字", color = Color.Gray)
                // }
                innerTextField()
            }
        )
    }
}

private fun calculateCursorPosition(
    originalCursor: Int,
    prefixLength: Int,
    filteredDigits: String,
    rawText: String
): Int {
    // 光标在前缀区域，直接定位到前缀末尾
    if (originalCursor <= prefixLength) {
        return prefixLength
    }
    // 计算用户在前缀后文本中的相对光标位置
    val relativeCursor = originalCursor - prefixLength
    // 统计用户光标前的有效数字数量
    var validDigitCount = 0
    for (i in 0 until minOf(relativeCursor, rawText.length)) {
        if (rawText[i].isDigit()) {
            validDigitCount++
        }
    }
    // 计算格式化后文本中的光标位置：前缀长度 + 有效数字数 + 插入的横杠数
    val dashCount = if (validDigitCount == 0) 0 else (validDigitCount - 1) / 4
    return prefixLength + validDigitCount + dashCount
}

代码说明 #

• 前缀保护：无论用户如何操作，输入框始终保留"ABC-"前缀，若用户尝试删除前缀，会自动恢复
• 输入限制：只允许输入数字，最多12位，超过部分会被截断
• 光标修复：通过计算有效数字位置和横杠数量，确保光标始终处于正确位置，退格操作也不会错位
• 可扩展性：如果需要修改前缀或掩码格式，只需调整prefix变量和格式化逻辑即可

内容的提问来源于stack exchange，提问作者Compose Learner