这次我们来看 Jetpack Compose 里最常用的三个交互组件输入框、按钮、Snackbar。这是“Jetpack Compose 安卓声明式 UI 开发”系列的第 7 篇主题很聚焦但内容并不浅。Compose 已经成了 Android 官方主推的 UI 开发方式如果你还在用 XML 写界面、findViewById 找控件那这一篇建议认真读完。文章会把三个组件的用法、状态管理方式、组合联动都过一遍最后给出一个可以直接运行的登录表单示例放进 Android Studio 就能跑。你会看到声明式 UI 和传统 View 系统的最大区别输入框的值存哪、按钮状态怎么变、Snackbar 怎么弹全部由状态驱动没有 findViewById没有 setText没有 show() 这样到处飞的操作。从门槛来看你只需要具备 Android Studio 基础使用经验、一点 Kotlin 语法以及一个模拟器或真机。不需要额外购买任何东西官方依赖拉下来就能写。下面直接进入正文。1. 核心能力速览先用一张表快速看清本次内容覆盖的范围能力项说明技术类型Android 声明式 UI 开发框架组件核心组件TextField / OutlinedTextField、Button 按钮族、Snackbar依赖方式Gradle 引入 Compose BOM 与 Material 3运行环境Android Studio Kotlin Android SDKAPI 21状态管理remember、mutableStateOf、状态提升事件回调onValueChange、onClick、SnackbarHostState.showSnackbar()视觉规范Material Design 3 自动适配主题是否支持预览支持 Preview 静态预览适用对象从 XML 转向 Compose 的 Android 开发者是否支持批量状态联动支持通过状态提升统一管理多个输入框从材料来看这个系列属于“搬运 中文讲解”的教程形式核心价值是把 Compose 官方思路用中文系统地拆解出来。本文不重复搬运原视频重点把输入框、按钮、Snackbar 的工程化用法和常见坑位重新整理成博客的形式方便你作为手册查阅。2. 适用场景与使用边界先说实话这三个组件是 Compose 应用里出现频率最高的组合之一。登录页、注册页、设置页、搜索栏、消息反馈几乎每一个需要用户操作的界面都离不开它们。适合解决的场景表单类页面用户名、密码、手机号等输入场景。操作入口登录按钮、提交按钮、次级操作按钮。轻量反馈操作成功、失败提示、撤销入口、网络异常提示。不适合的场景需要长时间驻留、用户必须确认的系统级提示优先考虑 Dialog 或 Notification而不是 Snackbar。复杂富文本编辑、代码编辑器类输入Compose 基础 TextField 会吃力需要引入专用编辑器组件。追求极致输入性能、需要接入 IME 自定义键盘的大规模文本处理场景需要评估 Compose 的适配上限。关于边界有一点务必注意输入框天然涉及用户数据。如果应用采集手机号、验证码、用户名、搜索关键词必须在隐私政策里明确说明用途不能把用户输入内容写入本地明文日志更不能在未授权情况下上传到第三方服务。作为开发者写 Demo 自己测试没问题一旦上架或商用输入内容的处理和存储都需要合规。3. 环境准备与前置条件Compose 项目的环境准备并不复杂但依赖版本匹配是新手最常踩坑的地方。前置条件清单Android Studio 最新稳定版建议直接使用自带 JDK 的版本。Android SDK建议 API 33 或更高Compose 最低支持 API 21。一个模拟器或真机。模拟器推荐使用 Pixel 系列镜像真机开启开发者选项和 USB 调试。Kotlin 基础。至少要知道var、val、lambda 表达式、协程的基本概念。在 Android Studio 新建项目时直接选择 Empty Activity 模板模板会自动生成 Compose 相关配置。如果你是从现有项目接入 Compose需要在build.gradle.kts模块级中补充如下依赖dependencies { val composeBom platform(androidx.compose:compose-bom:2024.06.00) implementation(composeBom) implementation(androidx.compose.ui:ui) implementation(androidx.compose.material3:material3) implementation(androidx.compose.ui:ui-tooling-preview) debugImplementation(androidx.compose.ui:ui-tooling) implementation(androidx.activity:activity-compose:1.9.0) }版本号需要按你本机实际可用版本调整。新版 Android Studio 模板默认使用 Version Cataloglibs.versions.toml管理版本如果你看到的是libs.compose.material3这样的引用不需要重写成上面这种硬编码形式两种方式等价。还要确认项目启用了 Kotlin Compose 编译插件。如果是新版模板plugins块里一般会自动带上plugins { id(com.android.application) id(org.jetbrains.kotlin.android) id(org.jetbrains.kotlin.plugin.compose) }这三个插件缺一不可。尤其是org.jetbrains.kotlin.plugin.compose不配置的话Compose 编译器无法正常工作运行时会直接报错或界面不渲染。4. 声明式 UI 核心概念在写输入框之前必须先理解 Compose 的状态驱动模型。这个模型可以用一句话概括UI f(state)界面是状态的函数。状态变化时Compose 自动重新执行对应的 composable 函数界面随之更新。你不需要手动调用setText或notifyDataSetChanged。先看一个最小示例。一个普通的计数按钮Composable fun Counter() { var count by remember { mutableStateOf(0) } Button(onClick { count }) { Text(点击次数: $count) } }这里有几个关键点remember用来保存状态避免重组时被重置。mutableStateOf(0)创建了一个可观察状态。by委托语法让count的读写直接映射到MutableState。按钮点击时修改countCompose 自动重组Button内部内容界面上的文字就会更新。这个模型和传统 View 系统完全不同。传统方式是你主动找控件、改控件Compose 是你改状态框架负责刷新界面。理解这一点后再看输入框就非常顺了。输入框的值不是控件内部私有的而是由外部状态决定用户输入触发回调你更新状态状态再驱动输入框显示新内容。这就是所谓的“状态提升”。5. 输入框组件详解TextField 与 OutlinedTextField5.1 基础用法Jetpack Compose 提供两个最常用的输入框组件TextField默认填充样式。OutlinedTextField带边框样式。两者的核心参数完全一致区别只在视觉。实际项目中OutlinedTextField使用频率更高因为默认形态更容易看出输入区域边界。最小可运行的输入框Composable fun SimpleInput() { var text by remember { mutableStateOf() } OutlinedTextField( value text, onValueChange { text it }, label { Text(用户名) }, placeholder { Text(请输入用户名) } ) }重点看value和onValueChangevalue是输入框当前显示的内容完全由外部状态控制。onValueChange是用户输入变化时的回调新值通过it返回。如果你只写了value而不更新状态输入框会表现为“无法输入”。这是 Compose 新手最常犯的错误。5.2 密码输入框密码框需要做两件事隐藏输入内容和切换可见性。Composable fun PasswordInput() { var password by remember { mutableStateOf() } var visible by remember { mutableStateOf(false) } OutlinedTextField( value password, onValueChange { password it }, label { Text(密码) }, visualTransformation if (visible) { VisualTransformation.None } else { PasswordVisualTransformation() }, trailingIcon { TextButton(onClick { visible !visible }) { Text(if (visible) 隐藏 else 显示) } } ) }visualTransformation控制输入内容的显示方式。传PasswordVisualTransformation()时内容会变成掩码传VisualTransformation.None时显示明文。trailingIcon是输入框右侧的附加区域可以放图标或文字按钮。5.3 数字输入与键盘类型如果输入内容限定为数字比如年龄、验证码可以通过keyboardOptions指定键盘类型import androidx.compose.foundation.text.KeyboardOptions import androidx.compose.ui.text.input.KeyboardType OutlinedTextField( value code, onValueChange { newValue - if (newValue.length 6 newValue.all { it.isDigit() }) { code newValue } }, label { Text(验证码) }, keyboardOptions KeyboardOptions(keyboardType KeyboardType.Number) )这里做了两层控制keyboardOptions控制软键盘类型为数字键盘。onValueChange里手动过滤非数字字符并限制最大长度。键盘类型只影响软键盘显示用户仍然可能粘贴非数字内容所以回调里的校验不能省略。5.4 错误提示与校验输入框内置isError参数配合supportingText可以显示错误信息Composable fun ValidatedInput() { var email by remember { mutableStateOf() } val isError email.isNotBlank() !android.util.Patterns.EMAIL_ADDRESS.matcher(email).matches() OutlinedTextField( value email, onValueChange { email it }, label { Text(邮箱) }, isError isError, supportingText { if (isError) { Text(邮箱格式不正确) } } ) }isError true时边框和提示文字会切换为主题指定的错误颜色。注意这里的校验逻辑不要写得过重尽量用轻量的正则或 SDK 自带工具避免在重组过程中执行耗时计算。6. 按钮组件详解Button 与 Material3 按钮族6.1 基础 ButtonMaterial 3 提供多种按钮样式按优先级排列组件用途视觉强调程度Button页面主操作高FilledTonalButton次主操作中OutlinedButton次要操作中低TextButton低优先级操作低最基础的使用Button( onClick { /* 处理点击 */ }, enabled true ) { Text(登录) }enabled为false时按钮置灰且不可点击这在表单校验场景中非常实用。6.2 表单提交按钮与 loading 状态实际开发中按钮经常需要展示“加载中”状态。Compose 没有内置的loading参数但可以自己组合常见做法是用CircularProgressIndicator替换按钮文字Composable fun LoginButton( loading: Boolean, onClick: () - Unit ) { Button( onClick onClick, enabled !loading ) { if (loading) { CircularProgressIndicator( modifier Modifier.size(20.dp), strokeWidth 2.dp, color MaterialTheme.colorScheme.onPrimary ) } else { Text(登录) } } }点击登录后把loading置为true按钮显示转圈动画并禁止再次点击网络请求结束后loading置为false恢复可点击状态。这种模式比用 Toast 提示“请求中”要专业得多。6.3 图标按钮当按钮只有图标、没有文字时用IconButton或FilledIconButtonIconButton(onClick { /* 处理点击 */ }) { Icon( imageVector Icons.Default.Refresh, contentDescription 刷新 ) }contentDescription用于无障碍朗读不能省略。特别是图标按钮没有文字信息屏幕阅读器只能靠contentDescription告诉用户这个按钮是干什么的。6.4 按钮的点击范围与布局Compose 按钮默认自带最小尺寸和点击涟漪效果。如果需要扩大点击区域可以在Modifier上增加minimumInteractiveComponentSize()这是 Material 组件默认行为的一部分。实际布局时直接用Modifier.fillMaxWidth()可以让按钮撑满整行Button( onClick { /* 处理点击 */ }, modifier Modifier .fillMaxWidth() .height(52.dp) ) { Text(登录) }7. Snackbar 提示组件与状态管理7.1 为什么是 SnackbarSnackbar 是 Material Design 中的轻量提示组件从屏幕底部滑出短暂显示后自动消失。它和 Toast 的区别在于Snackbar 支持操作按钮比如“撤销”“重试”。Snackbar 属于应用内 UI样式可控适配深色模式。Snackbar 需要挂在Scaffold上由SnackbarHostState管理。7.2 基础实现Snackbar 不是简单调用一个全局方法它需要三样东西配合Scaffold作为页面容器。SnackbarHost指定 Snackbar 的展示位置。SnackbarHostState控制 Snackbar 的显示和隐藏。Composable fun SnackbarDemo() { val snackbarHostState remember { SnackbarHostState() } val scope rememberCoroutineScope() Scaffold( snackbarHost { SnackbarHost(snackbarHostState) } ) { innerPadding - Button( onClick { scope.launch { snackbarHostState.showSnackbar(操作成功) } }, modifier Modifier.padding(innerPadding) ) { Text(显示 Snackbar) } } }关键点rememberCoroutineScope()获取一个协程作用域避免在非 suspend 环境中直接调用showSnackbar。showSnackbar是挂起函数必须放在协程里。Scaffold会为 Snackbar 自动预留位置它不会覆盖底部内容。7.3 带操作按钮的 Snackbarscope.launch { val result snackbarHostState.showSnackbar( message 删除成功, actionLabel 撤销, duration SnackbarDuration.Short ) if (result SnackbarResult.ActionPerformed) { // 用户点击了“撤销” } }showSnackbar会返回用户操作结果SnackbarResult.ActionPerformed表示用户点击了操作按钮。这个交互模式非常适合删除、修改等可逆操作场景。7.4 Snackbar 与输入框、按钮的联动Snackbar 最常见的用法是作为表单提交的结果反馈。比如用户点击“登录”按钮后如果用户名或密码为空弹出提示。后面会有一个完整示例这里先强调一个容易忽略的问题SnackbarHost 必须放在 Scaffold 中否则showSnackbar调用不会产生任何可视效果。代码不会报错只是什么都不显示排查起来很费时间。8. 组合实战登录表单完整示例现在把输入框、按钮、Snackbar 组合起来做一个完整的登录表单。这个示例会覆盖两个输入框用户名、密码。密码可见性切换。表单校验。登录按钮 loading 状态。校验失败与成功两种 Snackbar 反馈。package com.example.composedemo import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.layout.* import androidx.compose.foundation.text.KeyboardOptions import androidx.compose.material3.* import androidx.compose.runtime.* import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.text.input.KeyboardType import androidx.compose.ui.text.input.PasswordVisualTransformation import androidx.compose.ui.text.input.VisualTransformation import androidx.compose.ui.unit.dp import kotlinx.coroutines.launch class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { MaterialTheme { LoginScreen() } } } } OptIn(ExperimentalMaterial3Api::class) Composable fun LoginScreen() { var username by remember { mutableStateOf() } var password by remember { mutableStateOf() } var passwordVisible by remember { mutableStateOf(false) } var loading by remember { mutableStateOf(false) } val snackbarHostState remember { SnackbarHostState() } val scope rememberCoroutineScope() val canSubmit username.isNotBlank() password.isNotBlank() Scaffold( snackbarHost { SnackbarHost(snackbarHostState) } ) { innerPadding - Column( modifier Modifier .fillMaxSize() .padding(innerPadding) .padding(24.dp), verticalArrangement Arrangement.Center, horizontalAlignment Alignment.CenterHorizontally ) { OutlinedTextField( value username, onValueChange { username it }, label { Text(用户名) }, singleLine true, modifier Modifier.fillMaxWidth() ) Spacer(modifier Modifier.height(16.dp)) OutlinedTextField( value password, onValueChange { password it }, label { Text(密码) }, singleLine true, visualTransformation if (passwordVisible) { VisualTransformation.None } else { PasswordVisualTransformation() }, trailingIcon { TextButton(onClick { passwordVisible !passwordVisible }) { Text(if (passwordVisible) 隐藏 else 显示) } }, keyboardOptions KeyboardOptions(keyboardType KeyboardType.Password), modifier Modifier.fillMaxWidth() ) Spacer(modifier Modifier.height(24.dp)) Button( onClick { if (!canSubmit) { scope.launch { snackbarHostState.showSnackbar(用户名和密码不能为空) } returnButton } // 模拟登录请求 loading true scope.launch { kotlinx.coroutines.delay(1500) loading false snackbarHostState.showSnackbar(登录成功) } }, enabled !loading, modifier Modifier .fillMaxWidth() .height(52.dp) ) { if (loading) { CircularProgressIndicator( modifier Modifier.size(20.dp), strokeWidth 2.dp ) } else { Text(登录) } } } } }这个示例的运行逻辑用户输入用户名和密码。点击“登录”按钮时先判断输入是否为空为空则弹出 Snackbar 提示。输入不为空时按钮进入 loading 状态模拟网络请求 1.5 秒。请求结束后按钮恢复弹出“登录成功”提示。判断成功的标准应用启动后能正常输入、按钮点击有反馈、密码可切换可见性、空值提示和成功提示都能出现。这个示例文件可以直接作为Empty Activity模板的MainActivity.kt使用。跑起来之后建议你改几个地方验证自己的理解去掉canSubmit的enabled绑定看看按钮始终可点击的效果。把snackbarHost从Scaffold中删掉看 Snackbar 是否还会显示。用rememberSaveable替换remember旋转屏幕后观察输入内容是否保留。9. 常见问题与排查方法下面是这组组件在实际开发中最高频的问题和排查思路问题现象可能原因排查方式解决方案输入框输入没反应只设置了value没有在onValueChange更新状态检查onValueChange回调内是否更新了状态在回调中执行text it按钮点击无效enabled false检查按钮的enabled参数确认提交条件满足或移除enabledSnackbar 不显示SnackbarHost没有放在Scaffold中或没有传snackbarHostState检查Scaffold(snackbarHost ...)的写法为Scaffold配置snackbarHost参数Snackbar 不显示在非协程环境中直接调用showSnackbar确认调用处是否在协程内使用rememberCoroutineScope().launch包裹密码框明文显示visualTransformation条件写反检查if/else分支passwordVisible为真时传VisualTransformation.None软键盘遮挡输入框页面没有处理 IME 自适应检查WindowCompat.setDecorFitsSystemWindows是否关闭使用Modifier.imePadding()或调整adjustResize预览界面空白未添加Preview注解或预览函数用错检查预览函数是否独立于setContent添加Preview(showBackground true)注解编译报错找不到 Compose API依赖版本不匹配或缺少 Compose 编译器插件检查plugins和dependencies配置补全org.jetbrains.kotlin.plugin.compose插件和 Compose 依赖旋转屏幕后输入内容丢失使用remember而不是rememberSaveable在源码中搜索remember { mutableStateOf替换为rememberSaveable { mutableStateOf界面频繁重组卡顿在setContent或 composable 内部执行耗时操作查看 Logcat 是否有卡顿警告将耗时逻辑移入LaunchedEffect或 ViewModel这里最值得记住的是问题三、四经常被当成同一个问题但原因不同。如果你发现 Snackbar 完全不显示先检查Scaffold层如果显示后立即消失再检查协程和调用逻辑。10. 性能观察与最佳实践10.1 控制重组范围Compose 是状态驱动但状态变化并不一定导致整个页面重组。单个输入框的内容变化时Compose 会尽量重组最小范围。这要求你在写代码时避免把大计算量逻辑直接写在组合函数中Composable fun BadExample() { var text by remember { mutableStateOf() } // 错误每次重组都会计算 val result heavyCalculation(text) TextField(value text, onValueChange { text it }) }正确做法是把heavyCalculation放进remember(text)或derivedStateOf中只有输入变化时才重新计算。10.2 状态保存策略remember保存重组期间的状态。rememberSaveable保存配置变更如旋转屏幕时的状态。ViewModel StateFlow保存进程死亡时的业务状态。输入框内容建议使用rememberSaveable因为用户旋转屏幕后不应丢失已输入的内容。10.3 输入内容合规实践输入框涉及用户数据下面几条是硬性建议不要把TextField的值直接打印到 Logcat。不要在上传日志时包含输入框内容。采集手机号、身份证号等敏感信息前必须有明确业务场景和隐私政策支持。测试环境和生产环境的数据必须隔离。10.4 深色模式适配Material 3 组件默认支持深色模式。只要使用MaterialTheme提供的颜色语义而不是硬编码白色、黑色输入框、按钮、Snackbar 的深色表现都会自动跟随系统主题。11. 总结与下一步这篇文章从一个极小的入口展开输入框、按钮、Snackbar。但这三个组件背后其实是 Compose 声明式 UI 的核心运行机制。输入框的value和onValueChange是状态驱动的最基础模型按钮的enabled是状态影响交互的典型例子Snackbar 的SnackbarHostState则是跨组件状态通信的入门形态。建议你先做的事把上面第 8 节的登录表单完整跑一遍。这是最短路径验证自己是否真正理解了 Compose 状态管理的方式。最容易踩的坑就是 Snackbar 忘挂Scaffold、输入框忘记更新状态这两个问题在后续项目开发中还会反复出现。下一步值得扩展的方向用 ViewModel 管理登录状态替代在 composable 里写delay的模拟逻辑。把表单校验抽成独立函数配合StateFlow做实时校验。接入 Navigation 组件实现登录成功后的页面跳转。学习Modifier.imePadding()处理软键盘遮挡输入框的问题。将输入框、按钮、Snackbar 封装成通用组件减少复用代码量。这篇文章可以作为 Compose 入门第 7 课的配套笔记保存后续写到表单、登录、设置页时回来查一下即可。
Jetpack Compose 核心交互组件：输入框、按钮与 Snackbar 实战指南
这次我们来看 Jetpack Compose 里最常用的三个交互组件输入框、按钮、Snackbar。这是“Jetpack Compose 安卓声明式 UI 开发”系列的第 7 篇主题很聚焦但内容并不浅。Compose 已经成了 Android 官方主推的 UI 开发方式如果你还在用 XML 写界面、findViewById 找控件那这一篇建议认真读完。文章会把三个组件的用法、状态管理方式、组合联动都过一遍最后给出一个可以直接运行的登录表单示例放进 Android Studio 就能跑。你会看到声明式 UI 和传统 View 系统的最大区别输入框的值存哪、按钮状态怎么变、Snackbar 怎么弹全部由状态驱动没有 findViewById没有 setText没有 show() 这样到处飞的操作。从门槛来看你只需要具备 Android Studio 基础使用经验、一点 Kotlin 语法以及一个模拟器或真机。不需要额外购买任何东西官方依赖拉下来就能写。下面直接进入正文。1. 核心能力速览先用一张表快速看清本次内容覆盖的范围能力项说明技术类型Android 声明式 UI 开发框架组件核心组件TextField / OutlinedTextField、Button 按钮族、Snackbar依赖方式Gradle 引入 Compose BOM 与 Material 3运行环境Android Studio Kotlin Android SDKAPI 21状态管理remember、mutableStateOf、状态提升事件回调onValueChange、onClick、SnackbarHostState.showSnackbar()视觉规范Material Design 3 自动适配主题是否支持预览支持 Preview 静态预览适用对象从 XML 转向 Compose 的 Android 开发者是否支持批量状态联动支持通过状态提升统一管理多个输入框从材料来看这个系列属于“搬运 中文讲解”的教程形式核心价值是把 Compose 官方思路用中文系统地拆解出来。本文不重复搬运原视频重点把输入框、按钮、Snackbar 的工程化用法和常见坑位重新整理成博客的形式方便你作为手册查阅。2. 适用场景与使用边界先说实话这三个组件是 Compose 应用里出现频率最高的组合之一。登录页、注册页、设置页、搜索栏、消息反馈几乎每一个需要用户操作的界面都离不开它们。适合解决的场景表单类页面用户名、密码、手机号等输入场景。操作入口登录按钮、提交按钮、次级操作按钮。轻量反馈操作成功、失败提示、撤销入口、网络异常提示。不适合的场景需要长时间驻留、用户必须确认的系统级提示优先考虑 Dialog 或 Notification而不是 Snackbar。复杂富文本编辑、代码编辑器类输入Compose 基础 TextField 会吃力需要引入专用编辑器组件。追求极致输入性能、需要接入 IME 自定义键盘的大规模文本处理场景需要评估 Compose 的适配上限。关于边界有一点务必注意输入框天然涉及用户数据。如果应用采集手机号、验证码、用户名、搜索关键词必须在隐私政策里明确说明用途不能把用户输入内容写入本地明文日志更不能在未授权情况下上传到第三方服务。作为开发者写 Demo 自己测试没问题一旦上架或商用输入内容的处理和存储都需要合规。3. 环境准备与前置条件Compose 项目的环境准备并不复杂但依赖版本匹配是新手最常踩坑的地方。前置条件清单Android Studio 最新稳定版建议直接使用自带 JDK 的版本。Android SDK建议 API 33 或更高Compose 最低支持 API 21。一个模拟器或真机。模拟器推荐使用 Pixel 系列镜像真机开启开发者选项和 USB 调试。Kotlin 基础。至少要知道var、val、lambda 表达式、协程的基本概念。在 Android Studio 新建项目时直接选择 Empty Activity 模板模板会自动生成 Compose 相关配置。如果你是从现有项目接入 Compose需要在build.gradle.kts模块级中补充如下依赖dependencies { val composeBom platform(androidx.compose:compose-bom:2024.06.00) implementation(composeBom) implementation(androidx.compose.ui:ui) implementation(androidx.compose.material3:material3) implementation(androidx.compose.ui:ui-tooling-preview) debugImplementation(androidx.compose.ui:ui-tooling) implementation(androidx.activity:activity-compose:1.9.0) }版本号需要按你本机实际可用版本调整。新版 Android Studio 模板默认使用 Version Cataloglibs.versions.toml管理版本如果你看到的是libs.compose.material3这样的引用不需要重写成上面这种硬编码形式两种方式等价。还要确认项目启用了 Kotlin Compose 编译插件。如果是新版模板plugins块里一般会自动带上plugins { id(com.android.application) id(org.jetbrains.kotlin.android) id(org.jetbrains.kotlin.plugin.compose) }这三个插件缺一不可。尤其是org.jetbrains.kotlin.plugin.compose不配置的话Compose 编译器无法正常工作运行时会直接报错或界面不渲染。4. 声明式 UI 核心概念在写输入框之前必须先理解 Compose 的状态驱动模型。这个模型可以用一句话概括UI f(state)界面是状态的函数。状态变化时Compose 自动重新执行对应的 composable 函数界面随之更新。你不需要手动调用setText或notifyDataSetChanged。先看一个最小示例。一个普通的计数按钮Composable fun Counter() { var count by remember { mutableStateOf(0) } Button(onClick { count }) { Text(点击次数: $count) } }这里有几个关键点remember用来保存状态避免重组时被重置。mutableStateOf(0)创建了一个可观察状态。by委托语法让count的读写直接映射到MutableState。按钮点击时修改countCompose 自动重组Button内部内容界面上的文字就会更新。这个模型和传统 View 系统完全不同。传统方式是你主动找控件、改控件Compose 是你改状态框架负责刷新界面。理解这一点后再看输入框就非常顺了。输入框的值不是控件内部私有的而是由外部状态决定用户输入触发回调你更新状态状态再驱动输入框显示新内容。这就是所谓的“状态提升”。5. 输入框组件详解TextField 与 OutlinedTextField5.1 基础用法Jetpack Compose 提供两个最常用的输入框组件TextField默认填充样式。OutlinedTextField带边框样式。两者的核心参数完全一致区别只在视觉。实际项目中OutlinedTextField使用频率更高因为默认形态更容易看出输入区域边界。最小可运行的输入框Composable fun SimpleInput() { var text by remember { mutableStateOf() } OutlinedTextField( value text, onValueChange { text it }, label { Text(用户名) }, placeholder { Text(请输入用户名) } ) }重点看value和onValueChangevalue是输入框当前显示的内容完全由外部状态控制。onValueChange是用户输入变化时的回调新值通过it返回。如果你只写了value而不更新状态输入框会表现为“无法输入”。这是 Compose 新手最常犯的错误。5.2 密码输入框密码框需要做两件事隐藏输入内容和切换可见性。Composable fun PasswordInput() { var password by remember { mutableStateOf() } var visible by remember { mutableStateOf(false) } OutlinedTextField( value password, onValueChange { password it }, label { Text(密码) }, visualTransformation if (visible) { VisualTransformation.None } else { PasswordVisualTransformation() }, trailingIcon { TextButton(onClick { visible !visible }) { Text(if (visible) 隐藏 else 显示) } } ) }visualTransformation控制输入内容的显示方式。传PasswordVisualTransformation()时内容会变成掩码传VisualTransformation.None时显示明文。trailingIcon是输入框右侧的附加区域可以放图标或文字按钮。5.3 数字输入与键盘类型如果输入内容限定为数字比如年龄、验证码可以通过keyboardOptions指定键盘类型import androidx.compose.foundation.text.KeyboardOptions import androidx.compose.ui.text.input.KeyboardType OutlinedTextField( value code, onValueChange { newValue - if (newValue.length 6 newValue.all { it.isDigit() }) { code newValue } }, label { Text(验证码) }, keyboardOptions KeyboardOptions(keyboardType KeyboardType.Number) )这里做了两层控制keyboardOptions控制软键盘类型为数字键盘。onValueChange里手动过滤非数字字符并限制最大长度。键盘类型只影响软键盘显示用户仍然可能粘贴非数字内容所以回调里的校验不能省略。5.4 错误提示与校验输入框内置isError参数配合supportingText可以显示错误信息Composable fun ValidatedInput() { var email by remember { mutableStateOf() } val isError email.isNotBlank() !android.util.Patterns.EMAIL_ADDRESS.matcher(email).matches() OutlinedTextField( value email, onValueChange { email it }, label { Text(邮箱) }, isError isError, supportingText { if (isError) { Text(邮箱格式不正确) } } ) }isError true时边框和提示文字会切换为主题指定的错误颜色。注意这里的校验逻辑不要写得过重尽量用轻量的正则或 SDK 自带工具避免在重组过程中执行耗时计算。6. 按钮组件详解Button 与 Material3 按钮族6.1 基础 ButtonMaterial 3 提供多种按钮样式按优先级排列组件用途视觉强调程度Button页面主操作高FilledTonalButton次主操作中OutlinedButton次要操作中低TextButton低优先级操作低最基础的使用Button( onClick { /* 处理点击 */ }, enabled true ) { Text(登录) }enabled为false时按钮置灰且不可点击这在表单校验场景中非常实用。6.2 表单提交按钮与 loading 状态实际开发中按钮经常需要展示“加载中”状态。Compose 没有内置的loading参数但可以自己组合常见做法是用CircularProgressIndicator替换按钮文字Composable fun LoginButton( loading: Boolean, onClick: () - Unit ) { Button( onClick onClick, enabled !loading ) { if (loading) { CircularProgressIndicator( modifier Modifier.size(20.dp), strokeWidth 2.dp, color MaterialTheme.colorScheme.onPrimary ) } else { Text(登录) } } }点击登录后把loading置为true按钮显示转圈动画并禁止再次点击网络请求结束后loading置为false恢复可点击状态。这种模式比用 Toast 提示“请求中”要专业得多。6.3 图标按钮当按钮只有图标、没有文字时用IconButton或FilledIconButtonIconButton(onClick { /* 处理点击 */ }) { Icon( imageVector Icons.Default.Refresh, contentDescription 刷新 ) }contentDescription用于无障碍朗读不能省略。特别是图标按钮没有文字信息屏幕阅读器只能靠contentDescription告诉用户这个按钮是干什么的。6.4 按钮的点击范围与布局Compose 按钮默认自带最小尺寸和点击涟漪效果。如果需要扩大点击区域可以在Modifier上增加minimumInteractiveComponentSize()这是 Material 组件默认行为的一部分。实际布局时直接用Modifier.fillMaxWidth()可以让按钮撑满整行Button( onClick { /* 处理点击 */ }, modifier Modifier .fillMaxWidth() .height(52.dp) ) { Text(登录) }7. Snackbar 提示组件与状态管理7.1 为什么是 SnackbarSnackbar 是 Material Design 中的轻量提示组件从屏幕底部滑出短暂显示后自动消失。它和 Toast 的区别在于Snackbar 支持操作按钮比如“撤销”“重试”。Snackbar 属于应用内 UI样式可控适配深色模式。Snackbar 需要挂在Scaffold上由SnackbarHostState管理。7.2 基础实现Snackbar 不是简单调用一个全局方法它需要三样东西配合Scaffold作为页面容器。SnackbarHost指定 Snackbar 的展示位置。SnackbarHostState控制 Snackbar 的显示和隐藏。Composable fun SnackbarDemo() { val snackbarHostState remember { SnackbarHostState() } val scope rememberCoroutineScope() Scaffold( snackbarHost { SnackbarHost(snackbarHostState) } ) { innerPadding - Button( onClick { scope.launch { snackbarHostState.showSnackbar(操作成功) } }, modifier Modifier.padding(innerPadding) ) { Text(显示 Snackbar) } } }关键点rememberCoroutineScope()获取一个协程作用域避免在非 suspend 环境中直接调用showSnackbar。showSnackbar是挂起函数必须放在协程里。Scaffold会为 Snackbar 自动预留位置它不会覆盖底部内容。7.3 带操作按钮的 Snackbarscope.launch { val result snackbarHostState.showSnackbar( message 删除成功, actionLabel 撤销, duration SnackbarDuration.Short ) if (result SnackbarResult.ActionPerformed) { // 用户点击了“撤销” } }showSnackbar会返回用户操作结果SnackbarResult.ActionPerformed表示用户点击了操作按钮。这个交互模式非常适合删除、修改等可逆操作场景。7.4 Snackbar 与输入框、按钮的联动Snackbar 最常见的用法是作为表单提交的结果反馈。比如用户点击“登录”按钮后如果用户名或密码为空弹出提示。后面会有一个完整示例这里先强调一个容易忽略的问题SnackbarHost 必须放在 Scaffold 中否则showSnackbar调用不会产生任何可视效果。代码不会报错只是什么都不显示排查起来很费时间。8. 组合实战登录表单完整示例现在把输入框、按钮、Snackbar 组合起来做一个完整的登录表单。这个示例会覆盖两个输入框用户名、密码。密码可见性切换。表单校验。登录按钮 loading 状态。校验失败与成功两种 Snackbar 反馈。package com.example.composedemo import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.layout.* import androidx.compose.foundation.text.KeyboardOptions import androidx.compose.material3.* import androidx.compose.runtime.* import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.text.input.KeyboardType import androidx.compose.ui.text.input.PasswordVisualTransformation import androidx.compose.ui.text.input.VisualTransformation import androidx.compose.ui.unit.dp import kotlinx.coroutines.launch class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { MaterialTheme { LoginScreen() } } } } OptIn(ExperimentalMaterial3Api::class) Composable fun LoginScreen() { var username by remember { mutableStateOf() } var password by remember { mutableStateOf() } var passwordVisible by remember { mutableStateOf(false) } var loading by remember { mutableStateOf(false) } val snackbarHostState remember { SnackbarHostState() } val scope rememberCoroutineScope() val canSubmit username.isNotBlank() password.isNotBlank() Scaffold( snackbarHost { SnackbarHost(snackbarHostState) } ) { innerPadding - Column( modifier Modifier .fillMaxSize() .padding(innerPadding) .padding(24.dp), verticalArrangement Arrangement.Center, horizontalAlignment Alignment.CenterHorizontally ) { OutlinedTextField( value username, onValueChange { username it }, label { Text(用户名) }, singleLine true, modifier Modifier.fillMaxWidth() ) Spacer(modifier Modifier.height(16.dp)) OutlinedTextField( value password, onValueChange { password it }, label { Text(密码) }, singleLine true, visualTransformation if (passwordVisible) { VisualTransformation.None } else { PasswordVisualTransformation() }, trailingIcon { TextButton(onClick { passwordVisible !passwordVisible }) { Text(if (passwordVisible) 隐藏 else 显示) } }, keyboardOptions KeyboardOptions(keyboardType KeyboardType.Password), modifier Modifier.fillMaxWidth() ) Spacer(modifier Modifier.height(24.dp)) Button( onClick { if (!canSubmit) { scope.launch { snackbarHostState.showSnackbar(用户名和密码不能为空) } returnButton } // 模拟登录请求 loading true scope.launch { kotlinx.coroutines.delay(1500) loading false snackbarHostState.showSnackbar(登录成功) } }, enabled !loading, modifier Modifier .fillMaxWidth() .height(52.dp) ) { if (loading) { CircularProgressIndicator( modifier Modifier.size(20.dp), strokeWidth 2.dp ) } else { Text(登录) } } } } }这个示例的运行逻辑用户输入用户名和密码。点击“登录”按钮时先判断输入是否为空为空则弹出 Snackbar 提示。输入不为空时按钮进入 loading 状态模拟网络请求 1.5 秒。请求结束后按钮恢复弹出“登录成功”提示。判断成功的标准应用启动后能正常输入、按钮点击有反馈、密码可切换可见性、空值提示和成功提示都能出现。这个示例文件可以直接作为Empty Activity模板的MainActivity.kt使用。跑起来之后建议你改几个地方验证自己的理解去掉canSubmit的enabled绑定看看按钮始终可点击的效果。把snackbarHost从Scaffold中删掉看 Snackbar 是否还会显示。用rememberSaveable替换remember旋转屏幕后观察输入内容是否保留。9. 常见问题与排查方法下面是这组组件在实际开发中最高频的问题和排查思路问题现象可能原因排查方式解决方案输入框输入没反应只设置了value没有在onValueChange更新状态检查onValueChange回调内是否更新了状态在回调中执行text it按钮点击无效enabled false检查按钮的enabled参数确认提交条件满足或移除enabledSnackbar 不显示SnackbarHost没有放在Scaffold中或没有传snackbarHostState检查Scaffold(snackbarHost ...)的写法为Scaffold配置snackbarHost参数Snackbar 不显示在非协程环境中直接调用showSnackbar确认调用处是否在协程内使用rememberCoroutineScope().launch包裹密码框明文显示visualTransformation条件写反检查if/else分支passwordVisible为真时传VisualTransformation.None软键盘遮挡输入框页面没有处理 IME 自适应检查WindowCompat.setDecorFitsSystemWindows是否关闭使用Modifier.imePadding()或调整adjustResize预览界面空白未添加Preview注解或预览函数用错检查预览函数是否独立于setContent添加Preview(showBackground true)注解编译报错找不到 Compose API依赖版本不匹配或缺少 Compose 编译器插件检查plugins和dependencies配置补全org.jetbrains.kotlin.plugin.compose插件和 Compose 依赖旋转屏幕后输入内容丢失使用remember而不是rememberSaveable在源码中搜索remember { mutableStateOf替换为rememberSaveable { mutableStateOf界面频繁重组卡顿在setContent或 composable 内部执行耗时操作查看 Logcat 是否有卡顿警告将耗时逻辑移入LaunchedEffect或 ViewModel这里最值得记住的是问题三、四经常被当成同一个问题但原因不同。如果你发现 Snackbar 完全不显示先检查Scaffold层如果显示后立即消失再检查协程和调用逻辑。10. 性能观察与最佳实践10.1 控制重组范围Compose 是状态驱动但状态变化并不一定导致整个页面重组。单个输入框的内容变化时Compose 会尽量重组最小范围。这要求你在写代码时避免把大计算量逻辑直接写在组合函数中Composable fun BadExample() { var text by remember { mutableStateOf() } // 错误每次重组都会计算 val result heavyCalculation(text) TextField(value text, onValueChange { text it }) }正确做法是把heavyCalculation放进remember(text)或derivedStateOf中只有输入变化时才重新计算。10.2 状态保存策略remember保存重组期间的状态。rememberSaveable保存配置变更如旋转屏幕时的状态。ViewModel StateFlow保存进程死亡时的业务状态。输入框内容建议使用rememberSaveable因为用户旋转屏幕后不应丢失已输入的内容。10.3 输入内容合规实践输入框涉及用户数据下面几条是硬性建议不要把TextField的值直接打印到 Logcat。不要在上传日志时包含输入框内容。采集手机号、身份证号等敏感信息前必须有明确业务场景和隐私政策支持。测试环境和生产环境的数据必须隔离。10.4 深色模式适配Material 3 组件默认支持深色模式。只要使用MaterialTheme提供的颜色语义而不是硬编码白色、黑色输入框、按钮、Snackbar 的深色表现都会自动跟随系统主题。11. 总结与下一步这篇文章从一个极小的入口展开输入框、按钮、Snackbar。但这三个组件背后其实是 Compose 声明式 UI 的核心运行机制。输入框的value和onValueChange是状态驱动的最基础模型按钮的enabled是状态影响交互的典型例子Snackbar 的SnackbarHostState则是跨组件状态通信的入门形态。建议你先做的事把上面第 8 节的登录表单完整跑一遍。这是最短路径验证自己是否真正理解了 Compose 状态管理的方式。最容易踩的坑就是 Snackbar 忘挂Scaffold、输入框忘记更新状态这两个问题在后续项目开发中还会反复出现。下一步值得扩展的方向用 ViewModel 管理登录状态替代在 composable 里写delay的模拟逻辑。把表单校验抽成独立函数配合StateFlow做实时校验。接入 Navigation 组件实现登录成功后的页面跳转。学习Modifier.imePadding()处理软键盘遮挡输入框的问题。将输入框、按钮、Snackbar 封装成通用组件减少复用代码量。这篇文章可以作为 Compose 入门第 7 课的配套笔记保存后续写到表单、登录、设置页时回来查一下即可。
