NodeGui CheckState 枚举详解:勾选状态的三种取值与 Qt 组件实战用法
NodeGui CheckState 枚举详解:勾选状态的三种取值与 Qt 组件实战用法
本篇文章以 NodeGui 官方 API 文档中的 CheckState 枚举 为骨架,结合仓库内 TypeScript 源码、C++ 封装层与测试用例,系统讲解勾选状态枚举的取值定义、底层绑定原理,以及它在 QCheckBox、列表/树形/表格条目等组件中的实际用法。读完本文,你将能准确理解 Unchecked、PartiallyChecked、Checked 三种状态的语义差异,并在自己的 NodeGui 桌面应用中正确读写任何支持勾选的控件状态。
CheckState 是什么
CheckState 是 NodeGui 提供的一组枚举值,用于描述 Qt 控件中「复选框 / 可勾选项」所处的勾选状态。它是 Qt 原生 Qt::CheckState 枚举在 Node.js 侧的 TypeScript 映射,由 NodeGui 的枚举模块统一导出。
该枚举位于 src/lib/QtEnums/CheckState/index.ts,并通过 src/lib/QtEnums/index.ts 的聚合导出对外提供:
// src/lib/QtEnums/CheckState/index.ts
export enum CheckState {
Unchecked = 0,
PartiallyChecked = 1,
Checked = 2,
}
枚举成员一览
根据官方文档 checkstate.md,CheckState 共包含 3 个枚举成员,其名称与数值如下:
| 枚举成员 | 数值 | 语义 |
|---|---|---|
CheckState.Unchecked |
0 |
未勾选 |
CheckState.PartiallyChecked |
1 |
部分勾选(半选状态) |
CheckState.Checked |
2 |
已勾选 |
三个成员的取值与 Qt 原生 Qt::CheckState 完全一致,这一点在 C++ 封装层中可以直接得到印证:NodeGui 的包装类在读写状态时,直接使用 static_cast<Qt::CheckState>(state) 进行类型转换(见下文「底层绑定原理」一节)。
为什么会有 PartiallyChecked
普通复选框只有「勾选 / 未勾选」两种状态;PartiallyChecked(半选)通常出现在两种场景中:
- 三态复选框:QCheckBox 开启
tristate属性后,可以呈现第三态——既不是完全勾选也不是完全未勾选,常用于「部分选项被选中」的语义(例如全选按钮:当子项部分选中时显示半选状态); - 树形 / 表格层级项:父节点存在子节点且子节点勾选状态不完全一致时,父节点会呈现部分勾选状态。
在组件中的实际用法
CheckState 不是孤立存在的枚举,它被多个带勾选能力的 NodeGui 组件引用。从源码搜索可见,它至少被以下类使用(每个类都同时提供了 setCheckState() 写入方法与 checkState() 读取方法):
| 组件类 | 源码位置 | 说明 |
|---|---|---|
QCheckBox |
src/lib/QtWidgets/QCheckBox.ts | 复选框控件本体 |
QListWidgetItem |
src/lib/QtWidgets/QListWidgetItem.ts | 列表项 |
QTreeWidgetItem |
src/lib/QtWidgets/QTreeWidgetItem.ts | 树形项,需按列指定状态 |
QTableWidgetItem |
src/lib/QtWidgets/QTableWidgetItem.ts | 表格单元格项 |
QStandardItem |
src/lib/QtWidgets/QStandardItem.ts | 通用模型项 |
1. 复选框:QCheckBox
QCheckBox 封装了 Qt 的 QCheckBox 类(C++ 端实现见 src/cpp/lib/QtWidgets/QCheckBox/qcheckbox_wrap.cpp),其 TS 侧 API 如下:
// src/lib/QtWidgets/QCheckBox.ts(节选)
checkState(): CheckState {
return this.native.checkState();
}
setCheckState(state: CheckState): void {
this.native.setCheckState(state);
}
使用方式:
import { QCheckBox, CheckState } from '@nodegui/nodegui';
const checkbox = new QCheckBox();
checkbox.setText('启用高级模式');
// 写入勾选状态
checkbox.setCheckState(CheckState.Checked);
// 读取勾选状态
if (checkbox.checkState() === CheckState.Checked) {
console.log('已勾选');
}
若希望复选框支持三态(半选),需要先开启 setTristate():
checkbox.setTristate(true); // 启用三态
checkbox.setCheckState(CheckState.PartiallyChecked); // 此时显示半选状态
QCheckBox 还对外暴露 stateChanged 信号(见 QCheckBox.ts 中的 QCheckBoxSignals 接口),当状态发生变化时会以数值形式回调。
2. 列表项:QListWidgetItem
QListWidgetItem.ts 的官方注释示例展示了在列表项上打勾的经典写法,其中枚举以数字字面量形式出现(2 即 CheckState.Checked,0 即 CheckState.Unchecked):
const { QListWidget, QListWidgetItem } = require('@nodegui/nodegui');
const listWidget = new QListWidget();
for (let i = 0; i < 30; i++) {
const listWidgetItem = new QListWidgetItem();
listWidgetItem.setText('listWidgetItem ' + i);
if (i === 3) {
listWidgetItem.setCheckState(CheckState.Checked);
} else {
listWidgetItem.setCheckState(CheckState.Unchecked);
}
listWidget.addItem(listWidgetItem);
}
更可读、更不易出错的写法是直接引用枚举成员,同时可以配合 checkState() 回读:
const state = listWidgetItem.checkState(); // CheckState.Unchecked | PartiallyChecked | Checked
3. 树形项:QTreeWidgetItem
QTreeWidgetItem 的 setCheckState 需要同时指定列号与状态(见 QTreeWidgetItem.ts):
setCheckState(column: number, state: CheckState): void {
this.native.setCheckState(column, state);
}
示例——为第 0 列打勾,为第 1 列设置半选:
const item = new QTreeWidgetItem();
item.setText(0, '任务节点');
item.setCheckState(0, CheckState.Checked);
item.setCheckState(1, CheckState.PartiallyChecked);
父级树项在子项勾选状态不一致时,会被 Qt 自动呈现为 PartiallyChecked,这与 ItemDataRole.CheckStateRole 的模型层语义是呼应的。
4. 表格项与模型项
QTableWidgetItem:与QListWidgetItem相似,直接以setCheckState(state)/checkState()读写单元格勾选状态,见 src/lib/QtWidgets/QTableWidgetItem.ts。QStandardItem:模型层条目,同样提供setCheckState(state)与checkState(),见 src/lib/QtWidgets/QStandardItem.ts。
与 ItemDataRole.CheckStateRole 的关系
在模型/视图架构下,除了直接调用控件的 setCheckState,还可以通过数据角色 ItemDataRole.CheckStateRole(数值为 10)在 data() 回调中返回 CheckState 值,从而让视图按角色渲染勾选状态。
仓库自带的示例 src/examples/modelview_2_formatting.ts 演示了这种做法——在 data() 中针对 CheckStateRole 返回 CheckState.Checked,即可给指定单元格((1, 0))加上勾选框:
case ItemDataRole.CheckStateRole:
if (row == 1 && col == 0) {
// add a checkbox to cell(1,0)
return new QVariant(CheckState.Checked);
}
break;
注意返回值需要包装成 QVariant,且该角色定义于 ItemDataRole 枚举(CheckStateRole = 10)。这意味着 CheckState 枚举既可用于控件 API 直接读写,也可作为模型数据角色参与数据驱动渲染,两者配合可以构建出「勾选即联动数据」的复杂交互界面。
底层绑定原理
NodeGui 通过 N-API 将 C++ 对象暴露给 JavaScript。以 QCheckBox 为例,其原生绑定在 src/cpp/lib/QtWidgets/QCheckBox/qcheckbox_wrap.cpp 中注册了 checkState 与 setCheckState 两个实例方法:
// qcheckbox_wrap.cpp(节选)
Napi::Value QCheckBoxWrap::checkState(const Napi::CallbackInfo& info) {
Qt::CheckState state = this->instance->checkState();
return Napi::Value::From(env, static_cast<int>(state));
}
Napi::Value QCheckBoxWrap::setCheckState(const Napi::CallbackInfo& info) {
int state = info[0].As<Napi::Number>().Int32Value();
this->instance->setCheckState(static_cast<Qt::CheckState>(state));
return env.Null();
}
从这段代码可以清晰看到两个关键事实:
- 数值即状态:JS 侧传入的
CheckState数值(0/1/2)会被直接转换为Qt::CheckState,因此枚举值与 Qt 完全对齐,这就是前文数字字面量写法(setCheckState(2)、setCheckState(0))能够生效的原因; - 读取返回数字:
checkState()在 C++ 层将Qt::CheckState转回整数返回,JS 侧再与CheckState枚举成员比较即可。
其他组件(如 QListWidgetItem、QTreeWidgetItem、QStandardItem、QTableWidgetItem)的 C++ 封装采用了相同的转换模式,分别见 src/cpp/lib/QtWidgets/QListWidgetItem/qlistwidgetitem_wrap.cpp、src/cpp/lib/QtWidgets/QTreeWidgetItem/qtreewidgetitem_wrap.cpp、src/cpp/lib/QtWidgets/QStandardItem/qstandarditem_wrap.cpp 与 src/cpp/lib/QtWidgets/QTableWidgetItem/qtablewidgetitem_wrap.cpp。
测试验证与使用建议
仓库的单元测试 src/lib/QtWidgets/tests/QCheckBox.test.ts 覆盖了 QCheckBox 的实例化、setText、setIcon、setChecked 以及信号机制,验证了 setChecked(true) 与 isChecked() 的读写一致性——这两者本质上是 Checked / Unchecked 布尔语义的便捷封装。
综合源码与文档,使用 CheckState 时有几点建议:
- 优先使用枚举名而非数字:虽然
setCheckState(2)合法,但CheckState.Checked语义更清晰,也避免魔法数字; - 半选状态需要前置条件:普通复选框不开启
tristate时,PartiallyChecked无法被用户交互产生,需要通过setTristate(true)显式开启,或依赖父级树项的自动半选; - 读写方法成对出现:
setCheckState/checkState在 QCheckBox、QListWidgetItem、QTreeWidgetItem、QTableWidgetItem、QStandardItem 中均成对提供,可放心用于状态回读与持久化; - 模型场景使用 CheckStateRole:在自定义模型(如
QAbstractTableModel)中,通过ItemDataRole.CheckStateRole返回CheckState值,是让数据驱动视图渲染勾选状态的推荐做法,可参考 modelview_2_formatting.ts。
小结
CheckState 枚举虽小,却是 NodeGui 所有勾选类交互的基石:0(Unchecked)、1(PartiallyChecked)、2(Checked)三个取值与 Qt 原生枚举一一对应,贯穿复选框、列表项、树形项、表格项与模型层的读写链路。掌握它的取值语义、setCheckState/checkState 的成对用法以及 CheckStateRole 的数据角色配合,即可在桌面应用中实现从简单打勾到三态级联勾选等各类交互。