uni-app x checkbox-group 多选框组组件完全指南属性、事件与表单联动机制【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app组件类型UniCheckboxGroupElement位于 docs/component/checkbox-group.md导读checkbox-group是 uni-app x 中用于承载多个checkbox子项的多选框组组件负责统一管理组内各复选框的选中状态并在设置name属性后以数组形式将选中值整体提交给form组件。读完本文你将掌握checkbox-group的属性与事件用法、UniCheckboxGroupChangeEvent事件数据结构、与form组件的提交/重置联动机制以及其底层源码实现原理与自动化测试用例。一、组件概述checkbox-group多选框组是单选场景的对偶组件radio-group保证组内互斥而checkbox-group允许多选。一个checkbox-group内可包含多个checkbox子组件组内任意子项选中状态变化时组会统一向外派发change事件。在仓库中该组件的官方实现位于 src/uni_modules/uni-form/components/checkbox-group/checkbox-group.uvue对应的子项组件实现位于 src/uni_modules/uni-form/components/checkbox/checkbox.uvue二者同属于uni-form表单组件族。核心能力给checkbox-group设置name属性后内部包含的多个checkbox将以数组的方式统一提交表单详见 form 组件文档。二、兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.9 | 4.11 | 4.61 |说明表格中的版本号为 uni-app x 引擎或 HBuilderX 对应能力的起始支持版本。App 侧Android/iOS/HarmonyOS在蒸汽模式Vapor下由源码注释标注了各自的最低版本iOS 5.11、Android 5.21、HarmonyOS 5.0见 checkbox-group.uvue 中的uniPlatform标注。三、属性详解| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :-: | :- | | name | string | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 表单的控件名称作为键值对的一部分与表单(form组件)一同提交 | | change | (event: UniCheckboxGroupChangeEvent) void | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | checkbox-group中选中项发生改变时触发 change 事件detail {value:[选中的checkbox的value的数组]} |namename是组与form表单联动的关键属性。只有在设置了name后组才会向父级form组件注册自己为表单字段。从源码看name的默认值为空字符串withDefaults中定义且注册逻辑判断了props.name非空见 checkbox-group.uvue。changechange事件在组内任意checkbox的选中状态变化时触发事件对象的detail.value为当前所有被选中子项的value组成的字符串数组。四、事件与数据类型UniCheckboxGroupChangeEventUniCheckboxGroupChangeEvent继承自UniCustomEventUniCheckboxGroupChangeEventDetail其泛型参数detail为UniCheckboxGroupChangeEventDetail。UniCheckboxGroupChangeEventDetail 的属性值| 名称 | 类型 | 必填 | | :- | :- | :- | | value | Arraystring | 是 |事件构造的源码实现在 checkbox-group.uvue 中可以看到事件类型的真实定义type UniCheckboxGroupChangeEventDetail { value : Arraystring } class UniCheckboxGroupChangeEvent extends UniCustomEventUniCheckboxGroupChangeEventDetail { constructor(value : Arraystring) { super(change, { value } as UniCheckboxGroupChangeEventDetail) } } const emit defineEmits{ change: [event: UniCheckboxGroupChangeEvent] }()关于 value 数组顺序的一个重要细节组内维护了elementOrderMap记录每个 value 的注册顺序与elementOrderCounter计数器派发事件时会先将选中值按元素注册顺序排序再发出从而保证detail.value的顺序与页面上复选框的排列顺序一致见 checkbox-group.uvue。五、与 form 表单的联动提交与重置checkbox-group是form组件支持的表单内容子组件之一其他还包括 input、textarea、radio、switch、slider 等见 form 组件文档。设置name后组的选中值数组会作为键值对的一部分随表单提交。表单字段注册在onMounted中若存在外层form上下文FORM_KEY且name非空组会调用formCtx.registerField注册自己formCtx.registerField({ name: props.name, getValue: () selectedValues.value.slice(), reset: () { // 通过保存的子项 setter 重置所有子 checkbox const initial new Setstring(initialSelected.value) selectedValues.value initialSelected.value.slice() childSetters.forEach((setChecked, val) { setChecked(initial.has(val)) }) dispatchEvent() } })对应接口定义在 types.uts 中export type FormField { name: string getValue: () any reset?: () void } export type FormContext { registerField: (field: FormField) void unregisterField: (name: string) void submit: () void reset: () void }提交策略form提交时收集所有已注册字段的getValue()结果checkbox-group对应提交一个数组{name: [值1, 值2, ...]}。注意 uni-app(x) 的提交策略与浏览器 W3C 标准存在差异提交数据是一个对象{name: value}而非浏览器标准的数组结构多个表单子项若name相同仅保留最后一个而checkbox-group由于整组共享同一个name其 value 是数组天然支持一个 key 对应多个值设置了disabled的表单子项仍然会提交与浏览器忽略 disabled 子项的策略不同。以上策略说明详见 form 组件文档 的「submit策略差异」小节。重置策略uni-app x 在 App3.97与 Web4.0平台上的reset策略为还原初始值。对应到checkbox-group即重置为首次注册时记录的初始选中集合源码中的initialSelected并回调每个子项保存的setChecked来同步子组件的 UI 状态最后再派发一次change事件见 checkbox-group.uvue。六、源码级原理剖析组如何管理子项checkbox-group与子项checkbox之间通过Provide/Inject上下文通信上下文 key 为CHECKBOX_GROUP_KEY定义于 common.uts类型为CheckboxGroupContext定义于 types.utsexport type CheckboxGroupContext { register: (value: string, checked: boolean, setChecked: (checked: boolean) void) void unregister: (value: string) void toggle: (value: string, checked: boolean, emitChange: boolean) void isChecked: (value: string) boolean name: string }工作流程注册register每个checkbox子项在onMounted时向组注册自己的value、初始选中状态以及一个setChecked回调用于组主动改子项状态如 reset 场景。组维护selectedValues数组和childSetters映射并记录首帧选中快照到initialSelected。切换toggle用户点击子项时子项调用group.toggle(value, checked, emitChange)更新selectedValues若emitChange为 true则组按元素顺序派发change事件见 checkbox.uvue。注销unregister子项卸载时调用group.unregister(value)从选中数组、setter 映射与顺序表中移除。子项checkbox自身的核心属性如disabled、checked、value、color/foreColor等详见 checkbox 组件文档。七、完整示例在表单中使用 checkbox-group以下示例提取自仓库示例页面 src/pages/component/checkbox/checkbox.uvue 与 form 示例展示了一个与form联动的完整多选场景template form submitonFormSubmit resetonFormReset view classuni-form-item text classtitle爱好可多选/text checkbox-group nameloves classflex-row changeonLovesChange view classgroup-item checkbox value0 :checkeddata.loves.indexOf(0) -1 /text classform-text读书/text /view view classgroup-item checkbox value1 :checkeddata.loves.indexOf(1) -1 /text classform-text写字/text /view view classgroup-item checkbox value2 :checkeddata.loves.indexOf(2) -1 /text classform-text运动/text /view /checkbox-group /view view classflex-row button classbtn btn-submit form-typesubmit typeprimarySubmit/button button classbtn btn-reset typedefault form-typeresetReset/button /view /form /template script setup languts type DataType { loves: string[] } const data reactive({ loves: [0], } as DataType) // 监听组内选中变化e.detail.value 为选中 value 数组 const onLovesChange (e: UniCheckboxGroupChangeEvent) { data.loves e.detail.value uni.showToast({ icon: none, title: 当前选中: e.detail.value.join(,), }) } // submit 时 e.detail.value.loves 即为选中数组 const onFormSubmit (e: UniFormSubmitEvent) { console.log(提交的爱好, e.detail.value[loves]) } const onFormReset (e: UniFormResetEvent) { // uni-app x App/Web 平台 reset 为还原初始值即还原到 0 被选中 } /script要点提示checkbox-group的name与子项checkbox的value是两个不同的键name决定提交时对象的 keyvalue决定数组内每个元素的值建议用label包裹checkbox与其文本便于点击文本也触发选中支付宝小程序不支持将文本或text放在checkbox内部需将文本作为同级节点用label包裹详见 checkbox 组件文档使用defineExpose暴露data便于自动化测试读取状态示例页面中的常规做法。八、自动化测试change 事件的验证仓库为 checkbox 示例页编写了完整的自动化测试 src/pages/component/checkbox/checkbox.test.js其中change用例直接验证了checkbox-group的事件行为it(change, async () { expect(await page.data(data.value)).toEqual([]) const cb1 await page.$(.cb1) await cb1.tap() await page.waitFor(100) expect(await page.data(data.value)).toEqual([cb, cb1]) // 依次选中 cb1 后value 为 [cb, cb1] const cb await page.$(.cb) await cb.tap() await page.waitFor(100) expect(await page.data(data.value)).toEqual([cb1]) // 取消 cb 后仅剩 cb1 const cb2 await page.$(.cb2) await cb2.tap() await page.waitFor(100) expect(await page.data(data.value)).toEqual([cb1]) // 点击禁用的 cb2 不生效 await cb1.tap() await page.waitFor(100) expect(await page.data(data.value)).toEqual([]) // 全部取消后为空数组 })从测试中可以确认三个行为事实选中值按元素注册顺序排列[cb, cb1]、disabled的子项点击不改变选中集合、事件派发的 value 始终是最新的选中数组。此外测试还验证了组内元素数量、disabled/checked属性绑定以及UniCheckboxGroupChangeEvent的触发e.target?.tagName CHECKBOX-GROUP。九、注意事项与最佳实践不设置 name 时仅用于状态管理checkbox-group即使不设置name也可以正常使用change做选中状态管理只是不会参与form提交。勿将自定义组件混入表单form目前只支持内置表单子组件提交自定义组件需自行绑定 data 并编码提交逻辑见 form 组件文档。value 的唯一性组内多个checkbox的value应保持唯一因为组以value作为选中集合的标识重复的value会导致ensureIncluded/ensureExcluded逻辑无法正确区分见 checkbox-group.uvue。点击事件委托checkbox子项的点击由自身处理并通过group.toggle同步到组无需在组上额外绑定点击事件。label 配合提升可用性将文本与checkbox放入label组件可扩大点击命中区域。参见form 表单组件文档表单提交与重置策略、表单内容子组件说明checkbox 组件文档子项属性disabled、checked、value、颜色体系等与示例代码label 组件文档提升可点击区域的辅助组件组件实现源码checkbox-group.uvue、checkbox.uvue、types.uts、common.uts示例与测试示例页面、自动化测试【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考