此页面由 Cloud Translation API 翻译。

迁移到基于状态的文本字段
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

本页提供了一些示例，说明如何将基于值的 TextField 迁移到基于状态的 TextField。如需了解基于值和基于状态的 TextField 之间的区别，请参阅配置文本字段页面。

基本用法

基于价值

@Composable
fun OldSimpleTextField() {
    var state by rememberSaveable { mutableStateOf("") }
    TextField(
        value = state,
        onValueChange = { state = it },
        singleLine = true,
    )
}TextFieldMigrationSnippets.kt

基于状态

@Composable
fun NewSimpleTextField() {
    TextField(
        state = rememberTextFieldState(),
        lineLimits = TextFieldLineLimits.SingleLine
    )
}TextFieldMigrationSnippets.kt

将 value, onValueChange 和 remember { mutableStateOf("") } 替换为 rememberTextFieldState()。
将 singleLine = true 替换为 lineLimits = TextFieldLineLimits.SingleLine。

通过 `onValueChange` 过滤

基于价值

@Composable
fun OldNoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}TextFieldMigrationSnippets.kt

基于状态

@Preview
@Composable
fun NewNoLeadingZeros() {
    TextField(
        state = rememberTextFieldState(),
        inputTransformation = InputTransformation {
            while (length > 0 && charAt(0) == '0') delete(0, 1)
        }
    )
}TextFieldMigrationSnippets.kt

将值回调循环替换为 rememberTextFieldState()。
使用 InputTransformation 在 onValueChange 中重新实现过滤逻辑。
使用 InputTransformation 的接收器作用域中的 TextFieldBuffer 更新 state。
- 系统会在检测到用户输入后立即调用 InputTransformation。
- InputTransformation 通过 TextFieldBuffer 提出的更改会立即应用，从而避免软件键盘和 TextField 之间出现同步问题。

信用卡格式设置工具 `TextField`

基于价值

@Composable
fun OldTextFieldCreditCardFormatter() {
    var state by remember { mutableStateOf("") }
    TextField(
        value = state,
        onValueChange = { if (it.length <= 16) state = it },
        visualTransformation = VisualTransformation { text ->
            // Making XXXX-XXXX-XXXX-XXXX string.
            var out = ""
            for (i in text.indices) {
                out += text[i]
                if (i % 4 == 3 && i != 15) out += "-"
            }

            TransformedText(
                text = AnnotatedString(out),
                offsetMapping = object : OffsetMapping {
                    override fun originalToTransformed(offset: Int): Int {
                        if (offset <= 3) return offset
                        if (offset <= 7) return offset + 1
                        if (offset <= 11) return offset + 2
                        if (offset <= 16) return offset + 3
                        return 19
                    }

                    override fun transformedToOriginal(offset: Int): Int {
                        if (offset <= 4) return offset
                        if (offset <= 9) return offset - 1
                        if (offset <= 14) return offset - 2
                        if (offset <= 19) return offset - 3
                        return 16
                    }
                }
            )
        }
    )
}TextFieldMigrationSnippets.kt

基于状态

@Composable
fun NewTextFieldCreditCardFormatter() {
    val state = rememberTextFieldState()
    TextField(
        state = state,
        inputTransformation = InputTransformation.maxLength(16),
        outputTransformation = OutputTransformation {
            if (length > 4) insert(4, "-")
            if (length > 9) insert(9, "-")
            if (length > 14) insert(14, "-")
        },
    )
}TextFieldMigrationSnippets.kt

将 onValueChange 中的过滤替换为 InputTransformation，以设置输入的最大长度。
- 请参阅通过 onValueChange 过滤部分。
将 VisualTransformation 替换为 OutputTransformation 以添加短划线。
- 使用 VisualTransformation 时，您负责使用短划线创建新文本，并计算索引如何在视觉文本和后备状态之间映射。
- OutputTransformation 会自动处理偏移量映射。您只需使用 OutputTransformation.transformOutput 接收器作用域中的 TextFieldBuffer 在正确的位置添加短划线即可。

更新状态（简单）

