做了三年 Compose 项目我越来越觉得文本输入框是值得单独花一整篇去讲清楚的组件。Jetpack Compose 里的 TextField在 Material 3 版本下跟早期写 XML 时的 EditText 完全是两个物种它不自带状态、不自动保存内容甚至可以让你自由重排内部结构。很多同事问我的问题其实是同一个为什么我照着示例写了 TextField输入没反应为什么弹不出数字键盘为什么中文输不了几个字就被拦掉了这篇文章我就从最基础的状态管理开始逐步拆到键盘交互、视觉定制和几个高频业务场景的实现最后再把项目里踩过的版本坑列出来。无论你是刚开始接触 Compose还是已经上了生产项目但没系统梳理过 TextField都可以从里面找到能直接用的东西。1. 为什么 Material 3 的 TextField 值得单独拆开讲1.1 从 XML 时代到 Compose输入框的思维转换先聊聊我这几年最大的体会。以前在 XML 里写 EditText你很少去思考“状态”这件事。android:text设置好再挂一个 TextWatcher 把内容同步到 ViewModel其余样式交给 drawable 和 selector 就好。切到 Compose 之后第一个被颠覆的认知就是输入框的内容不再由组件内部保存而是由调用方决定。TextField必须接收一个value同时必须传入一个onValueChange回调。整个组件看起来像个“受控组件”跟 Web 前端里 React 的思路非常像。好处是数据流完全可预测所有文本变化都经过同一个回调你在哪里修改状态哪里就能感知到变化。坏处也很明显很多从 XML 转过来的人第一周都会踩同一个坑写了TextField(value text)但onValueChange里忘了回传或者根本没有onValueChange结果键盘输入在屏幕上纹丝不动。正常写法是这样var text by rememberSaveable { mutableStateOf() } TextField( value text, onValueChange { text it }, label { Text(用户名) } )这里我用的是rememberSaveable不是普通的remember。区别在于当 Activity 因为旋转屏幕、系统回收或者分屏被重建时rememberSaveable能把文本状态自动存进 Bundle并在重建后恢复回来。你如果用remember { mutableStateOf() }旋转一下屏幕用户刚输入的内容就全没了。类似的坑我在代码评审里见过太多次属于那种不影响编译、但真实体验很糟糕的问题。1.2 M3 与 M2 的 TextField 差异默认样式、认知门槛和 API 状态Material 3 版本的 TextField从视觉到 API 都跟 Material 2 有一些微妙的差别。M2 时代我们熟悉的TextField是填充式加底部下划线OutlinedTextField是带边框的卡片式。到了 M3整体风格更强调圆角容器、状态层叠加和颜色系统联动。比如容器默认带一个surfaceContainerHighest色调的填充聚焦时颜色会变悬停和按下时还有 ripple 状态层叠加这些在 M3 里都是默认行为。比较实际的一个问题是M3 早期版本中TextField这类组件被标注为ExperimentalMaterial3Api。也就是说你在代码里直接用 TextField编译器会要求加OptIn(ExperimentalMaterial3Api::class)。后来随着版本迭代部分组件去掉了实验性标注但如果你使用 material3 1.0.x 或 1.1.x仍然会遇到这个注解。网上很多教程抄下来会看到一堆实验性 API 警告但这不代表代码有错只是你的依赖版本跟教程不一致而已。遇到这种情况别硬抄注解先看一下当前依赖版本的源码和 release notes。M3 输入框的交互细节也值得注意聚焦时底部指示器或边框会变成主题色未聚焦时是灰色或透明容器颜色会在聚焦、悬停、按下时叠加上不同的状态层错误状态下边框、指示器、label 都会跟随错误色变化label有浮动动画输入内容后 label 会缩小上浮到输入框左上角。这些行为不是简单改一两个参数就能完全覆盖的第一次用 M3 的 TextField建议先用默认主题跑一遍看清楚它的“默认样子”再决定要定制哪些地方。1.3 TextField / OutlinedTextField / BasicTextField 怎么选我自己的选择原则很简单90% 的业务场景用TextField或OutlinedTextField只有极少数需要完全自定义绘制的情况才碰BasicTextField。需要明显边框、表单位比较强用OutlinedTextField界面走扁平化、填充式风格用TextField想要完全掌控背景、光标、选中色甚至做一个不像输入框的输入区域才用BasicTextField。BasicTextField是底层组件TextField和OutlinedTextField本质上是它在外面套了一层decorationBox把容器、label、图标、提示文字这些 Material 规范里的插槽都实现好了。很多人一上来就想用BasicTextField做完全自定义结果发现要自己处理光标闪烁、文本选中、滚动、手势选择工作量翻倍还容易出 bug。能用封装层解决的事别急着往底层钻。2. 状态管理与常用参数value、onValueChange、label 与 placeholder2.1 为什么状态必须提升以及 rememberSaveable 的完整用法Compose 之所以把状态提升设计成默认规范是因为它是声明式 UI。界面长什么样完全由状态决定。TextField内部不持有状态它只负责把value渲染出来并在用户输入时通过onValueChange通知外部更新。外部更新状态后重新组合输入框内容跟着变化。这个循环一旦断掉比如回调里没更新状态界面就不会有任何变化。rememberSaveable能保存的类型受限于 Bundle。String、Int、Boolean这些基本类型可以直接存如果value用的是TextFieldValue需要指定stateSavervar text by rememberSaveable(stateSaver TextFieldValue.Saver) { mutableStateOf(TextFieldValue()) } TextField( value text, onValueChange { text it } )TextFieldValue是比String更完整的输入框状态它除了包含文本内容还包含光标选区selection和输入法组合文本composition的信息。后面讲输入过滤的时候你会看到它的价值。现在先记住一点如果只是存普通字符串用String就够了一旦需要精细控制光标或处理中文组合态就必须换成TextFieldValue。2.2 TextFieldValue 与 String 的选择时机我见过不少人在输入框里只用String直到某天产品提了一个需求输入内容达到最大长度后再输入字符光标不能乱跳。这时候String方案就开始力不从心了。举个最常见的场景限制输入 10 个字符。用String的写法是onValueChange { newValue - if (newValue.length 10) { value newValue } }在英文输入下这个逻辑没有问题。但在中文输入法下用户输入拼音时onValueChange收到的是拼音字母的组合文本。比如用户想输入“你好”他敲了nihao这 5 个字母还没上屏呢newValue.length已经大于 10结果输入直接被拒绝用户连候选词都看不到。这就是典型的“输入框会吞字”。正确的处理方式是判断用户当前是否处于输入法组合状态如果是就放行等候选词确定上屏之后再统一做长度限制。这个判断写在TextFieldValue.composition上onValueChange { tfv - val composing tfv.composition ! null if (composing || tfv.text.length 10) { value tfv } else { val newText tfv.text.take(10) value tfv.copy(text newText, selection TextRange(newText.length)) } }这段代码的意义在于用户在拼音输入过程中composition不为空所以不管拼音多长都不会被截断当用户选词上屏后composition变成空此时再判断最终文本长度超出部分被截掉光标同步移到最后。这样既限制了长度又不会破坏中文输入体验。2.3 label、placeholder、supportingText 的分工与布局M3 的 TextField 在布局上提供了多个辅助插槽比较容易混的是下面这几个label浮动标签。聚焦时上浮到输入框左上角未聚焦但已有内容时也保持上浮placeholder占位提示。只在输入框为空时显示用户一开始输入就消失supportingText常驻辅助文字显示在输入框下方一般放帮助信息或错误提示leadingIcon/trailingIcon左右两侧的图标位prefix/suffix前缀和后缀文本位比如货币符号或计量单位。很多设计稿里只有一个“请输入手机号”的提示开发往往顺手就用placeholder做了。但实际上更适合用的是label。因为placeholder一旦聚焦就消失用户如果中间被打断可能忘了这个字段是干嘛的label则会在聚焦后上浮仍然留在可见区域起到持续提示的作用。如果产品需要一段常驻说明比如“密码需为 8-16 位”那应该用supportingText它始终显示在输入框下方适合放不可消失的帮助文案。3. 键盘与焦点控制KeyboardOptions、ImeAction 和 FocusRequester 的组合拳3.1 KeyboardOptions 里的细节数字键盘也不是万能的KeyboardOptions负责控制软键盘的类型和右下角按钮样式。最常见的需求是手机号输入框弹出数字键盘KeyboardOptions( keyboardType KeyboardType.Number, imeAction ImeAction.Next )这里有一个容易被忽略的坑KeyboardType.Number不是绝对安全的数字限制。在部分第三方输入法或英文键盘下用户仍然能输入、-等符号。如果产品要求严格只允许数字你还得在onValueChange里做一层过滤不能只依赖键盘类型。不同键盘类型的适用场景也需要记清楚键盘类型适用场景注意点Text普通文本默认首字母可能大写可通过capitalization关掉Number数字输入部分键盘仍可输入符号需要代码过滤Decimal小数输入允许小数点适合金额输入Phone电话号码会带出#、*等符号Email邮箱输入键盘上会有和.快捷位Password密码输入会禁用部分输入法的自动联想和候选词如果你把手机号输入框的键盘类型设置成Number表面上是对的但到了真机测试就会发现有些键盘支持长按数字键输入特殊符号。要彻底封死得配合onValueChange过滤。反过来如果你把金额输入框设置成Number而不是Decimal用户连小数点都打不出来这属于比多输入几个符号更严重的错误。3.2 ImeAction键盘右下角按钮的正确触发方式imeAction用来修改键盘右下角按钮的文案和图标常见的有Next、Search、Done、Send。但设置imeAction只是换了按钮外观真正触发动作还缺一个keyboardActionsval focusManager LocalFocusManager.current OutlinedTextField( value username, onValueChange { username it }, keyboardOptions KeyboardOptions(imeAction ImeAction.Next), keyboardActions KeyboardActions( onNext { focusManager.moveFocus(FocusDirection.Down) } ) )FocusDirection.Down会按 Compose 的焦点顺序向下移动。大多数表单页面只要控件从上到下排列这个默认顺序就是对的。如果你的跳转目标比较特殊比如要从最后一个输入框跳到某个按钮并直接触发提交可以给目标控件设置Modifier.focusRequester然后在onDone里手动requestFocus()。比较常见的错误是用户点了“下一步”焦点确实跳到了下一个输入框但下一个输入框没有自动弹键盘。这是因为你只移动了焦点没有主动调用SoftwareKeyboardController.show()。移动焦点后最好补一句keyboard?.show()这样键盘会跟随焦点一起切换。另一个细节是如果最后一个输入框的imeAction是Done用户点击它时应该直接触发提交而不是把焦点移到一个没有意义的控件上。我一般这样处理keyboardActions KeyboardActions( onDone { focusManager.clearFocus() viewModel.submit() } )3.3 FocusRequester 自动聚焦进入页面直接弹键盘搜索页面进入后自动聚焦搜索框是一个非常常见的需求。Compose 里用FocusRequester可以做到val focusRequester remember { FocusRequester() } val keyboard LocalSoftwareKeyboardController.current LaunchedEffect(Unit) { focusRequester.requestFocus() keyboard?.show() } OutlinedTextField( modifier Modifier.focusRequester(focusRequester), value keyword, onValueChange { keyword it }, placeholder { Text(搜索) } )关键点在于requestFocus()必须在LaunchedEffect里调用不能直接写在 Composable 函数体内。因为focusRequester只能在组件挂载到组合树之后才能找到目标直接写在函数体里时组件还没完成布局请求会无效。还有一个实际体验问题如果页面有进场动画动画还没播完就请求焦点键盘可能会在动画过程中闪烁出现观感很糟。我自己的做法是如果页面有过渡动画就给LaunchedEffect加一个delay(300)左右等动画基本稳定后再请求焦点。这个数值不用特别精确实测体感差别很大。4. 视觉定制colors、shape 与 decorationBox 的分层控制4.1 colors 参数拆解别一上来就整段复制M3 的 TextField 颜色是通过TextFieldColors统一管理的。你可以通过TextFieldDefaults.colors()来定制每个字段对应一个状态常用的有focusedContainerColor/unfocusedContainerColor容器填充色focusedIndicatorColor/unfocusedIndicatorColor填充式输入框底部指示器颜色focusedBorderColor/unfocusedBorderColorOutlinedTextField 的边框颜色cursorColor光标颜色focusedLabelColor/unfocusedLabelColorlabel 文字颜色errorContainerColor/errorIndicatorColor/errorLabelColor/errorBorderColor错误状态颜色。我刚开始用的时候图省事从网上抄了一段覆盖了所有颜色的代码。结果发现改了focusedContainerColor之后聚焦时容器颜色确实变了但 label 颜色、指示器颜色、占位符颜色还是跟主题不一致整个输入框像拼凑出来的。原因在于TextFieldDefaults.colors()的默认值来自当前ColorScheme如果你只改两三个字段其他字段仍然跟随主题色。更稳的做法是先在默认主题下跑起来观察哪些颜色不符合预期再针对性地覆盖。比如只想让光标变成品牌色TextFieldDefaults.colors( cursorColor MaterialTheme.colorScheme.primary )这样其他颜色全部保持 M3 默认不会出现“改一个颜色崩一片视觉”的问题。4.2 shape 与边框圆角不是边框边框也不是圆角OutlinedTextField的shape参数控制的是整体轮廓决定输入框四个角的圆角大小。但边框的宽度和颜色是通过colors里的focusedBorderColor、unfocusedBorderColor控制的。这两个维度经常搞混有人想改边框颜色却去改shape自然没有效果。我常用的写法OutlinedTextField( modifier Modifier.fillMaxWidth(), value value, onValueChange { value it }, shape RoundedCornerShape(12.dp), colors TextFieldDefaults.colors( focusedBorderColor MaterialTheme.colorScheme.primary, unfocusedBorderColor Color(0xFFDDDDDD), focusedContainerColor Color.Transparent, unfocusedContainerColor Color.Transparent, ) )如果你用的是填充式TextField它没有边框取而代之的是底部下划线。想去掉下划线就把focusedIndicatorColor和unfocusedIndicatorColor都设成Color.Transparent。这样输入框看起来就没有那条默认的横线了配合自定义背景能做出更干净的样式。4.3 decorationBox真正控制内部布局的入口decorationBox是 M3 TextField 最强大也最容易被忽略的参数。它的作用是把“文本输入区域”作为一个可移动的插槽让你在输入框内部重新排布图标、文本、按钮的位置。举个例子实现一个带搜索图标和清除按钮的搜索框TextField( value text, onValueChange { text it }, modifier Modifier.fillMaxWidth(), decorationBox { innerTextField - Row( verticalAlignment Alignment.CenterVertically, modifier Modifier.padding(horizontal 12.dp) ) { Icon(Icons.Default.Search, contentDescription null) Box(Modifier.weight(1f).padding(horizontal 8.dp)) { innerTextField() } if (text.isNotEmpty()) { IconButton(onClick { text }) { Icon(Icons.Default.Close, contentDescription 清除) } } } } )这里最关键的一行是innerTextField()。它是一个函数调用它才会把真正的文本输入区域渲染出来。如果你忘了调用TextField 会变成一个没有输入能力的空壳点了没有任何反应。在自定义decorationBox时不要完全抛弃默认实现尽量在默认基础上做增量修改否则光标、选中、label 动画这些交互细节都要自己重新实现成本非常高。我自己在项目里用decorationBox实现过不少非标准布局比如“文字在图标下方”“label 在容器内部”都是在默认结构上微调。完全从零拼一个输入框通常只适合做原型验证不适合上生产。5. 高频业务场景实战密码可见性、错误提示、输入过滤与格式化5.1 密码框可见性切换不只是换个图标密码框的本质是visualTransformation。默认设成PasswordVisualTransformation()后输入的内容在界面上显示为圆点但实际文本内容并没有变。切换可见性时只需要在PasswordVisualTransformation()和VisualTransformation.None之间切换var passwordVisible by rememberSaveable { mutableStateOf(false) } OutlinedTextField( value password, onValueChange { password it }, visualTransformation if (passwordVisible) { VisualTransformation.None } else { PasswordVisualTransformation() }, keyboardOptions KeyboardOptions(keyboardType KeyboardType.Password), trailingIcon { IconButton(onClick { passwordVisible !passwordVisible }) { Icon( imageVector if (passwordVisible) { Icons.Default.VisibilityOff } else { Icons.Default.Visibility }, contentDescription if (passwordVisible) 隐藏密码 else 显示密码 ) } } )这里有几个需要提前知道的事第一Icons.Default.Visibility和Icons.Default.VisibilityOff在material-icons-core里不一定都有。我印象中基础包只包含最常用的一小批图标像这种可视性切换图标需要额外引入material-icons-extended依赖。编译时如果报找不到符号先检查依赖。第二切换visualTransformation时如果用户的光标在字符串中间可能出现光标位置偏移的问题。这是因为PasswordVisualTransformation会把文本宽度映射成固定宽度切换回明文时偏移计算可能出现偏差。大多数情况下影响不大但如果产品对光标位置很敏感可以考虑用TextFieldValue在切换时手动修正 selection。第三不要把keyboardType跟着可见性一起切换成KeyboardType.Text。那样会导致键盘类型变化部分输入法会直接把键盘重建用户输入到一半键盘状态被重置体验很差。保持Password类型即可明文显示只是视觉上的不影响输入法行为。5.2 isError 与 supportingText 联动错误状态的正确更新时机M3 的 TextField 内置了isError参数传入true后容器的边框、下划线、label 颜色都会自动变成错误色。配合supportingText可以在输入框下方显示具体错误文案var errorMessage by remember { mutableStateOfString?(null) } OutlinedTextField( value value, onValueChange { value it if (it.length 6) { errorMessage 至少输入 6 个字符 } else { errorMessage null } }, isError errorMessage ! null, supportingText { errorMessage?.let { Text(it) } } )这里有一个时机问题不要把复杂的校验逻辑都塞进onValueChange。输入框每次变化都会触发回调如果校验逻辑很重会产生明显的卡顿。更合理的做法是输入过程中只做轻量检查比如清空时立即清除错误真正的提交校验放在按钮点击时统一执行一次性给所有字段设置 errorMessage。还有一个细节supportingText即使没有错误时也可以显示普通帮助文案。要区分“正常提示”和“错误提示”两种状态可以这样做supportingText { if (errorMessage ! null) { Text(text errorMessage!!, color MaterialTheme.colorScheme.error) } else { Text(text 密码需为 8-16 位字符) } }这样输入框下方始终留有文本位置不会因为错误文案的出现导致布局上下跳动。布局跳动是表单页非常影响体验的问题能用常驻空间解决就尽量用常驻空间。5.3 输入过滤与格式化从“禁止输入”到“允许后加工”输入过滤是 TextField 实操里最容易踩坑的部分。很多人的第一反应是在onValueChange里拦截非法字符并直接丢弃。这个思路没错但实现上很容易导致光标跳位。最简单的数字过滤onValueChange { input - val filtered input.filter { it.isDigit() } if (filtered ! input) returnTextField value filtered }这种写法在输入框内容较长、用户光标在中间插入非法字符时文本被过滤后长度变化Compose 重新设置文本光标很可能会跳到末尾。要解决这个问题可以用TextFieldValue自己维护 selectiononValueChange { tfv - val newText tfv.text.filter { it.isDigit() } if (newText ! tfv.text) { val newSelection tfv.selection.takeIf { it.end newText.length } ?: TextRange(newText.length) value tfv.copy(text newText, selection newSelection) } else { value tfv } }这段代码在过滤掉非法字符后会判断旧的选区位置是否仍然有效。如果旧光标位置已经超出新文本长度就把它收回到末尾否则保持原位置不变。这样用户在中间删除、插入时光标能保持在正确的位置不会跳来跳去。不过我要说句实话严格实时的字符过滤往往不是最优解。对于金额、手机号这类格式要求严格的字段你也可以选择“输入时不限制失去焦点时统一格式化”。比如金额输入用户可能输入“12.3.4”过程中我们不打断等焦点移开后再用正则修正成合法金额。这样用户体验更流畅代码也简单得多。是否实时过滤取决于产品对这个字段的容忍度没有绝对正确答案。6. 我在实际项目中踩过的坑Material 3 版本相关6.1 ExperimentalMaterial3Api 与版本差异M3 的 TextField 在不少版本里都被标注为实验性 API。这个标注本身不是问题真正麻烦的是不同版本之间行为存在差异你从网上找来的代码很可能跟当前依赖对不上。举个例子旧项目里引入 M3 后发现TextFieldDefaults.colors()的某个参数在新版本里被重命名了编译直接报错。当时我去翻源码才发现新版本把backgroundColor系列统一改成了containerColor系列。这已经不是参数名的问题而是整个 M3 颜色体系的规范变化。碰到这种情况最直接的做法是锁定 material3 版本别跟着最新版本频繁升级。升级前先看 release notes确认有哪些破坏性变更。代码层面尽量使用官方文档里的默认写法少用从老版本代码库里抄来的取消标注写法。你抄的代码可能来自某个特定版本换个版本就不兼容了。6.2 中文输入法组合文本的“假长度”问题这个坑我在前面提过一次但值得单独拿出来再讲一遍因为它是 TextField 在中文环境下最核心的问题。英文输入时每个字符上屏都是即时的onValueChange收到的就是最终文本。中文输入不一样用户输入拼音时输入法会先把拼音字母作为组合文本放进去等用户选词后组合文本才会被替换成汉字。如果你在onValueChange里处理不当会出两类问题一是长度限制误伤中文。用户输入一个 6 位汉字的词拼音可能有十几二十个字母直接按length判断拼音阶段就会被截断。二是过滤误伤组合文本。比如你想禁止输入空格用户输入“zhong wen”时拼音里带了空格上来就被过滤掉输入法就无法正常分词联想。正确的处理方式统一是组合期间放行组合结束后再加工。onValueChange { tfv - if (tfv.composition ! null) { // 输入法还在组合阶段不拦截 value tfv } else { // 文字已上屏或手动输入此时再过滤和限制 val filtered tfv.text.filterNot { it.isWhitespace() } value tfv.copy(text filtered, selection TextRange(filtered.length)) } }这套逻辑在 Jetpack Compose 的输入框里基本是通用的凡是做中文输入过滤的地方都应该先判断composition。我在不同项目里遇到至少四五次类似问题每次都换人重新踩一遍所以希望看到这篇文章的人能从根上避免它。6.3 键盘遮挡、焦点闪烁和重组过度最后聊几个跟键盘和性能相关的工程化问题。第一个是键盘遮挡。在普通页面上输入框被弹出的软键盘挡住可以考虑给根布局加Modifier.imePadding()这样键盘弹出时布局会自动上移把输入框顶出可视区域。但要注意在Dialog或底部弹层里使用imePadding()需要给弹层内容本身也加上否则对话框不会跟随键盘移动。我在项目里遇到过对话框里的输入框被键盘完全盖住的情况排查了半天问题就出在imePadding()只加在最外层页面没加到Dialog的内容上。第二个是焦点闪烁。进入页面自动聚焦时如果页面还在做过渡动画键盘可能会在动画过程中闪一下再消失。要避免这个现象可以在LaunchedEffect里加一个delay()等动画基本结束后再requestFocus()。时间不用很长300 毫秒左右体感就不错了。第三个是重组过度。TextField 本身是个状态密集组件每次输入都会触发onValueChange导致持有该状态的 Composable 重组。如果这个 Composable 很大包含列表等无关内容你会发现打字越来越卡。解决办法是把输入框区域拆成独立的 Composable让状态变化只影响输入框附近的范围不要影响整个页面。另一个容易被忽略的点是derivedStateOf可以用来减少不必要的重组比如只在文本长度变化超过某个阈值时才触发下游更新。这些坑看起来不大但在真实项目里个个都能让人排查好几个小时。如果你最近也在写 Compose 表单我建议把上面几类场景在本地项目里跑一遍特别是中文组合文本和焦点迁移这两个提前踩过一遍之后后续写表单会顺手很多。