HarmonyOS6 半年磨一剑 - RcCheckboxGroup 组件与全选不确定态机制深度解析

文章目录前言一、RcCheckboxGroup 内部状态同步1.1 双层状态管理1.2 选中状态判断二、布局渲染架构2.1 横向与纵向的渲染分支2.2 itemGap 的类型安全处理2.3 属性透传机制三、全选与不确定态indeterminate3.1 三态状态机3.2 全选逻辑实现3.3 indeterminate 的渲染细节四、完整全选示例五、纵向列表带分隔线示例总结前言在多项选择场景中全选功能是用户体验的重要组成部分。当所有子项全部选中时全选框显示为选中当部分子项选中时全选框应显示为不确定状态通常是一个横线而非勾明确告知用户这是部分选中而非全部当没有子项选中时全选框为未选中。这三种状态构成了全选交互的完整状态机而RcCheckbox 的indeterminate参数正是为此而设计。本文将深入解析RcCheckboxGroup的内部状态同步机制、布局渲染架构以及如何与indeterminate配合构建完整的全选功能并提供多个完整可运行的实战示例。一、RcCheckboxGroup 内部状态同步1.1 双层状态管理RcCheckboxGroup同样采用受控模式 内部副本的双状态策略// 外部传入的受控状态ParamRequirecheckedValues:RcCheckboxValue[][]// 内部副本驱动 UI 渲染LocalrcCheckboxGroupInnerValues:RcCheckboxValue[][]// 初始化aboutToAppear():void{this.rcCheckboxGroupInnerValues[...this.checkedValues]}// 外部变化时同步使用 JSON 深比较避免无效更新aboutToRecycle():void{if(JSON.stringify(this.checkedValues)!JSON.stringify(this.rcCheckboxGroupInnerValues)){this.rcCheckboxGroupInnerValues[...this.checkedValues]}}使用展开运算符[...this.checkedValues]创建数组副本保证内外状态引用独立互不影响。1.2 选中状态判断privateisRcCheckboxChecked(value:RcCheckboxValue):boolean{returnthis.rcCheckboxGroupInnerValues.some(vvvalue)}使用Array.some 严格相等判断某个值是否已选中支持string、number、boolean三种类型的精确比较。二、布局渲染架构2.1 横向与纵向的渲染分支RcCheckboxGroup根据placement参数选择完全不同的容器组件build(){if(this.placementcolumn){// 纵向布局Column 容器支持下划线分隔Column({space:this.getRcCheckboxGroupItemGap()}){ForEach(this.options,(option:RcCheckboxOption,index:number){Column(){RcCheckbox({...})// 可选下划线非最后一项时显示if(this.showBorderBottomindexthis.options.length-1){Divider().color(#EBEEF5).strokeWidth(1).margin({top:this.getRcCheckboxGroupItemGap()/2})}}.width(100%)})}}else{// 横向布局Row 容器自动换行Row({space:this.getRcCheckboxGroupItemGap()}){ForEach(this.options,(option:RcCheckboxOption){RcCheckbox({...})})}}}两种布局的渲染差异对比项row横向column纵向容器RowColumn分隔线不支持showBorderBottom: true时显示宽度自适应内容子项宽度 100%适用场景选项较少、水平空间充足选项较多、移动端列表2.2 itemGap 的类型安全处理privategetRcCheckboxGroupItemGap():number{returntypeofthis.itemGapnumber?this.itemGap:Number(this.itemGap)||12}itemGap支持RcStringNumber数字或数字字符串通过|| 12的兜底处理确保非法输入时使用默认值 12不会因为类型转换失败导致布局异常。2.3 属性透传机制Group 会将所有样式相关参数完整传递给每个子RcCheckboxRcCheckbox({checkboxValue:option.value,checkboxLabel:option.label,checked:this.isRcCheckboxChecked(option.value),onCheckedChange:(checked:boolean){this.handleRcCheckboxGroupChange(option.value,checked)},// 透传组级样式参数disabled:this.disabled||option.disabled||false,// 组禁用 OR 项禁用checkboxShape:this.checkboxGroupShape,checkboxSize:this.checkboxGroupSize,activeColor:this.activeColor,inactiveColor:this.inactiveColor,iconColor:this.iconColor,iconSize:this.iconSize,labelColor:this.labelColor,labelSize:this.labelSize,labelDisabled:this.labelDisabled,iconPlacement:this.iconPlacement,isButton:this.isButton,showBorder:this.showBorder})disabled的合并逻辑特别值得注意this.disabled || option.disabled || false组级禁用和项级禁用取逻辑或任意一个为true该项就禁用完美支持了整组禁用和单项禁用两种场景。三、全选与不确定态indeterminate3.1 三态状态机全选功能需要维护三个独立状态全不选checkAllfalse, isIndeterminatefalse | | 选中部分 v 部分选checkAllfalse, isIndeterminatetrue | | 选中全部 v 全选checkAlltrue, isIndeterminatefalse三态之间的转换是互斥的checkAll和isIndeterminate不能同时为true。3.2 全选逻辑实现// 全选框点击时handleCheckAll(checked:boolean){if(checked){this.allItemValuesthis.allItemOptions.map(itemitem.value)// 全选}else{this.allItemValues[]// 全不选}this.checkAllcheckedthis.isIndeterminatefalse// 点击全选后不确定态必须清除}// 子项变化时重新计算全选状态handleAllItemsChange(values:RcCheckboxValue[]){this.allItemValuesvaluesthis.checkAllvalues.lengththis.allItemOptions.length// 全选this.isIndeterminatevalues.length0values.lengththis.allItemOptions.length// 部分选}3.3 indeterminate 的渲染细节BuilderrenderRcCheckboxIcon(){Stack({alignContent:Alignment.Center}){if(this.indeterminate){// 不确定状态显示横线if(this.customIndeterminateIcon){RcIcon({name:this.customIndeterminateIcon,...})}else{Rect().width(this.getRcCheckboxIconSize()).height(2).fill(this.iconColor)}}elseif(this.rcCheckboxInnerChecked){// 选中状态显示勾...}// 未选中什么都不显示}}indeterminate的优先级高于rcCheckboxInnerChecked当两者同时为true时显示横线而非勾。这符合全选场景中全选框处于不确定态时 checked 仍为 true 但视觉应显示横线的业务逻辑。四、完整全选示例import{RcCheckbox,RcCheckboxGroup,RcCheckboxOption,RcCheckboxValue}fromrchouiEntryComponentstruct CheckAllExample{StatecheckAll:booleanfalseStateisIndeterminate:booleanfalseStateselectedValues:RcCheckboxValue[][]privateallOptions:RcCheckboxOption[][{value:item1,label:前端开发},{value:item2,label:后端开发},{value:item3,label:UI设计},{value:item4,label:产品规划}]handleCheckAll(checked:boolean){this.checkAllcheckedthis.isIndeterminatefalsethis.selectedValueschecked?this.allOptions.map(oo.value):[]}handleGroupChange(values:RcCheckboxValue[]){this.selectedValuesvaluesthis.checkAllvalues.lengththis.allOptions.lengththis.isIndeterminatevalues.length0values.lengththis.allOptions.length}build(){Column({space:20}){Text(全选功能演示).fontSize(20).fontWeight(FontWeight.Bold)// 全选框Column(){RcCheckbox({checkboxLabel:全选点击可全选/全不选,checked:this.checkAll,indeterminate:this.isIndeterminate,checkboxSize:large,onCheckedChange:this.handleCheckAll})}.width(100%).padding({top:12,bottom:12,left:16,right:16}).backgroundColor(#FFFFFF).borderRadius(8)Divider().color(#EBEEF5)// 子项列表RcCheckboxGroup({options:this.allOptions,placement:column,showBorderBottom:true,itemGap:16,checkedValues:this.selectedValues,onCheckedValuesChange:this.handleGroupChange})// 状态说明Row({space:8}){Text(已选${this.selectedValues.length}/${this.allOptions.length}项).fontSize(14).fontColor(#606266)if(this.isIndeterminate){Text(部分选中).fontSize(12).fontColor(#E6A23C).padding({left:6,right:6,top:2,bottom:2}).backgroundColor(#FDF6EC).borderRadius(4)}elseif(this.checkAll){Text(已全选).fontSize(12).fontColor(#67C23A).padding({left:6,right:6,top:2,bottom:2}).backgroundColor(#F0F9EB).borderRadius(4)}}// 已选内容if(this.selectedValues.length0){Text(已选内容${this.selectedValues.join(、)}).fontSize(13).fontColor(#909399)}}.padding(20).width(100%).height(100%).backgroundColor(#F5F7FA)}}五、纵向列表带分隔线示例import{RcCheckboxGroup,RcCheckboxOption,RcCheckboxValue}fromrchouiEntryComponentstruct ColumnGroupExample{StatehobbyValues:RcCheckboxValue[][reading]privatehobbyOptions:RcCheckboxOption[][{value:reading,label:阅读},{value:music,label:音乐},{value:sports,label:运动,disabled:true},{value:travel,label:旅行},{value:cooking,label:烹饪}]build(){Column({space:16}){Text(兴趣爱好纵向带分隔线).fontSize(18).fontWeight(FontWeight.Bold)Column(){RcCheckboxGroup({options:this.hobbyOptions,placement:column,showBorderBottom:true,itemGap:16,checkedValues:this.hobbyValues,onCheckedValuesChange:(values:RcCheckboxValue[]){this.hobbyValuesvalues}})}.padding(16).backgroundColor(#FFFFFF).borderRadius(8)Text(已选${this.hobbyValues.length}项运动已禁用).fontSize(13).fontColor(#909399)}.padding(20).width(100%).height(100%).backgroundColor(#F5F7FA)}}总结RcCheckboxGroup通过双层状态管理外部受控 内部副本和属性透传机制实现了对多个子复选框的统一管理。showBorderBottom的分隔线设计和itemGap的间距控制使纵向列表的视觉层次清晰可控。indeterminate参数是全选功能的灵魂——它的优先级高于checked用横线明确区分全选与部分选两种不同的语义是提升表单易用性的关键细节。在实际项目中全选、部分选、全不选三态的计算逻辑需要开发者在外部维护组件只负责忠实渲染职责分离清晰。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是我持续创作的动力