基于价值

@Composable
fun OldTextFieldStateUpdate(userRepository: UserRepository) {
    var username by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        username = userRepository.fetchUsername()
    }
    TextField(
        value = username,
        onValueChange = { username = it }
    )
}TextFieldMigrationSnippets.kt

基于状态

@Composable
fun NewTextFieldStateUpdate(userRepository: UserRepository) {
    val usernameState = rememberTextFieldState()
    LaunchedEffect(Unit) {
        usernameState.setTextAndPlaceCursorAtEnd(userRepository.fetchUsername())
    }
    TextField(state = usernameState)
}TextFieldMigrationSnippets.kt

将值回调循环替换为 rememberTextFieldState()。
使用 TextFieldState.setTextAndPlaceCursorAtEnd 更改值赋值。

更新状态（复杂）

基于价值

@Composable
fun OldTextFieldAddMarkdownEmphasis() {
    var markdownState by remember { mutableStateOf(TextFieldValue()) }
    Button(onClick = {
        // add ** decorations around the current selection, also preserve the selection
        markdownState = with(markdownState) {
            copy(
                text = buildString {
                    append(text.take(selection.min))
                    append("**")
                    append(text.substring(selection))
                    append("**")
                    append(text.drop(selection.max))
                },
                selection = TextRange(selection.min + 2, selection.max + 2)
            )
        }
    }) {
        Text("Bold")
    }
    TextField(
        value = markdownState,
        onValueChange = { markdownState = it },
        maxLines = 10
    )
}TextFieldMigrationSnippets.kt

基于状态

@Composable
fun NewTextFieldAddMarkdownEmphasis() {
    val markdownState = rememberTextFieldState()
    LaunchedEffect(Unit) {
        // add ** decorations around the current selection
        markdownState.edit {
            insert(originalSelection.max, "**")
            insert(originalSelection.min, "**")
            selection = TextRange(originalSelection.min + 2, originalSelection.max + 2)
        }
    }
    TextField(
        state = markdownState,
        lineLimits = TextFieldLineLimits.MultiLine(1, 10)
    )
}TextFieldMigrationSnippets.kt

在此用例中，一个按钮会添加 Markdown 装饰，以粗体显示光标或当前所选区域周围的文本。它还会在更改后保留选择位置。

将值回调循环替换为 rememberTextFieldState()。
将 maxLines = 10 替换为 lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 10)。
使用 TextFieldState.edit 调用更改计算新 TextFieldValue 的逻辑。
- 系统会根据当前选择的内容拼接现有文本，并在其中插入 Markdown 装饰，从而生成新的 TextFieldValue。
- 此外，选择范围也会根据文本的新索引进行调整。
- TextFieldState.edit 可以使用 TextFieldBuffer 以更自然的方式修改当前状态。
- 选择明确定义了要插入装饰的位置。
- 然后，调整选择，类似于 onValueChange 方法。

ViewModel `StateFlow` 架构

许多应用都遵循现代应用开发指南，该指南提倡使用 StateFlow 通过包含所有信息的单个不可变类来定义屏幕或组件的界面状态。

在这些类型的应用中，包含文本输入的登录界面等表单通常设计如下：

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState>
        get() = _uiState.asStateFlow()

    fun updateUsername(username: String) = _uiState.update { it.copy(username = username) }

    fun updatePassword(password: String) = _uiState.update { it.copy(password = password) }
}

data class UiState(
    val username: String = "",
    val password: String = ""
)

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    val uiState by loginViewModel.uiState.collectAsStateWithLifecycle()
    Column(modifier) {
        TextField(
            value = uiState.username,
            onValueChange = { loginViewModel.updateUsername(it) }
        )
        TextField(
            value = uiState.password,
            onValueChange = { loginViewModel.updatePassword(it) },
            visualTransformation = PasswordVisualTransformation()
        )
    }
}TextFieldMigrationSnippets.kt

这种设计非常适合使用 value, onValueChange 状态提升范式的 TextFields。不过，在文本输入方面，这种方法存在不可预知的缺点。Compose 中 TextField 的有效状态管理博文详细介绍了此方法的深层同步问题。

