CheckboxGroup onChange 回调触发机制
二、删除选中内容时触发 onChange 的实现方案
方案一：通过数据源管理触发
@Entry
@Component
struct CheckboxGroupExample {
private data: MyDataSource = new MyDataSource();
@State isSelectAll: boolean = false;
aboutToAppear() {
// 初始化数据
for (let i = 0; i <= 100; i++) {
this.data.pushData({
isCheck: false,
itemName: `checkbox ${i}`
});
}
}
// 删除选中的项目
deleteSelectedItems() {
let dataSource = this.data.getDataSource();
// 1. 获取需要删除的索引（从后往前删除，避免索引变化）
let itemsToDelete: number[] = [];
dataSource.forEach((item, index) => {
if (item.isCheck) {
itemsToDelete.push(index);
}
});
// 2. 从后往前删除（重要：避免索引混乱）
for (let i = itemsToDelete.length - 1; i >= 0; i--) {
this.data.deleteData(itemsToDelete[i]);
}
// 3. 更新全选状态（这会触发 CheckboxGroup 的 onChange）
this.isSelectAll = false;
// 4. 手动触发 CheckboxGroup 的状态同步
// 由于删除了选中项，CheckboxGroup 会自动检测到变化
}
build() {
Column() {
// CheckboxGroup 全选组件
Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
CheckboxGroup({ group: "group" })
.selectAll(this.isSelectAll)
.onChange((result: CheckboxGroupResult) => {
// 这里会在以下情况触发：
// 1. 点击全选按钮
// 2. 点击任何一个子 Checkbox
// 3. 删除选中项后，选中状态发生变化
console.info('CheckboxGroup onChange:', JSON.stringify(result));
console.info('选中的项目:', result.name);
console.info('选中状态:', result.status); // All/Part/None
})
Text("全选").fontSize(25)
}.onClick(() => {
this.isSelectAll = !this.isSelectAll;
this.data.operateData(this.isSelectAll);
})
// 删除按钮
Button('删除选中项')
.onClick(() => {
this.deleteSelectedItems();
})
// 列表显示
List({ space: 3 }) {
LazyForEach(this.data, (item: checkboxItemData, index: number) => {
ListItem() {
Row() {
Checkbox({ name: `checkbox-${index}`, group: 'group' })
.select(item.isCheck)
.onChange((value: boolean) => {
this.data.operateItem(value, index);
// 更新全选状态
let dataSource = this.data.getDataSource();
this.isSelectAll = dataSource.every(item => item.isCheck === true);
})
Text(item.itemName).fontSize(20)
}
}
}, (item: checkboxItemData) => item.itemName + item.isCheck)
}.cachedCount(5)
}
}
}
// 数据源类需要添加删除方法
class MyDataSource extends BasicDataSource {
private dataArray: checkboxItemData[] = [];
// 删除指定索引的数据
public deleteData(index: number): void {
if (index >= 0 && index < this.dataArray.length) {
this.dataArray.splice(index, 1);
this.notifyDataDelete(index);
}
}
// 获取数据源
public getDataSource(): checkboxItemData[] {
return this.dataArray;
}
// 批量操作数据
public operateData(isSelect: boolean): void {
this.dataArray.forEach((item) => {
item.isCheck = isSelect;
});
this.notifyDataReload();
}
// 操作单个项目
public operateItem(isSelect: boolean, index: number): void {
this.dataArray[index].isCheck = isSelect;
this.notifyDataChange(index);
}
}
interface checkboxItemData {
isCheck: boolean;
itemName: string;
}
---
方案二：手动触发状态变化
如果需要在删除后显式触发 onChange：
@Entry
@Component
struct CheckboxDeleteExample {
@State selectAll: boolean = false;
@State items: Array<{id: string, name: string, checked: boolean}> = [
{ id: '1', name: '选项1', checked: false },
{ id: '2', name: '选项2', checked: false },
{ id: '3', name: '选项3', checked: false },
];
// 删除选中的项目
deleteSelectedItems() {
// 1. 过滤掉选中的项目
const beforeCount = this.items.length;
this.items = this.items.filter(item => !item.checked);
const afterCount = this.items.length;
// 2. 如果删除了项目，重置全选状态
if (beforeCount !== afterCount) {
// 方法1: 直接修改 selectAll（推荐）
this.selectAll = false;
// 方法2: 如果剩余项目全部选中，则保持全选状态
// this.selectAll = this.items.length > 0 &&
// this.items.every(item => item.checked);
}
}
build() {
Column() {
// 全选按钮
Row() {
CheckboxGroup({ group: 'myGroup' })
.selectAll(this.selectAll)
.onChange((result: CheckboxGroupResult) => {
console.info('CheckboxGroup 状态变化:');
console.info('选中的name:', JSON.stringify(result.name));
console.info('选中状态:', result.status);
// result.status 的值：
// - SelectStatus.All: 全部选中
// - SelectStatus.Part: 部分选中
// - SelectStatus.None: 全不选中
})
Text('全选')
}.onClick(() => {
this.selectAll = !this.selectAll;
// 更新所有项目的选中状态
this.items.forEach(item => item.checked = this.selectAll);
})
// 删除按钮
Button('删除选中项')
.margin({ top: 20 })
.onClick(() => {
this.deleteSelectedItems();
})
// 选项列表
Column({ space: 10 }) {
ForEach(this.items, (item) => {
Row() {
Checkbox({ name: item.id, group: 'myGroup' })
.select(item.checked)
.onChange((value: boolean) => {
// 更新单个项目状态
item.checked = value;
// 更新全选状态
this.selectAll = this.items.every(it => it.checked);
})
Text(item.name)
}
}, (item) => item.id)
}
.margin({ top: 20 })
}
.padding(20)
}
}
---
三、onChange 回调参数详解
CheckboxGroupResult 对象（ts-basic-components-checkboxgroup.md:312-325）
interface CheckboxGroupResult {
name: Array<string>; // 群组内所有被选中的多选框名称
status: SelectStatus; // 选中状态
}
SelectStatus 枚举（ts-basic-components-checkboxgroup.md:327-341）
enum SelectStatus {
All, // 群组多选框全部选择
Part, // 群组多选框部分选择
None // 群组多选框全部未选择
}
---
四、完整示例：删除选中项并触发 onChange
@Entry
@Component
struct CheckboxGroupDeleteDemo {
@State selectAllState: boolean = false;
@State itemList: ItemData[] = [
{ id: '1', name: '文档1.pdf', checked: false },
{ id: '2', name: '图片2.jpg', checked: false },
{ id: '3', name: '视频3.mp4', checked: false },
{ id: '4', name: '音频4.mp3', checked: false },
];
// 删除选中的项目
deleteSelected() {
const selectedCount = this.itemList.filter(item => item.checked).length;
if (selectedCount === 0) {
console.warn('没有选中任何项目');
return;
}
// 删除选中的项目
this.itemList = this.itemList.filter(item => !item.checked);
// 重置全选状态（这会触发 CheckboxGroup 的 onChange）
this.selectAllState = false;
console.info(`已删除 ${selectedCount} 个项目`);
}
build() {
Column({ space: 20 }) {
Text('文件列表管理')
.fontSize(24)
.fontWeight(FontWeight.Bold)
// 全选和删除按钮
Row({ space: 20 }) {
// 全选按钮
Row() {
CheckboxGroup({ group: 'fileGroup' })
.selectAll(this.selectAllState)
.onChange((result: CheckboxGroupResult) => {
console.info('=== CheckboxGroup onChange 触发 ===');
console.info('选中的文件:', result.name);
console.info('选中状态:', SelectStatus[result.status]);
console.info('状态详情:',
result.status === SelectStatus.All ? '全选' :
result.status === SelectStatus.Part ? '部分选中' : '未选中'
);
})
Text('全选')
}
.onClick(() => {
this.selectAllState = !this.selectAllState;
this.itemList.forEach(item => item.checked = this.selectAllState);
})
// 删除按钮
Button('删除选中')
.onClick(() => {
this.deleteSelected();
})
}
// 文件列表
Column({ space: 10 }) {
ForEach(this.itemList, (item: ItemData) => {
Row({ space: 10 }) {
Checkbox({ name: item.id, group: 'fileGroup' })
.select(item.checked)
.onChange((checked: boolean) => {
item.checked = checked;
// 更新全选状态
const allChecked = this.itemList.every(it => it.checked);
const noneChecked = this.itemList.every(it => !it.checked);
if (allChecked) {
this.selectAllState = true;
} else if (noneChecked) {
this.selectAllState = false;
}
})
Text(item.name)
}
.width('100%')
.padding(10)
.backgroundColor(Color.White)
.borderRadius(8)
}, (item: ItemData) => item.id)
}
// 统计信息
Text(`共 ${this.itemList.length} 个文件，已选中 ${this.itemList.filter(it => it.checked).length} 个`)
.fontSize(14)
.fontColor(Color.Gray)
}
.width('100%')
.height('100%')
.padding(20)
.backgroundColor('#F5F5F5')
}
}
interface ItemData {
id: string;
name: string;
checked: boolean;
}
---
五、关键注意事项
- onChange 触发时机
- ✅ CheckboxGroup 本身状态变化
- ✅ 群组内任何 Checkbox 状态变化
- ✅ 通过 selectAll 属性修改（需配合状态管理）
- 删除操作最佳实践
// ❌ 错误做法：直接删除不更新状态
deleteItems() {
this.items = this.items.filter(item => !item.checked);
// onChange 可能不会触发！
}
// ✅ 正确做法：删除后更新 selectAll 状态
deleteItems() {
this.items = this.items.filter(item => !item.checked);
this.selectAllState = false; // 触发状态变化
}
- 使用双向绑定（API 10+）
// 使用 $$ 双向绑定（推荐）
CheckboxGroup({ group: 'group' })
.selectAll($$this.isSelectAll)
.onChange((result: CheckboxGroupResult) => {
// 自动同步状态
})
// 或使用 !! 双向绑定（API 18+）
CheckboxGroup({ group: 'group' })
.selectAll(this.isSelectAll!!)
- 带缓存组件的处理
根据文档提示（ts-basic-components-checkboxgroup.md:25）：
在结合带缓存组件使用时（如List），未被创建的Checkbox选中状态需要应用手动控制。
// 删除时需要手动管理未创建的 Checkbox 状态
deleteSelected() {
// 更新数据源
this.data.deleteSelectedItems();
// 通知 List 刷新
this.data.notifyDataReload();
// 重置全选状态
this.isSelectAll = false;
}
六、总结
CheckboxGroup 的 onChange 会在以下情况自动触发：
- 点击 CheckboxGroup
- 点击群组内的 Checkbox
- 修改 selectAll 属性值
- 数据源变化导致选中状态变化
