15.ArkUI Checkbox的介绍和使用

以下是 ArkUI Checkbox 组件的详细介绍和使用指南：

---

一、Checkbox 基础介绍

功能特性：

• 提供二态选择（选中/未选中）
• 支持自定义样式和标签布局
• 支持与数据状态绑定
• 提供状态变化事件回调

适用场景：

• 表单中的多选操作
• 设置选项开关
• 列表项选择控制
• 需要二元选择的交互场景

---

二、基础用法

1. 创建基本 Checkbox

@Entry
@Component
struct CheckboxExample {@State isChecked: boolean = falsebuild() {Column() {Checkbox({ name: 'agree', checked: this.isChecked }).onChange((value: boolean) => {this.isChecked = valueconsole.log('当前状态：', value ? '选中' : '未选中')}).width(200).height(40)}}
}

2. 带标签的 Checkbox

Checkbox({ name: 'terms', checked: this.agreeTerms }).selectedColor('#007AFF') // 选中颜色.unselectedColor('#CCCCCC') // 未选中颜色.label('同意用户协议') // 标签文字.labelPosition(LabelPosition.Right) // 标签位置

---

三、高级功能

1. 多选组管理

@State checkedItems: boolean[] = [false, false, false]build() {Column() {ForEach(this.checkedItems, (item, index) => {Checkbox().checked(this.checkedItems[index]).onChange((value) => {this.checkedItems[index] = value}).label(`选项 ${index + 1}`)})}
}

2. 自定义样式

Checkbox().size({ width: 30, height: 30 }) // 设置尺寸.shape(CheckBoxShape.Circle) // 圆形样式.selectedIcon($r('app.media.custom_check')) // 自定义选中图标.unselectedIcon($r('app.media.custom_uncheck')) // 自定义未选中图标

3. 禁用状态

Checkbox().checked(false).enabled(false) // 禁用交互.label('不可用选项')

---

四、状态管理

1. 双向绑定

@State agreePrivacy: boolean = falseCheckbox().checked(this.agreePrivacy).onChange((value) => {this.agreePrivacy = value})

2. 结合 @Prop

@Component
struct CheckboxItem {@Prop checked: booleanbuild() {Checkbox().checked(this.checked).onChange((value) => {this.checked = value})}
}

---

五、实战示例 - 设置选项

@Entry
@Component
struct SettingsView {@State settings = {notification: true,darkMode: false,autoUpdate: true}build() {Column({ spacing: 20 }) {// 通知开关Checkbox().checked(this.settings.notification).onChange((value) => {this.settings.notification = value// 实际业务逻辑...}).label('接收通知').selectedColor('#34C759')// 深色模式Checkbox().checked(this.settings.darkMode).onChange((value) => {this.settings.darkMode = value// 切换主题逻辑...}).label('深色模式').selectedColor('#5856D6')// 自动更新Checkbox().checked(this.settings.autoUpdate).enabled(this.settings.notification) // 依赖通知开关.onChange((value) => {this.settings.autoUpdate = value}).label('自动更新')}.padding(20)}
}

---

六、注意事项

1. 状态管理原则：

   • 始终通过 @State 或 @Prop 管理选中状态
   • 避免直接修改 DOM 属性

2. 性能优化：

   • 大量 Checkbox 使用 LazyForEach
   • 复杂样式建议封装为自定义组件

3. 无障碍支持：

   Checkbox().accessibilityLabel('隐私协议选择框').accessibilityHint('双击切换选择状态')
   

4. 平台差异：

   • 在 OpenHarmony 上默认使用系统原生样式
   • 不同设备尺寸需要适配布局

---

七、常见问题解决

Q1：状态不更新

• 检查是否使用 @State 修饰变量
• 确认 onChange 回调中正确更新状态

Q2：自定义样式失效

• 确认图标资源路径正确
• 检查尺寸是否被父容器限制

Q3：点击区域太小

• 添加 padding 扩大热区：

  Checkbox().padding(10).hitTestBehavior(HitTestMode.Transparent)
  

---

通过合理运用 Checkbox 组件，可以构建出符合用户直觉的交互界面。建议结合具体业务需求选择最合适的实现方式，对于复杂场景推荐封装为可复用的自定义组件。