问题在于，新 TextFieldState 设计与 StateFlow 支持的 ViewModel 界面状态不直接兼容。将 username: String 和 password: String 替换为 username: TextFieldState 和 password: TextFieldState 可能看起来很奇怪，因为 TextFieldState 本质上就是可变数据结构。

常见的建议是避免将界面依赖项放入 ViewModel。虽然这通常是一种良好做法，但有时可能会被误解。对于纯粹的数据结构且不带有任何界面元素的 Compose 依赖项（例如 TextFieldState），这一点尤为重要。

MutableState 或 TextFieldState 等类是简单的状态容器，由 Compose 的 Snapshot 状态系统提供支持。它们与 StateFlow 或 RxJava 等依赖项没有区别。因此，我们建议您重新评估如何在代码中应用“ViewModel 中不得有界面依赖项”原则。在 ViewModel 中保留对 TextFieldState 的引用本身并不是一个坏做法。

建议采用的简单方法

我们建议您从 UiState 中提取 username 或 password 等值，并在 ViewModel 中为它们保留单独的引用。

class LoginViewModel : ViewModel() {
    val usernameState = TextFieldState()
    val passwordState = TextFieldState()
}

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    Column(modifier) {
        TextField(state = loginViewModel.usernameState,)
        SecureTextField(state = loginViewModel.passwordState)
    }
}TextFieldMigrationSnippets.kt

将 MutableStateFlow<UiState> 替换为几个 TextFieldState 值。
将这些 TextFieldState 对象传递给 LoginForm 可组合项中的 TextFields。

合规方法

这类架构变更并不总是轻而易举。您可能无法自由进行这些更改，或者所需的时间可能超过使用新 TextField 的好处。在这种情况下，您仍然可以通过稍作调整来使用基于状态的文本字段。

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState>
        get() = _uiState.asStateFlow()

    fun updateUsername(username: String) = _uiState.update { it.copy(username = username) }

    fun updatePassword(password: String) = _uiState.update { it.copy(password = password) }
}

data class UiState(
    val username: String = "",
    val password: String = ""
)

@Composable
fun LoginForm(
    loginViewModel: LoginViewModel,
    modifier: Modifier = Modifier
) {
    val initialUiState = remember(loginViewModel) { loginViewModel.uiState.value }
    Column(modifier) {
        val usernameState = rememberTextFieldState(initialUiState.username)
        LaunchedEffect(usernameState) {
            snapshotFlow { usernameState.text.toString() }.collectLatest {
                loginViewModel.updateUsername(it)
            }
        }
        TextField(usernameState)

        val passwordState = rememberTextFieldState(initialUiState.password)
        LaunchedEffect(usernameState) {
            snapshotFlow { usernameState.text.toString() }.collectLatest {
                loginViewModel.updatePassword(it)
            }
        }
        SecureTextField(passwordState)
    }
}TextFieldMigrationSnippets.kt

让 ViewModel 和 UiState 类保持不变。
请勿将状态直接提升到 ViewModel 并将其作为 TextFields 的可信来源，而是将 ViewModel 转换为简单的数据容器。
- 为此，请在 LaunchedEffect 中收集 snapshotFlow，以观察每个 TextFieldState.text 的变化。
您的 ViewModel 仍会具有界面中的最新值，但其 uiState: StateFlow<UiState> 不会驱动 TextField。
在 ViewModel 中实现的任何其他持久性逻辑都可以保持不变。

迁移到基于状态的文本字段 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

基本用法

基于价值

基于状态

通过 onValueChange 过滤

基于价值

基于状态

信用卡格式设置工具 TextField

基于价值

基于状态

更新状态（简单）

基于价值

基于状态

更新状态（复杂）

基于价值

基于状态

ViewModel StateFlow 架构

建议采用的简单方法

合规方法

迁移到基于状态的文本字段
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

通过 `onValueChange` 过滤

信用卡格式设置工具 `TextField`

ViewModel `StateFlow` 架构