NodeGui CheckState 枚举详解:勾选状态的三种取值与 Qt 组件实战用法

原创2026-09-24 16:34:511,653 阅读
文章标签:桌面应用跨平台

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(半选)通常出现在两种场景中:

  1. 三态复选框:QCheckBox 开启 tristate 属性后,可以呈现第三态——既不是完全勾选也不是完全未勾选,常用于「部分选项被选中」的语义(例如全选按钮:当子项部分选中时显示半选状态);
  2. 树形 / 表格层级项:父节点存在子节点且子节点勾选状态不完全一致时,父节点会呈现部分勾选状态。

在组件中的实际用法

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. 表格项与模型项

与 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();
}

从这段代码可以清晰看到两个关键事实:

  1. 数值即状态:JS 侧传入的 CheckState 数值(0/1/2)会被直接转换为 Qt::CheckState,因此枚举值与 Qt 完全对齐,这就是前文数字字面量写法(setCheckState(2)、setCheckState(0))能够生效的原因;
  2. 读取返回数字: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 的数据角色配合,即可在桌面应用中实现从简单打勾到三态级联勾选等各类交互。

登录后查看全文
nodegui