如果要在 Jetpack Compose 里找几个“看起来人畜无害、用起来全是细节”的组件我会把 RadioButton 排在最前面。之前做问卷模块时三个页面都涉及单选我第一版代码十分钟搞定结果产品验收时连着指了三个问题点整行文字没反应、禁用态颜色不对、TalkBack 只朗读“按钮”却不朗读选项内容。这才意识到Material 3 版 RadioButton 的深度远超一个布尔参数加一个回调那么简单。这篇文章把我从入门到进阶的完整梳理写出来覆盖状态管理、M3 视觉差异、定制方案、真实场景和排错链路适合正在写表单、设置页、筛选器以及被单选组件细节折磨的 Compose 开发者。1. 最小可用代码先让一个 Material 3 RadioButton 跑起来1.1 极简示例先跑通再说架构如果你还在用传统 View 的思维找RadioGroup那得先转变一下Compose 里没有 RadioGroup 这个容器单选组只是若干个RadioButton加上你自己的状态逻辑。最原始的写法长这样Composable fun MinimalRadioSample() { var selected by remember { mutableStateOf(false) } Row(verticalAlignment Alignment.CenterVertically) { RadioButton( selected selected, onClick { selected true } ) Text( text 同意服务条款, modifier Modifier.padding(start 8.dp) ) } }这段代码没多少可解释的selected决定圆点是否填充onClick在点击时把状态改成true。但如果你真的照着它去写表单很快就会发现两个问题。第一个问题是这根本算不算“单选组”。第二个问题更隐蔽文字区域点上去没反应。传统 View 里RadioButton自带文本点文字等于点按钮Compose 的RadioButton只画圆点文本是你自己拼的Text。所以你在生产环境里几乎不会用这种原子写法至少要把整行做成可点击区域。1.2 selected 为什么是一个参数而不是组件内部状态很多从 View 体系转过来的开发者会问为什么RadioButton不自己记住是否选中传统 Android 的RadioButton内部确实维护了checked状态勾选之后自己变。但 Compose 刻意把这事拆开了组件只负责把selected布尔值渲染成相应的视觉形态点击事件通过onClick回调抛出去状态由外部持有。打个比方。你家里的灯亮不亮不由开关面板自己决定而由配电箱里的回路状态决定。开关面板只是“显示当前状态”和“上报用户操作”它自己不存“灯亮着”这件事。如果每个开关都自己存一份状态那半夜你用 App 远程关灯时面板上的状态和真实状态就会打架。在 Compose 里这个“配电箱”就是remember、rememberSaveable或ViewModel里的状态。这样设计有四个直接好处单一数据源无论多少个RadioButton显示同一个状态它们看到的都是同一个值可预测状态怎么变、何时变完全由你的业务代码控制没有隐式的内部突变可恢复进程重建后状态从rememberSaveable恢复不需要组件依次回读易测试把一个selected true传进去UI 必然渲染成选中样式纯函数式的输入输出。所以当你写出RadioButton(selected myState, onClick { myState true })时本质上是说圆点是外部世界的镜像点击是给外部世界发指令。1.3 让整行都可点击用 selectable 而不是 clickable把文本加进点击目标最直觉的做法是在Row上加Modifier.clickable。我最初也这么干然后遇到了“点一次选中再点一次又取消”“TalkBack 把按钮和文本读成两个独立元素”等一系列问题。正确姿势是用Modifier.selectable它和clickable的区别在于clickable表达的是“这是一次普通点击”selectable表达的是“这是一个可被选中的条目”并且会自动在语义里声明Role.RadioButton和selected状态。Composable fun SelectableRow( selected: Boolean, onClick: () - Unit, text: String ) { Row( modifier Modifier .fillMaxWidth() .selectable( selected selected, role Role.RadioButton, onClick onClick ) .padding(vertical 12.dp, horizontal 16.dp), verticalAlignment Alignment.CenterVertically ) { RadioButton( selected selected, onClick null // 交互交给整行容器圆点只负责视觉 ) Text( text text, modifier Modifier.padding(start 12.dp) ) } }注意这里RadioButton的onClick传了null。很多教程会忽略这个细节但它很关键如果圆点自身也响应点击整行容器也响应点击一次触摸会同时触发两次点击逻辑轻则状态闪变重则在LazyColumn里引发 index 错位。把点击事件收敛到唯一的父容器上既简化了手势冲突也让无障碍服务把整行当成一个单选条目来朗读。提示selectable和clickable千万别混用在同一层级。clickable能触发点击但它不会声明“选中”语义也没有selected参数对无障碍和后续状态追踪都很不友好。2. 单选组的状态管理把“哪个被选中”变成唯一事实2.1 为什么不能用一堆 Boolean写“两个选项”时新手最常见的做法是var optionA by remember { mutableStateOf(false) } var optionB by remember { mutableStateOf(false) }这种写法在选项少的时候能跑但本质上是把“谁被选中”这个唯一事实拆成了 N 份副本。每当你需要“点 B 取消 A”就得写optionA false如果后续新增第三个选项又得在每处回调里手动维护另外两个为 false。一旦某个分支漏写就会出现两个圆点同时选中的离奇状态。正确思路是用一个可空值或枚举表示当前选中项每个RadioButton只比较“自己是不是那个值”。enum class PaymentMethod { Alipay, WeChat, Card } Composable fun PaymentMethodSample() { var selectedMethod by rememberSaveable { mutableStateOf(PaymentMethod.Alipay) } Column { listOf( PaymentMethod.Alipay to 支付宝, PaymentMethod.WeChat to 微信支付, PaymentMethod.Card to 银行卡 ).forEach { (method, label) - Row( modifier Modifier .fillMaxWidth() .selectable( selected selectedMethod method, role Role.RadioButton, onClick { selectedMethod method } ) .padding(vertical 12.dp, horizontal 16.dp), verticalAlignment Alignment.CenterVertically ) { RadioButton( selected selectedMethod method, onClick null ) Text(label, modifier Modifier.padding(start 12.dp)) } } } }每次状态切换只改selectedMethod一个值所有圆点的选中状态都从它推导而来。这就是 Compose 推崇的“状态提升”把状态放到所有使用者的最低公共祖先处。2.2 列表单选用 ID 而不是 index当单选组来自一个动态列表时状态就不再是枚举而是“当前选中的那条数据的唯一标识”。很多人在LazyColumn里会用selectedIndex这在一个内容永远不变的静态列表里没问题但一旦列表支持删除、过滤、排序index 就会漂移。举个具体例子列表有 10 项用户选中第 5 项此时selectedIndex 4。然后用户删除第 1 项原本的第 5 项变成了列表第 4 项但你的selectedIndex还是 4于是选中项悄悄变成了原来的第 6 项。这种 bug 不是偶发而是必然。正确写法是用业务主键var selectedProductId by rememberSaveable { mutableStateOfString?(null) } LazyColumn { items(products, key { it.id }) { product - ProductRow( title product.name, selected product.id selectedProductId, onClick { selectedProductId product.id } ) } }items的key参数帮我们做了两件事一是让列表项在顺序变化时保持自身状态稳定二是让selected的比对始终基于业务标识而不是位置。结合Modifier.selectable每次selectedProductId变化时只有新旧两个列表项会发生重组其余项全部跳过性能上也更干净。2.3 从 rememberSaveable 到 ViewModel状态该放哪里既然rememberSaveable能在屏幕旋转、进程重建后自动恢复那是不是就够用了**这取决于状态是否只服务于 UI。打个比方如果你的单选值只是用来控制某个区域的展开收起那rememberSaveable完全够用。但如果这个值要参与表单提交、要传给接口、要回填服务端数据或者要跨页面共享UI 层面的remember就非常别扭——你总不能在提交按钮的onClick里再翻一次remember的闭包去取值吧这时候应该把状态放进ViewModelclass PaymentViewModel : ViewModel() { private val _paymentMethod MutableStateFlow(PaymentMethod.Alipay) val paymentMethod: StateFlowPaymentMethod _paymentMethod.asStateFlow() fun selectMethod(method: PaymentMethod) { _paymentMethod.value method } } Composable fun PaymentScreen(viewModel: PaymentViewModel viewModel()) { val paymentMethod by viewModel.paymentMethod.collectAsStateWithLifecycle() // 直接根据 paymentMethod 渲染点击时调用 viewModel.selectMethod(...) }依赖上需要androidx.lifecycle:lifecycle-runtime-compose才能使用collectAsStateWithLifecycle()它在页面退到后台时会自动停止收集比裸用collectAsState()更省资源。我自己的判断标准很简单如果单选值在离开屏幕后还有人需要读它就进 ViewModel如果只是为了撑住当前界面的一个形状remember 就够了。3. Material 3 下的视觉差异迁移者最容易忽略的三处3.1 颜色体系换了primary 之外的 token 故事从 Material 2 迁到 Material 3最先感受到的往往是颜色变了。M2 时代 RadioButton 的选中色直接绑定MaterialTheme.colors.primaryM3 则把默认颜色拆到了colorScheme的多个角色上。状态Material 2 默认来源Material 3 默认来源选中colors.primarycolorScheme.primary未选中colors.primaryVariant/onSurface的混合colorScheme.onSurfaceVariant禁用选中colors.disabled相关onSurface.copy(alpha 0.38f)禁用未选中同上onSurface.copy(alpha 0.38f)M3 的设计是降低非选中状态的存在感未选中的圆环使用onSurfaceVariant颜色比纯黑/纯白更灰、更柔和选中后换成primary对比更鲜明。如果你在 M2 项目里自定义过颜色迁移后一定要重新过一遍默认色因为同样的“选中色”在两个版本里肉眼观感差别很大。如果你要自定义优先通过RadioButtonDefaults.colorsRadioButton( selected selected, onClick onClick, colors RadioButtonDefaults.colors( selectedColor Color(0xFF6750A4), unselectedColor Color(0xFF79747E), disabledSelectedColor Color(0xFF6750A4).copy(alpha 0.38f), disabledUnselectedColor Color(0xFF79747E).copy(alpha 0.38f) ) )这里有个易踩的坑很多人只改selectedColor忘了传 disabled 系列颜色。于是表单进入禁用态时你原本精心调好的品牌色被默认的“38% 透明度灰”替代整个页面瞬间变得脏兮兮。定制品控时四个状态最好一起给齐。3.2 20dp 的视觉圆点与 48dp 的触摸目标“为什么我的 RadioButton 看起来比 M2 小了一圈”这是迁移后高频出现的问题。M3 规范的 RadioButton 视觉图形本身是 20dp而可交互热区为了保证触达性会借助LocalMinimumInteractiveComponentSize撑到大约 48dp。也就是说你看到的圆点是缩小的部分周围一圈透明区域都是它的热区。很多开发者发现“点圆点附近也没反应”其实不是热区不够而是你的布局里只有一个孤零零的 RadioButton能点的区域只有那 20dp 圆点和周边极小范围。解决方案不是去改 Compose 的默认尺寸而是把整行变成selectable容器让热区变成整行宽度。如果确实需要缩小热区理论上可以通过设置LocalMinimumInteractiveComponentSize调整CompositionLocalProvider(LocalMinimumInteractiveComponentSize provides 40.dp) { // RadioButton 或整行容器 }但我几乎不建议这样做。Material Design 规定触摸目标至少 48dp是有肢体可达性和误触率数据支撑的。为了视觉紧凑牺牲可用性得不偿失。更合适的做法是通过 padding 扩大热区而不是缩减它。3.3 状态层与涟漪交互反馈不是只有颜色变化M3 把交互反馈拆成了两层状态层state layer和涟漪ripple。状态层是 hover、focus、pressed 时叠加在组件表面的一层半透明蒙层颜色通常取自onSurface或primary透明度随状态变化涟漪则是点击时的扩散动画。系统组件已经在内部把这些细节处理好了。这对我们写自定义单选有启发不要只在selected变化时换个颜色就完事按下、聚焦、悬停都应该有相应反馈。比如自定义卡片单选时如果只写了选中色切换用户按下去时完全没有任何视觉响应就会觉得“这玩意是不是没点中”。如果要给自定义组件加状态层反馈通常这样取交互状态val interactionSource remember { MutableInteractionSource() } val isPressed by interactionSource.collectIsPressedAsState() val isHovered by interactionSource.collectIsHoveredAsState()再根据isPressed/isHovered叠加Modifier.background(color.copy(alpha ...))。系统RadioButton内部做的也是类似的事所以你在定制时不要丢掉这一层。4. 进阶定制把默认圆点改成符合产品气质的单选控件4.1 用默认组件但精准改颜色第一种“定制”其实是克制地调色。同样用RadioButtonDefaults.colors把选中色换成品牌主色把未选中色换成品牌描边色同时把 disabled 两种状态的颜色也一并配好视觉上就比默认值更贴近产品调性。这种做法最省事交互反馈、语义、动画都由系统组件兜底稳定性最高。适合场景设置页、列表明细、表单基础单选。你不需要重写绘制逻辑界面看起来就已经是“定制过”的。4.2 把圆形换成卡片、标签、图标语义依然叫 RadioButton比调色更进一步是彻底不用系统的圆形图标自己画选中态。比如商品筛选页的标签单选、卡片单选。这时候仍然可以用Modifier.selectable保留单选语义只是视觉指示器换成你自己的 Box/Icon/卡片边框。下面是一个标签式单选的完整示例视觉上像一个胶囊语义上仍然是 RadioButtonComposable fun FilterTag( label: String, selected: Boolean, onClick: () - Unit ) { val colorScheme MaterialTheme.colorScheme Box( modifier Modifier .clip(RoundedCornerShape(50)) .selectable( selected selected, role Role.RadioButton, onClick onClick ) .background( if (selected) colorScheme.primary else colorScheme.surfaceVariant ) .padding(horizontal 16.dp, vertical 8.dp) ) { Text( text label, color if (selected) colorScheme.onPrimary else colorScheme.onSurface ) } }注意我依然传了role Role.RadioButton和selected。这样 TalkBack 读出来的还是“某某已选中”而不是一个没有角色的自定义容器。视觉上可以千变万化语义角色不能丢。如果你想让按下时也有状态层反馈可以在Box上加indication但更简单的做法是再叠加一层val interactionSource remember { MutableInteractionSource() } val isPressed by interactionSource.collectIsPressedAsState()然后在background后面再画一层isPressed时的半透明蒙层。具体用不用取决于你要不要支持按压反馈。4.3 选中动画的两个实用方向自定义控件时动画一般集中在两个地方状态切换的颜色过渡和指示器的显隐/缩放。颜色过渡用animateColorAsState就很自然val containerColor by animateColorAsState( targetValue if (selected) colorScheme.primary else colorScheme.surfaceVariant, animationSpec tween(durationMillis 150), label radioContainerColor )指示器显隐可以用animateFloatAsState配合 scaleval indicatorScale by animateFloatAsState( targetValue if (selected) 1f else 0f, animationSpec spring( dampingRatio Spring.DampingRatioMediumBouncy, stiffness Spring.StiffnessMediumLow ), label indicatorScale )然后在指示器Box上.graphicsLayer { scaleX indicatorScale; scaleY indicatorScale }。一个经验是颜色过渡用 tween显隐缩放用 spring但 spring 不要到处都是。页面里如果有十来个单选标签同时做弹跳视觉上会非常闹。系统组件默认反而克制得多这也是我建议“先用系统组件再谈定制”的原因。5. 真实业务场景三份可以直接抄的组合用法5.1 设置页偏好图标 标题 说明文字 单选设置页的“单选偏好项”通常不是孤零零一行文字而是“图标 标题 副标题说明 右侧圆点”的组合。代码可以这样组织Composable fun SettingsRadioRow( icon: ImageVector, title: String, description: String, selected: Boolean, onClick: () - Unit ) { Row( modifier Modifier .fillMaxWidth() .selectable( selected selected, role Role.RadioButton, onClick onClick ) .padding(horizontal 16.dp, vertical 12.dp), verticalAlignment Alignment.CenterVertically ) { Icon( imageVector icon, contentDescription null, tint if (selected) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.onSurfaceVariant ) Column( modifier Modifier .weight(1f) .padding(start 16.dp) ) { Text(title, style MaterialTheme.typography.bodyLarge) if (description.isNotEmpty()) { Text( text description, style MaterialTheme.typography.bodySmall, color MaterialTheme.colorScheme.onSurfaceVariant ) } } RadioButton(selected selected, onClick null) } }这里图标颜色跟随选中态变化视觉层次更清楚。contentDescription null是因为图标是装饰性的真正的语义由整行的selectable承担不要让读屏软件把图标再读一遍。5.2 问卷表单必选校验与状态回填问卷类页面通常有多个单选组每次点击都要立刻产生状态提交时还要校验“是否已选”。我推荐用 data class 把整页表单状态收集在一起data class SurveyFormState( val gender: GenderOption? null, val ageRange: AgeRange? null, val satisfaction: SatisfactionLevel? null ) class SurveyViewModel : ViewModel() { private val _form MutableStateFlow(SurveyFormState()) val form: StateFlowSurveyFormState _form.asStateFlow() fun selectGender(value: GenderOption) { _form.update { it.copy(gender value) } } fun submit() { val state _form.value if (state.gender null || state.ageRange null) { // 触发 UI 提示还有未完成项 return } // 组装请求数据 } }单个StateFlow持有整张表单校验逻辑全部收敛到submit()一个函数里。UI 层只负责把gender等值映射到各个selectable容器。这样做的好处是页面重组一百次表单值纹丝不动某个字段要做服务端回填直接_form.update { it.copy(...) }即可不用写各处的 setter 调用。有人会问用rememberSaveable也能实现旋转恢复为什么不直接在 Composable 里写因为问卷提交时要校验、要组装 payload、可能要调接口这些活塞进Composable函数里只会让 UI 层越来越胖。ViewModel 分离出来后Composable 里剩下的只是“读状态、发事件”可测试性也好很多。5.3 商品筛选多组单选之间的联动与禁用电商筛选页里属性面板经常是多组单选尺码一组、颜色一组、风格一组。状态结构一般是一个MapString, Stringkey 是组 IDvalue 是选中的选项 IDvar selectedGroups by remember { mutableStateOfMapString, String(emptyMap()) } fun selectOption(groupId: String, optionId: String) { selectedGroups selectedGroups (groupId to optionId) }每个选项的选中条件就是selectedGroups[groupId] optionId。联动禁用则要在渲染前计算val enabledOptions remember(skuData, selectedGroups) { buildAvailabilityMap(skuData, selectedGroups) }这里enabledOptions根据当前选中的组合实时推导出每个组里哪些选项可用。不可用的选项在RadioButton上传enabled false同时整行容器也要禁用Row( modifier Modifier.selectable( selected selected, enabled enabled, role Role.RadioButton, onClick onClick ) ) { RadioButton( selected selected, enabled enabled, onClick null ) }enabled false时selectable和RadioButton都不会响应点击M3 的默认颜色会自动把不可用项压成 38% 透明度。注意不可用并不等于不可见这也是 Material 规范特意用颜色区分、不直接隐藏的设计意图。6. 高频 Bug 与排查链路从“点不动”到“乱读”6.1 点不动、选中没反应先分清三类原因我在群里看过无数句“RadioButton 点了没反应”绝大多数逃不过下面几类症状常见原因验证方法圆点被点击后立刻弹回原样onClick 传了 null事件根本没分派给圆点检查 RadioButton 的 onClick 是否为 null点击整行没有反应Row 上没有 selectable/clickable或事件被子组件拦截检查是否只有 RadioButton 自己的 onClick 在工作选中后状态闪一下又没了状态被错误地声明在某个 item 的局部 remember 中列表重组后失效把状态上提到 ViewModel 或父级 Composable有一个非常典型的反面写法Row(modifier Modifier.clickable { selected !selected }) { RadioButton( selected selected, onClick { selected !selected } ) }这个写法在点击圆点时RadioButton的 onClick 触发一次selected !selected随后点击事件冒泡到 Row 的 clickable 又触发一次selected !selected一加一减状态原地不动。在真机上你会看到圆点完全没反应或者闪一下又弹回来。这种 bug 的排查思路是先确认同一个点击会不会同时命中多个 onClick再确认最终状态的写入方向是否一致。修复方式就是前面反复强调的Row用selectableRadioButton的onClick置null让事件只有一条路径。6.2 点击区域过小不是 RadioButton 的问题是布局问题如果你把RadioButton放进一个高度只有 24dp 的 Row再点周围空白区域没反应不要怪组件。M3 的RadioButton虽有 48dp 级的最小交互尺寸兜底但它撑的是“包含圆点在内的区域”不是整行。空白区域没有绑任何容器自然不响应。排查时可以临时给整个容器加个边框看看热区到底有多大Modifier.border(1.dp, Color.Red)一跑就能看出来红色边框之外的部分点再多也没用。修复方向很明确让“热区”等于“可见条目区”也就是把selectable放到整行 Row 上而不是包在圆点周围。如果是自定义卡片记得在整张卡片上放selectable然后再把 RadioButton 作为纯视觉元素放进去。以上操作做完整个条目的宽高都是可点击区域。6.3 TalkBack 语义缺失与重复朗读无障碍问题在单选组件上特别容易出因为默认情况下RadioButton和旁边的Text是语义上独立的两个节点。用户触摸整行时TalkBack 可能先读“未选择”再读“标签文字”或者把“按钮”和“文本”拆成两个可聚焦元素操作效率极低。Modifier.selectable已经帮我们声明了role和selected但要让整行的子控件语义合并成一个节点通常还要显式合并后代Row( modifier Modifier .selectable(selected selected, role Role.RadioButton, onClick onClick) .semantics(mergeDescendants true) {} .padding(...) )如果合并后发现 TalkBack 还是读出了多余内容可以更进一步用clearAndSetSemantics清掉子节点语义再手动补充关键信息Modifier.clearAndSetSemantics { role Role.RadioButton selected selected contentDescription label }这条链路的核心是先让系统知道你是一个单选条目再让系统知道你选中了没有最后确保文字标签只被读一次。顺序不能反因为mergeDescendants true如果放在clearAndSetSemantics之前可能又会合并出重复文本。我在实际项目里基本会封装一个SelectableRow把语义合并、角色声明、RadioButton视觉、整行差异都收进一个组件里业务层只传selected、onClick、title、description四样东西。这样无论是设置页、问卷页还是筛选页单选行的表现和行为都完全一致也避免每个页面复制一份“正确写法”时不小心漏掉某个语义细节。写这篇笔记时我又翻了一次自己的提交记录发现单选组件从“能跑”到“真正好用”之间差的不是代码量而是对状态模型、语义角色和交互反馈的完整理解。希望这些内容能帮你少走几个弯路。