鸿蒙 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，否则控制台会出现警告。
基础多选写法如下：
<template>
<checkbox-group @change="onChange">
<checkbox value="apple">苹果</checkbox>
<checkbox value="banana">香蕉</checkbox>
<checkbox value="orange">橙子</checkbox>
</checkbox-group>
<text>选中：{{selected}}</text>
</template>
<script setup lang="uts">
const selected = ref('')
const onChange = (event: UniCheckboxGroupChangeEvent) => {
selected.value = event.detail.value.join(', ')
}
</script>
默认选中通过 checked 属性实现，禁用通过 disabled 属性实现。注意 checked 只是初始状态，用户点击后选中状态由组件内部管理，不能通过动态修改 checked 来控制。
<checkbox-group>
<checkbox value="agree" checked>同意用户协议</checkbox>
<checkbox value="newsletter">订阅邮件通知</checkbox>
<checkbox value="option3" disabled>禁用项</checkbox>
<checkbox value="option4" disabled checked>禁用且选中</checkbox>
</checkbox-group>
自定义样式可设置 foreColor、backgroundColor、borderColor、activeBackgroundColor、activeBorderColor 等属性。鸿蒙平台 checkbox 的默认样式可能与其他平台略有差异，建议通过这些属性统一自定义。
<checkbox value="custom1"
foreColor="#9C27B0"
backgroundColor="#F3E5F5"
borderColor="#CE93D8"
activeBackgroundColor="#E1BEE7"
activeBorderColor="#9C27B0"
checked>紫色主题</checkbox>
列表多选是常见场景，用 v-for 渲染数据源，并给 checkbox 绑定 value 和 checked。
<checkbox-group @change="onHobbyChange">
<view v-for="(item, index) in hobbies" :key="index">
<checkbox :value="item.value" :checked="item.checked"></checkbox>
<text>{{item.name}}</text>
</view>
</checkbox-group>
<script setup lang="uts">
type Hobby = {
name: string
value: string
checked: boolean
}
const hobbies = ref([
{ name: '阅读', value: 'reading', checked: false },
{ name: '运动', value: 'sports', checked: true },
{ name: '音乐', value: 'music', checked: false }
] as Array<Hobby>)
const selectedHobbies = ref('')
const onHobbyChange = (event: UniCheckboxGroupChangeEvent) => {
selectedHobbies.value = event.detail.value.join(', ')
}
</script>
表单提交场景中，给 checkbox-group 设置 name，配合 form 的 submit 事件获取表单数据。
<form @submit="onSubmit">
<checkbox-group name="services">
<checkbox value="delivery">送货上门</checkbox>
<checkbox value="install">安装服务</checkbox>
<checkbox value="warranty">延长保修</checkbox>
</checkbox-group>
<button form-type="submit" type="primary">提交</button>
</form>
<script setup lang="uts">
const onSubmit = (event: UniFormSubmitEvent) => {
console.log('表单数据:', event.detail.value)
}
</script>
全选、反选和清空需要修改数据源的 checked 属性，然后通过 v-for 重新渲染，不能直接操作 DOM。change 事件只在用户点击时触发。
<button @click="selectAll">全选</button>
<button @click="invertSelect">反选</button>
<button @click="clearAll">清空</button>
<checkbox-group @change="onChange">
<view v-for="(item, index) in items" :key="index">
<checkbox :value="item.value" :checked="item.checked"></checkbox>
<text>{{item.name}}</text>
</view>
</checkbox-group>
<script setup lang="uts">
const items = ref([
{ name: '选项 A', value: 'a', checked: false },
{ name: '选项 B', value: 'b', checked: false },
{ name: '选项 C', value: 'c', checked: false }
])
const selectAll = () => {
items.value.forEach(item => { item.checked = true })
}
const invertSelect = () => {
items.value.forEach(item => { item.checked = !item.checked })
}
const clearAll = () => {
items.value.forEach(item => { item.checked = false })
}
const selectedCount = ref(0)
const onChange = (event: UniCheckboxGroupChangeEvent) => {
selectedCount.value = event.detail.value.length
}
</script>
与鸿蒙原生开发对比，鸿蒙原生多选使用 Checkbox 组件，写法如下：
Checkbox({ name: 'apple', group: 'fruits' })
.select(true)
.selectedColor('#2196F3')
.onChange((value: boolean) => {
console.log('选中状态:', value)
})
对比下来，uni-app x 的 checkbox 用属性控制样式，跟 checkbox-group 配合获取选中值，写法更统一。
踩坑记录汇总：checkbox 必须放在 checkbox-group 里；value 必须设置；color 和 iconColor 已废弃，使用 foreColor；checked 只是初始状态；全选/反选需要修改数据源；checkbox-group 的 change 事件只在用户点击时触发。在鸿蒙平台适配时，重点关注这些差异，可以避免大部分常见问题。
Re: 鸿蒙 uni-app x checkbox 多选适配与踩坑解析
感谢分享，正好在鸿蒙上做 uni-app x 表单，checkbox 这块确实容易踩坑。你提到的几个点很关键：checkbox 必须放在 checkbox-group 里、value 不能省、color 和 iconColor 要换成 foreColor，还有 checked 只是初始状态，动态修改它不能控制选中状态。这些之前很容易忽略。列表多选用 v-for 配合 checked 初始值的写法很实用，表单提交那里好像还没贴完，期待把 onSubmit 里怎么取 services 的完整示例补上。默认样式差异这个提醒也很及时，用 foreColor、backgroundColor、borderColor 这些属性统一处理能省不少调试时间，整体写得很清晰，收藏了。Re: 鸿蒙 uni-app x checkbox 多选适配与踩坑解析
感谢分享，正好最近在鸿蒙上做 uni-app x 表单，checkbox 单独用拿不到选中值这个坑我也碰到了。按 checkbox-group 包起来、每个 checkbox 给 value 之后，change 里就能拿到选中数组，确实顺了很多。foreColor 替换 color 和 iconColor 也很有用，之前控制台一直警告。checked 只是初始状态、不能靠动态改它控制选中状态这点特别关键，列表多选初始化选中能用，但后续交互还是得听 change。表单提交那段如果楼主后续能补完就更好了，想确认一下 checkbox-group 设置 name 后，submit 里拿到的 services 是不是选中的 value 数组。整体很实用，对鸿蒙端适配帮助很大。Re: 鸿蒙 uni-app x checkbox 多选适配与踩坑解析
感谢分享，这篇对鸿蒙 uni-app x 的 checkbox 多选踩坑整理得很清楚。checkbox 必须放在 checkbox-group 里、每个 checkbox 都要设 value、foreColor 替代废弃的 color 和 iconColor，这几个点很关键，尤其是 change 返回空字符串那个坑。checked 只作初始状态、不能动态修改控制选中，也提醒得很及时。默认选中、禁用、自定义样式、v-for 列表多选和 form 提交这些场景覆盖得挺全。想问下后面动态回显选中项时，是不是只能初始化 checked 加自己维护 value 数组？form submit 里 checkbox-group 的 name 对应值是什么结构，首帖没展开，方便的话可以再补一段。
页:
[1]