Android Academy · 课时

TextField 与用户输入

Q: 「TextField 与用户输入」这节课中我会学到什么？

在 Compose 中捕获用户输入的文本 你通过在浏览器中直接运行的动手代码来练习 Android Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

在 Compose 中捕获用户输入的文本

TextField 与用户输入 是 CoddyKit 上的免费 Android Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Android Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Android Academy 课程共包含 4 节课。

获取用户输入

几乎每个真实应用都需要向用户询问一些信息：姓名、电子邮件或搜索查询。在 Jetpack Compose 中，用于输入文本的基础组件是 TextField。

在本课中，您将学习如何显示文本字段、读取用户输入的内容，以及让字段与应用的状态保持同步。这是构建任何表单的基础。

您的第一个 TextField

TextField 需要两项内容：用于显示当前文本的 value，以及用户输入时要执行操作的 onValueChange 回调。

Compose 采用声明式方式，因此字段不会保存自己的文本。您需要将文本保存在状态中，再将其传回字段。这种模式称为状态提升。

@Composable
fun NameField() {
    var name by remember { mutableStateOf("") }

    TextField(
        value = name,
        onValueChange = { name = it }
    )
}

值循环的工作方式

最重要的一点是：TextField 会准确显示您传递给 value 的内容。当用户按下按键时，Compose 会将新文本传递给 onValueChange。

您将新文本保存到状态中。
状态变化会触发重组。
字段会使用更新后的 value 重新绘制。

如果忘记在 onValueChange 中更新状态，字段看起来就会被冻结，因为 value 从未发生变化。

var name by remember { mutableStateOf("") }

TextField(
    value = name,
    onValueChange = { newText -> name = newText }
)

添加标签和占位符

一个没有任何提示的文本字段无法告诉用户应该输入什么。请添加 label（会浮动到字段上方）和 placeholder（字段为空时显示的提示）。

这些细节能让表单更容易理解。

var email by remember { mutableStateOf("") }

TextField(
    value = email,
    onValueChange = { email = it },
    label = { Text("Email") },
    placeholder = { Text("you@example.com") }
)

OutlinedTextField

Material Design 提供两种主要样式。TextField 具有填充背景，而 OutlinedTextField 会在字段周围绘制边框。两者使用相同的 API，因此切换非常简单。

轮廓字段在表单中很受欢迎，因为垂直堆叠时界面清晰易读。

var username by remember { mutableStateOf("") }

OutlinedTextField(
    value = username,
    onValueChange = { username = it },
    label = { Text("Username") },
    singleLine = true
)

前置图标和后置图标

您可以使用图标装饰字段。leadingIcon 显示在开头（非常适合搜索或电子邮件图标），trailingIcon 显示在末尾（通常用于清除按钮）。

图标能让用户一眼看出字段的用途。

var query by remember { mutableStateOf("") }

OutlinedTextField(
    value = query,
    onValueChange = { query = it },
    label = { Text("Search") },
    leadingIcon = {
        Icon(Icons.Default.Search, contentDescription = null)
    }
)

清除按钮

一种常见的用户体验模式是使用小写的“x”清除字段。请仅在字段中有文本时显示它，并使用 trailingIcon 插槽和 IconButton。

请注意，清除操作实际上只是将状态重新设置为空字符串。

var text by remember { mutableStateOf("") }

OutlinedTextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Note") },
    trailingIcon = {
        if (text.isNotEmpty()) {
            IconButton(onClick = { text = "" }) {
                Icon(Icons.Default.Clear, contentDescription = "Clear")
            }
        }
    }
)

单行与多行

默认情况下，TextField 可以扩展为多行。对于姓名或电子邮件等内容，请设置 singleLine = true，这样用户就无法插入换行符。

对于较长的备注，请保留多行模式，并可以使用 maxLines 限制高度。

var bio by remember { mutableStateOf("") }

OutlinedTextField(
    value = bio,
    onValueChange = { bio = it },
    label = { Text("Bio") },
    maxLines = 4
)

实时响应输入

由于文本状态由您管理，因此可以立即对其做出响应。一个典型例子是在字段下方显示实时字符数。

每次按键都会更新 text，从而同时对字段和下方的字符数进行重组。

var text by remember { mutableStateOf("") }

Column {
    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Tweet") }
    )
    Text("${text.length} / 280")
}

转换输入

有时，您可能希望先规范化用户输入的内容，再将其保存。在 onValueChange 中，您可以先转换新值。

这里会将用户名强制转换为小写并去除空格。由于整个循环由您控制，字段始终会显示清理后的版本。

var handle by remember { mutableStateOf("") }

OutlinedTextField(
    value = handle,
    onValueChange = { input ->
        handle = input.lowercase().filterNot { it.isWhitespace() }
    },
    label = { Text("Handle") },
    singleLine = true
)

纯 Kotlin：清理用户标识

上面的转换逻辑只是普通的 Kotlin 代码。您可以单独测试它，无需 Android。下面是独立运行的相同清理规则。

将这类逻辑保存在纯函数中，可以轻松进行单元测试。

fun cleanHandle(input: String): String =
    input.lowercase().filterNot { it.isWhitespace() }

fun main() {
    println(cleanHandle("  John Doe "))
    println(cleanHandle("ADA Lovelace"))
}

快速检查

如果 TextField 的 onValueChange 回调从未更新传递给 value 的状态，会发生什么？

回顾

现在您已经掌握了 Compose 中文本输入的核心知识：

TextField 和 OutlinedTextField 接收 value 和 onValueChange 回调。
您可以使用 remember { mutableStateOf(...) } 保存文本，并在每次变化时更新它（状态提升）。
label、placeholder、前置/后置图标和 singleLine 可以调整外观和行为。
由于状态由您管理，因此可以实时响应输入，也可以在用户输入时转换内容。

下一步：管理整个表单的状态，而不只是一个字段。

常见问题解答

「TextField 与用户输入」课时是免费的吗？

是的 — 「TextField 与用户输入」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Android Academy 课程的其余内容，请升级到 CoddyKit PRO。 Android Academy 课程共包含 4 节课。

「TextField 与用户输入」这节课中我会学到什么？

在 Compose 中捕获用户输入的文本你通过在浏览器中直接运行的动手代码来练习 Android Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Android Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Android Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「TextField 与用户输入」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Android Academy 课中编写并运行代码吗？

能。每节 Android Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Android Academy