NodeGui QStandardItem 深度指南：从模型/视图架构到数据、状态与标志位控制

桌面应用跨平台【免费下载链接】nodeguiA library for building cross-platform native desktop applications with Node.js and CSS . React NodeGui : https://react.nodegui.org and Vue NodeGui: https://vue.nodegui.org项目地址https://gitcode.com/gh_mirrors/no/nodegui点击查看免费下载导读QStandardItem是 NodeGui 中用于表示QStandardItemModel树/表数据模型单元格的载体继承自 Component承担数据、勾选状态与行为标志位的存取。本文以 API 文档 为主线结合仓库中 TS 封装与 C 绑定源码完整讲解其构造方式、checkState/setCheckState/setData/setFlags四个核心方法并给出可运行的实战代码。一、QStandardItem 在 NodeGui 中的地位NodeGui 的模型/视图Model/View体系以QAbstractItemModel为抽象基类QStandardItemModel则是开箱即用的通用模型实现。与需要自行覆写rowCount/data等虚方法的QAbstractTableModel不同QStandardItemModel的数据由一个个QStandardItem单元格对象组成——这是理解本类最关键的前提每个QStandardItem对应模型中的一个数据单元单元格可以携带文本、图标、字体、对齐方式、背景色、勾选状态等多类数据项目Item之间通过父子关系构成树形结构QStandardItemModel将这种结构暴露给QTableView、QTreeView等视图控件从源码结构看QStandardItemModel.ts 仅提供了构造、item(row, column)取值与itemChanged信号数据写入与状态控制均落到QStandardItem上。二、类层级与核心 API 总览根据 qstandarditem.md 的声明QStandardItem继承自Component其完整的公开成员如下类别成员签名说明构造constructor()() QStandardItem创建空项目构造constructor(parent, text?)(parent: QStandardItem, text?: string) QStandardItem创建带父级与可选文本的项目构造constructor(native)(native: NativeElement) QStandardItem从原生对象包装供内部使用属性nativeNativeElement \| null底层原生句柄继承自Component方法checkState()() CheckState读取当前勾选状态方法setCheckState(state)(state: CheckState) void设置勾选状态方法setData(value, role)(value: number, role: number) void按角色写入数据方法setFlags(flags)(flags: ItemFlag) void设置行为标志位对应地QStandardItem.ts 中这五个方法均为对this.native的薄封装setCheckState转发到原生setCheckState(state)setData转发setData(value, role)setFlags转发setFlags(flags)checkState直接返回原生checkState()结果。三、三种构造方式与源码级细节1.new QStandardItem()—— 空项目不传任何参数创建一个没有任何文本、状态为未勾选的空白项目。在 qstandarditem_wrap.cpp 中对应new QStandardItem()。2.new QStandardItem(parent, text?)—— 带父级与文本传入一个QStandardItem作为父级父级由 NodeGui 侧的 QStandardItem.ts 判断若参数不是NativeElement且提供了text则底层走new addon.QStandardItem(text)。文本将写入项目的DisplayRole角色成为视图中显示的文字。3.new QStandardItem(native)—— 包装原生对象当checkIfNativeElement(parent)判定传入的是原生NativeElement时直接包装现有原生对象。这是内部桥接路径也是QStandardItemModel.item()返回项目的方式QStandardItemModel.ts的item(row, column)拿到原生 item 后执行new QStandardItem(item)将其包回 TS 层。C 侧对应 qstandarditem_wrap.cpp当第一个参数是Napi::ExternalQStandardItem时直接取用外部指针而非新建。注意TS 签名中parent仅用于构造时挂载到父级构造器内部只透传text给原生层parent并不会被原生构造器直接消费。四、数据写入setData(value, role)签名与语义setData(value: number, role: number): voidsetData按数据角色role向项目写入一个数值。角色决定了该值在视图中承担的意义。原生实现见 qstandarditem_wrap.cpp两个参数均为整数直接调用instance-setData(value, role)。常用角色来自 ItemDataRole 枚举角色值用途DisplayRole0单元格显示的文本DecorationRole1装饰图标/图片EditRole2编辑器中使用的数据ToolTipRole3悬停提示FontRole6字体TextAlignmentRole7文本对齐方式BackgroundRole8背景色ForegroundRole9前景色CheckStateRole10勾选状态SizeHintRole13尺寸提示UserRole0x0100自定义数据起始值使用要点本封装目前只接受number类型参数C 层用Int32Value读取因此如需写入颜色、字体等复合对象请使用QVariant 视图层角色渲染的方式见示例 modelview_2_formatting.ts 中通过QBrush、QFont装配QVariant的做法或将自定义数据编码为整数配合UserRole使用写入CheckStateRole时value对应 CheckState 的数值0/1/2与setCheckState效果一致数据变更后如需视图刷新参考 modelview_3_changingmodel.ts 中emitDataChanged的用法及时通知视图重绘。五、勾选状态checkState 与 setCheckState签名checkState(): CheckState setCheckState(state: CheckState): voidsetCheckState设置项目勾选状态。原生层 qstandarditem_wrap.cpp 将传入的整数强转为Qt::CheckState后写入checkState读取当前状态原生层 qstandarditem_wrap.cpp 将instance-checkState()的结果转回整数返回。CheckState 枚举取值CheckState/index.ts枚举成员值含义CheckState.Unchecked0未勾选CheckState.PartiallyChecked1部分勾选半选常用于树形父节点CheckState.Checked2已勾选实战注意勾选功能要生效项目的ItemIsUserCheckable标志位必须开启见下文setFlags否则视图中的复选框不可交互实现三态勾选父节点联动需要配合ItemIsUserTristate值为 256标志位使用。六、行为控制setFlags(flags)签名setFlags(flags: ItemFlag): voidsetFlags用位标志组合声明项目支持的行为可选、可编辑、可拖拽、可勾选等。原生层 qstandarditem_wrap.cpp 将整数强转为Qt::ItemFlag后写入。ItemFlag 枚举取值ItemFlag/index.ts枚举成员值含义ItemFlag.NoItemFlags0无任何标志ItemFlag.ItemIsSelectable1可选择ItemFlag.ItemIsEditable2可编辑ItemFlag.ItemIsDragEnabled4可拖拽ItemFlag.ItemIsDropEnabled8可接收拖放ItemFlag.ItemIsUserCheckable16用户可勾选ItemFlag.ItemIsEnabled32启用ItemFlag.ItemIsAutoTristate/ItemIsTristate64自动三态ItemFlag.ItemNeverHasChildren128无子节点ItemFlag.ItemIsUserTristate256用户三态使用要点标志位是按位组合的例如ItemIsSelectable | ItemIsEditable | ItemIsUserCheckable常见组合只读项目用ItemIsSelectable等价组合后的只读展示可编辑可勾选项目用ItemIsSelectable | ItemIsEditable | ItemIsUserCheckablesetFlags覆盖式设置非增量设置前需想清楚完整标志集合。七、综合实战用 QStandardItemModel QStandardItem 构建表格将上述 API 组合起来一个可运行的最小示例结构参考仓库 modelview 系列示例 的main()写法import { CheckState, ItemFlag, ItemDataRole, QStandardItem, QStandardItemModel, QTableView, } from nodegui/nodegui; function main(): void { const tableView new QTableView(); const model new QStandardItemModel(); // 创建两个单元格文本 可勾选 const cellA new QStandardItem(); cellA.setData(0, ItemDataRole.DisplayRole); // 写入显示文本的数值 cellA.setFlags( ItemFlag.ItemIsSelectable | ItemFlag.ItemIsEditable | ItemFlag.ItemIsUserCheckable, ); cellA.setCheckState(CheckState.Checked); const cellB new QStandardItem(); cellB.setFlags(ItemFlag.ItemIsSelectable); // 通过 QStandardItemModel 将项目接入模型由模型负责组织行列 // 注当前仓库的 QStandardItemModel 封装提供 item(row, column) 读取 // 项目挂载由原生模型层管理可在后续迭代中补充模型侧写入 API。 tableView.setModel(model); tableView.show(); (global as any).win tableView; } main();说明当前仓库中QStandardItemModel的 TS 封装主要暴露item(row, column)读取接口与itemChanged信号见 QStandardItemModel.ts完整的数据填充能力随版本演进上面的单元格属性 API 均与本文介绍的QStandardItem方法一一对应可直接迁移使用。八、信号联动itemChangedQStandardItem的数据变更最终会通过模型的itemChanged信号广播给视图层。原生实现位于 nstandarditemmodel.hppQStandardItemModel内部连接了itemChanged(QStandardItem*)信号并通过QStandardItemWrap::constructor.New将原生QStandardItem*包装回 JS 对象再发出。因此监听模型即可感知到具体哪个项目发生了数据/勾选/标志变化model.addEventListener(itemChanged, (item: QStandardItem) { console.log(item changed, checkState , item.checkState()); });九、总结围绕 QStandardItem API 文档本文完整覆盖了类层级QStandardItem extends Componentnative属性继承自 Component.ts三种构造空构造、带父级与文本构造、原生包装构造内部桥接QStandardItemModel.item()依赖此路径四个核心方法setData(value, role)按 ItemDataRole 写数据、setCheckState/checkState围绕 CheckState 管理勾选、setFlags以 ItemFlag 位组合控制行为底层原理TS 层 QStandardItem.ts 与 C 层 qstandarditem_wrap.cpp 的调用链关系。掌握这些 API 后你便能在 NodeGui 中自由控制表格/树视图单元格的数据、勾选状态与交互行为构建出可编辑、可勾选、只读等多样化的原生桌面数据界面。赞分享桌面应用跨平台【免费下载链接】nodeguiA library for building cross-platform native desktop applications with Node.js and CSS . React NodeGui : https://react.nodegui.org and Vue NodeGui: https://vue.nodegui.org项目地址https://gitcode.com/gh_mirrors/no/nodegui点击查看免费下载相关推荐终极NodeGUI模型视图架构指南掌握QAbstractItemModel和自定义数据模型终极NodeGUI模型视图架构指南掌握QAbstractItemModel和自定义数据模型 NodeGUI是一个强大的跨平台桌面应用开发框架它基于Node.桌面应用跨平台深入浅出CKEditor5框架架构从数据模型到视图渲染的完整解析深入浅出CKEditor5框架架构从数据模型到视图渲染的完整解析 CKEditor5是一个具有模块化架构、现代集成和协作编辑等功能的强大富文本编辑器框架。本文前端富文本UI组件ThinkPHP框架MVC架构深度解析控制器、模型与视图的终极协同指南ThinkPHP框架MVC架构深度解析控制器、模型与视图的终极协同指南 ThinkPHP作为一款十年匠心打造的高性能PHP框架其MVC模型 视图 控制器后端Web框架上一篇codeforces-go中的优先队列应用场景解析下一篇如何永久保存微信聊天记录WeChatMsg完整备份与导出终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考