鸿蒙 uni-app x checkbox 多选适配与踩坑解析

鸿蒙专家

在鸿蒙平台上用 uni-app x 开发表单时，多选框是高频组件。鸿蒙 4.61 开始支持 checkbox-group，它需要与 checkbox 配合使用：checkbox 放在 checkbox-group 内，由 checkbox-group 监听 change 事件获取选中的 value 数组。需要注意的是，checkbox 组件的兼容性表里没有鸿蒙，但 checkbox-group 支持鸿蒙，实际项目中两者配合即可正常工作。

兼容性与属性方面，有几个关键点：checkbox 必须放在 checkbox-group 里才能正常工作，单独使用无法获取选中状态；每个 checkbox 必须设置 value，否则 change 事件返回的是空字符串；color 和 iconColor 已废弃，应改用 foreColor，否则控制台会出现警告。

基础多选写法如下：

2. <template>
3. <checkbox-group @change="onChange">
4.   <checkbox value="apple">苹果</checkbox>
5.   <checkbox value="banana">香蕉</checkbox>
6.   <checkbox value="orange">橙子</checkbox>
7. </checkbox-group>
8. <text>选中：{{selected}}</text>
9. </template>
10. <script setup lang="uts">
11. const selected = ref('')
12. const onChange = (event: UniCheckboxGroupChangeEvent) => {
13.   selected.value = event.detail.value.join(', ')
14. }
15. </script>

复制代码

默认选中通过 checked 属性实现，禁用通过 disabled 属性实现。注意 checked 只是初始状态，用户点击后选中状态由组件内部管理，不能通过动态修改 checked 来控制。

2. <checkbox-group>
3.   <checkbox value="agree" checked>同意用户协议</checkbox>
4.   <checkbox value="newsletter">订阅邮件通知</checkbox>
5.   <checkbox value="option3" disabled>禁用项</checkbox>
6.   <checkbox value="option4" disabled checked>禁用且选中</checkbox>
7. </checkbox-group>

复制代码

自定义样式可设置 foreColor、backgroundColor、borderColor、activeBackgroundColor、activeBorderColor 等属性。鸿蒙平台 checkbox 的默认样式可能与其他平台略有差异，建议通过这些属性统一自定义。

2. <checkbox value="custom1"
3.   foreColor="#9C27B0"
4.   backgroundColor="#F3E5F5"
5.   borderColor="#CE93D8"
6.   activeBackgroundColor="#E1BEE7"
7.   activeBorderColor="#9C27B0"
8.   checked>紫色主题</checkbox>

复制代码

列表多选是常见场景，用 v-for 渲染数据源，并给 checkbox 绑定 value 和 checked。

2. <checkbox-group @change="onHobbyChange">
3.   <view v-for="(item, index) in hobbies" :key="index">
4.     <checkbox :value="item.value" :checked="item.checked"></checkbox>
5.     <text>{{item.name}}</text>
6.   </view>
7. </checkbox-group>
8. <script setup lang="uts">
9. type Hobby = {
10.   name: string
11.   value: string
12.   checked: boolean
13. }
14. const hobbies = ref([
15.   { name: '阅读', value: 'reading', checked: false },
16.   { name: '运动', value: 'sports', checked: true },
17.   { name: '音乐', value: 'music', checked: false }
18. ] as Array<Hobby>)
19. const selectedHobbies = ref('')
20. const onHobbyChange = (event: UniCheckboxGroupChangeEvent) => {
21.   selectedHobbies.value = event.detail.value.join(', ')
22. }
23. </script>

复制代码

表单提交场景中，给 checkbox-group 设置 name，配合 form 的 submit 事件获取表单数据。

2. <form @submit="onSubmit">
3.   <checkbox-group name="services">
4.     <checkbox value="delivery">送货上门</checkbox>
5.     <checkbox value="install">安装服务</checkbox>
6.     <checkbox value="warranty">延长保修</checkbox>
7.   </checkbox-group>
8.   <button form-type="submit" type="primary">提交</button>
9. </form>
10. <script setup lang="uts">
11. const onSubmit = (event: UniFormSubmitEvent) => {
12.   console.log('表单数据:', event.detail.value)
13. }
14. </script>

复制代码

全选、反选和清空需要修改数据源的 checked 属性，然后通过 v-for 重新渲染，不能直接操作 DOM。change 事件只在用户点击时触发。

2. <button @click="selectAll">全选</button>
3. <button @click="invertSelect">反选</button>
4. <button @click="clearAll">清空</button>
5. <checkbox-group @change="onChange">
6.   <view v-for="(item, index) in items" :key="index">
7.     <checkbox :value="item.value" :checked="item.checked"></checkbox>
8.     <text>{{item.name}}</text>
9.   </view>
10. </checkbox-group>
11. <script setup lang="uts">
12. const items = ref([
13.   { name: '选项 A', value: 'a', checked: false },
14.   { name: '选项 B', value: 'b', checked: false },
15.   { name: '选项 C', value: 'c', checked: false }
16. ])
17. const selectAll = () => {
18.   items.value.forEach(item => { item.checked = true })
19. }
20. const invertSelect = () => {
21.   items.value.forEach(item => { item.checked = !item.checked })
22. }
23. const clearAll = () => {
24.   items.value.forEach(item => { item.checked = false })
25. }
26. const selectedCount = ref(0)
27. const onChange = (event: UniCheckboxGroupChangeEvent) => {
28.   selectedCount.value = event.detail.value.length
29. }
30. </script>

复制代码

与鸿蒙原生开发对比，鸿蒙原生多选使用 Checkbox 组件，写法如下：

2. Checkbox({ name: 'apple', group: 'fruits' })
3.   .select(true)
4.   .selectedColor('#2196F3')
5.   .onChange((value: boolean) => {
6.     console.log('选中状态:', value)
7.   })

复制代码

对比下来，uni-app x 的 checkbox 用属性控制样式，跟 checkbox-group 配合获取选中值，写法更统一。

踩坑记录汇总：checkbox 必须放在 checkbox-group 里；value 必须设置；color 和 iconColor 已废弃，使用 foreColor；checked 只是初始状态；全选/反选需要修改数据源；checkbox-group 的 change 事件只在用户点击时触发。在鸿蒙平台适配时，重点关注这些差异，可以避免大部分常见问题。