uni-app x checkbox-group 多選框組組件完全指南屬性、事件與表單聯(lián)動(dòng)機(jī)制【免費(fèi)下載鏈接】uni-appA cross-platform framework using Vue.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/un/uni-app組件類型UniCheckboxGroupElement位于 docs/component/checkbox-group.md導(dǎo)讀checkbox-group是 uni-app x 中用于承載多個(gè)checkbox子項(xiàng)的多選框組組件負(fù)責(zé)統(tǒng)一管理組內(nèi)各復(fù)選框的選中狀態(tài)并在設(shè)置name屬性后以數(shù)組形式將選中值整體提交給form組件。讀完本文你將掌握checkbox-group的屬性與事件用法、UniCheckboxGroupChangeEvent事件數(shù)據(jù)結(jié)構(gòu)、與form組件的提交/重置聯(lián)動(dòng)機(jī)制以及其底層源碼實(shí)現(xiàn)原理與自動(dòng)化測(cè)試用例。一、組件概述checkbox-group多選框組是單選場(chǎng)景的對(duì)偶組件radio-group保證組內(nèi)互斥而checkbox-group允許多選。一個(gè)checkbox-group內(nèi)可包含多個(gè)checkbox子組件組內(nèi)任意子項(xiàng)選中狀態(tài)變化時(shí)組會(huì)統(tǒng)一向外派發(fā)change事件。在倉庫中該組件的官方實(shí)現(xiàn)位于 src/uni_modules/uni-form/components/checkbox-group/checkbox-group.uvue對(duì)應(yīng)的子項(xiàng)組件實(shí)現(xiàn)位于 src/uni_modules/uni-form/components/checkbox/checkbox.uvue二者同屬于uni-form表單組件族。核心能力給checkbox-group設(shè)置name屬性后內(nèi)部包含的多個(gè)checkbox將以數(shù)組的方式統(tǒng)一提交表單詳見 form 組件文檔。二、兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.9 | 4.11 | 4.61 |說明表格中的版本號(hào)為 uni-app x 引擎或 HBuilderX 對(duì)應(yīng)能力的起始支持版本。App 側(cè)Android/iOS/HarmonyOS在蒸汽模式Vapor下由源碼注釋標(biāo)注了各自的最低版本iOS 5.11、Android 5.21、HarmonyOS 5.0見 checkbox-group.uvue 中的uniPlatform標(biāo)注。三、屬性詳解| 名稱 | 類型 | 兼容性 | 描述 | | :- | :- | :-: | :- | | name | string | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 表單的控件名稱作為鍵值對(duì)的一部分與表單(form組件)一同提交 | | change | (event: UniCheckboxGroupChangeEvent) void | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | checkbox-group中選中項(xiàng)發(fā)生改變時(shí)觸發(fā) change 事件detail {value:[選中的checkbox的value的數(shù)組]} |namename是組與form表單聯(lián)動(dòng)的關(guān)鍵屬性。只有在設(shè)置了name后組才會(huì)向父級(jí)form組件注冊(cè)自己為表單字段。從源碼看name的默認(rèn)值為空字符串withDefaults中定義且注冊(cè)邏輯判斷了props.name非空見 checkbox-group.uvue。changechange事件在組內(nèi)任意checkbox的選中狀態(tài)變化時(shí)觸發(fā)事件對(duì)象的detail.value為當(dāng)前所有被選中子項(xiàng)的value組成的字符串?dāng)?shù)組。四、事件與數(shù)據(jù)類型UniCheckboxGroupChangeEventUniCheckboxGroupChangeEvent繼承自UniCustomEventUniCheckboxGroupChangeEventDetail其泛型參數(shù)detail為UniCheckboxGroupChangeEventDetail。UniCheckboxGroupChangeEventDetail 的屬性值| 名稱 | 類型 | 必填 | | :- | :- | :- | | value | Arraystring | 是 |事件構(gòu)造的源碼實(shí)現(xiàn)在 checkbox-group.uvue 中可以看到事件類型的真實(shí)定義type UniCheckboxGroupChangeEventDetail { value : Arraystring } class UniCheckboxGroupChangeEvent extends UniCustomEventUniCheckboxGroupChangeEventDetail { constructor(value : Arraystring) { super(change, { value } as UniCheckboxGroupChangeEventDetail) } } const emit defineEmits{ change: [event: UniCheckboxGroupChangeEvent] }()關(guān)于 value 數(shù)組順序的一個(gè)重要細(xì)節(jié)組內(nèi)維護(hù)了elementOrderMap記錄每個(gè) value 的注冊(cè)順序與elementOrderCounter計(jì)數(shù)器派發(fā)事件時(shí)會(huì)先將選中值按元素注冊(cè)順序排序再發(fā)出從而保證detail.value的順序與頁面上復(fù)選框的排列順序一致見 checkbox-group.uvue。五、與 form 表單的聯(lián)動(dòng)提交與重置checkbox-group是form組件支持的表單內(nèi)容子組件之一其他還包括 input、textarea、radio、switch、slider 等見 form 組件文檔。設(shè)置name后組的選中值數(shù)組會(huì)作為鍵值對(duì)的一部分隨表單提交。表單字段注冊(cè)在onMounted中若存在外層form上下文FORM_KEY且name非空組會(huì)調(diào)用formCtx.registerField注冊(cè)自己formCtx.registerField({ name: props.name, getValue: () selectedValues.value.slice(), reset: () { // 通過保存的子項(xiàng) setter 重置所有子 checkbox const initial new Setstring(initialSelected.value) selectedValues.value initialSelected.value.slice() childSetters.forEach((setChecked, val) { setChecked(initial.has(val)) }) dispatchEvent() } })對(duì)應(yīng)接口定義在 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提交時(shí)收集所有已注冊(cè)字段的getValue()結(jié)果checkbox-group對(duì)應(yīng)提交一個(gè)數(shù)組{name: [值1, 值2, ...]}。注意 uni-app(x) 的提交策略與瀏覽器 W3C 標(biāo)準(zhǔn)存在差異提交數(shù)據(jù)是一個(gè)對(duì)象{name: value}而非瀏覽器標(biāo)準(zhǔn)的數(shù)組結(jié)構(gòu)多個(gè)表單子項(xiàng)若name相同僅保留最后一個(gè)而checkbox-group由于整組共享同一個(gè)name其 value 是數(shù)組天然支持一個(gè) key 對(duì)應(yīng)多個(gè)值設(shè)置了disabled的表單子項(xiàng)仍然會(huì)提交與瀏覽器忽略 disabled 子項(xiàng)的策略不同。以上策略說明詳見 form 組件文檔 的「submit策略差異」小節(jié)。重置策略u(píng)ni-app x 在 App3.97與 Web4.0平臺(tái)上的reset策略為還原初始值。對(duì)應(yīng)到checkbox-group即重置為首次注冊(cè)時(shí)記錄的初始選中集合源碼中的initialSelected并回調(diào)每個(gè)子項(xiàng)保存的setChecked來同步子組件的 UI 狀態(tài)最后再派發(fā)一次change事件見 checkbox-group.uvue。六、源碼級(jí)原理剖析組如何管理子項(xiàng)checkbox-group與子項(xiàng)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 }工作流程注冊(cè)register每個(gè)checkbox子項(xiàng)在onMounted時(shí)向組注冊(cè)自己的value、初始選中狀態(tài)以及一個(gè)setChecked回調(diào)用于組主動(dòng)改子項(xiàng)狀態(tài)如 reset 場(chǎng)景。組維護(hù)selectedValues數(shù)組和childSetters映射并記錄首幀選中快照到initialSelected。切換toggle用戶點(diǎn)擊子項(xiàng)時(shí)子項(xiàng)調(diào)用group.toggle(value, checked, emitChange)更新selectedValues若emitChange為 true則組按元素順序派發(fā)change事件見 checkbox.uvue。注銷unregister子項(xiàng)卸載時(shí)調(diào)用group.unregister(value)從選中數(shù)組、setter 映射與順序表中移除。子項(xiàng)checkbox自身的核心屬性如disabled、checked、value、color/foreColor等詳見 checkbox 組件文檔。七、完整示例在表單中使用 checkbox-group以下示例提取自倉庫示例頁面 src/pages/component/checkbox/checkbox.uvue 與 form 示例展示了一個(gè)與form聯(lián)動(dòng)的完整多選場(chǎng)景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運(yùn)動(dòng)/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) // 監(jiān)聽組內(nèi)選中變化e.detail.value 為選中 value 數(shù)組 const onLovesChange (e: UniCheckboxGroupChangeEvent) { data.loves e.detail.value uni.showToast({ icon: none, title: 當(dāng)前選中: e.detail.value.join(,), }) } // submit 時(shí) e.detail.value.loves 即為選中數(shù)組 const onFormSubmit (e: UniFormSubmitEvent) { console.log(提交的愛好, e.detail.value[loves]) } const onFormReset (e: UniFormResetEvent) { // uni-app x App/Web 平臺(tái) reset 為還原初始值即還原到 0 被選中 } /script要點(diǎn)提示checkbox-group的name與子項(xiàng)checkbox的value是兩個(gè)不同的鍵name決定提交時(shí)對(duì)象的 keyvalue決定數(shù)組內(nèi)每個(gè)元素的值建議用label包裹c(diǎn)heckbox與其文本便于點(diǎn)擊文本也觸發(fā)選中支付寶小程序不支持將文本或text放在checkbox內(nèi)部需將文本作為同級(jí)節(jié)點(diǎn)用label包裹詳見 checkbox 組件文檔使用defineExpose暴露data便于自動(dòng)化測(cè)試讀取狀態(tài)示例頁面中的常規(guī)做法。八、自動(dòng)化測(cè)試change 事件的驗(yàn)證倉庫為 checkbox 示例頁編寫了完整的自動(dòng)化測(cè)試 src/pages/component/checkbox/checkbox.test.js其中change用例直接驗(yàn)證了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]) // 點(diǎn)擊禁用的 cb2 不生效 await cb1.tap() await page.waitFor(100) expect(await page.data(data.value)).toEqual([]) // 全部取消后為空數(shù)組 })從測(cè)試中可以確認(rèn)三個(gè)行為事實(shí)選中值按元素注冊(cè)順序排列[cb, cb1]、disabled的子項(xiàng)點(diǎn)擊不改變選中集合、事件派發(fā)的 value 始終是最新的選中數(shù)組。此外測(cè)試還驗(yàn)證了組內(nèi)元素?cái)?shù)量、disabled/checked屬性綁定以及UniCheckboxGroupChangeEvent的觸發(fā)e.target?.tagName CHECKBOX-GROUP。九、注意事項(xiàng)與最佳實(shí)踐不設(shè)置 name 時(shí)僅用于狀態(tài)管理checkbox-group即使不設(shè)置name也可以正常使用change做選中狀態(tài)管理只是不會(huì)參與form提交。勿將自定義組件混入表單form目前只支持內(nèi)置表單子組件提交自定義組件需自行綁定 data 并編碼提交邏輯見 form 組件文檔。value 的唯一性組內(nèi)多個(gè)checkbox的value應(yīng)保持唯一因?yàn)榻M以value作為選中集合的標(biāo)識(shí)重復(fù)的value會(huì)導(dǎo)致ensureIncluded/ensureExcluded邏輯無法正確區(qū)分見 checkbox-group.uvue。點(diǎn)擊事件委托checkbox子項(xiàng)的點(diǎn)擊由自身處理并通過group.toggle同步到組無需在組上額外綁定點(diǎn)擊事件。label 配合提升可用性將文本與checkbox放入label組件可擴(kuò)大點(diǎn)擊命中區(qū)域。參見form 表單組件文檔表單提交與重置策略、表單內(nèi)容子組件說明checkbox 組件文檔子項(xiàng)屬性disabled、checked、value、顏色體系等與示例代碼label 組件文檔提升可點(diǎn)擊區(qū)域的輔助組件組件實(shí)現(xiàn)源碼checkbox-group.uvue、checkbox.uvue、types.uts、common.uts示例與測(cè)試示例頁面、自動(dòng)化測(cè)試【免費(fèi)下載鏈接】uni-appA cross-platform framework using Vue.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/un/uni-app創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考