ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

NodeGui QTreeWidgetSignals 信号接口完全指南:从 Qt 树控件事件到 Node.js 回调

NodeGui QTreeWidgetSignals 信号接口完全指南:从 Qt 树控件事件到 Node.js 回调 桌面应用跨平台【免费下载链接】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点击查看免费下载QTreeWidgetSignals是 NodeGui 中树形视图控件QTreeWidget的信号接口定义它完整刻画了 Qt 的QTreeWidget在 Node.js 世界中的事件面项目点击、双击、展开/折叠、选中变化、内容编辑、当前项切换等 10 个原生信号以及从父级接口继承的 4 个通用信号。读完本文你将掌握如何为QTreeWidget挂载事件监听、理解每个信号回调的参数含义并能从源码层面看懂这些 Qt 信号是如何被转译为 Node.js 事件的。接口定位QTreeWidgetSignals 在整个信号体系中的位置在 NodeGui 中每个原生控件都对应一个信号接口Signals interface用于声明该控件能够对外发出哪些事件。这些接口之间存在严格的继承层级与 Qt 的类继承关系一一对应。从生成文档的 Hierarchy 一节可以看到QObjectSignals基础objectNameChanged↳ QWidgetSignalscustomContextMenuRequested、windowIconChanged、windowTitleChanged↳QTreeWidgetSignals在 TypeScript 源码侧QTreeWidgetSignals实际扩展自QAbstractScrollAreaSignals见 src/lib/QtWidgets/QTreeWidget.ts而生成的 API 文档将其继承关系精简表示为直接继承QWidgetSignals。这与类实现一致QTreeWidget的 TS 封装继承自QAbstractScrollAreaC 侧NTreeWidget则继承自QTreeWidget与NodeWidget见 src/cpp/include/nodegui/QtWidgets/QTreeWidget/ntreewidget.hpp。因此一个QTreeWidget实例实际可监听到的信号分为两类自有的树控件信号10 个与继承的通用信号4 个合计 14 个。信号总览信号名回调签名触发时机来源currentItemChanged(current, previous) void当前项目切换自有itemActivated(item \| null, column) void项目被激活如回车或双击取决于平台自有itemChanged(item, column) void项目数据被修改自有itemClicked(item, column) void鼠标点击项目自有itemCollapsed(item) void项目被折叠自有itemDoubleClicked(item \| null, column) void鼠标双击项目自有itemEntered(item, column) void鼠标悬停进入项目需开启鼠标跟踪自有itemExpanded(item) void项目被展开自有itemPressed(item \| null, column) void鼠标按下项目自有itemSelectionChanged() void选中集发生变化自有customContextMenuRequested(pos: {x, y}) void请求弹出上下文菜单继承自 QWidgetSignalsobjectNameChanged(objectName) void对象名变化继承自 QObjectSignalswindowIconChanged(iconNative) void窗口图标变化继承自 QWidgetSignalswindowTitleChanged(title) void窗口标题变化继承自 QWidgetSignals自有信号逐一详解1. currentItemChanged当前项目切换currentItemChanged: (current: QTreeWidgetItem, previous: QTreeWidgetItem) void;当树中当前项目有焦点、以虚线框高亮的项目发生变化时触发回调同时给出切换后的新项目current与切换前的旧项目previous两个参数都是 QTreeWidgetItem 实例。该信号非常适合实现主从联动界面——例如左侧树选中某分类时右侧面板展示对应详情。2. itemActivated项目激活itemActivated: (item: QTreeWidgetItem | null, column: number) void;当项目被激活时触发。所谓激活通常指双击或按回车键具体行为与平台和视图设置相关。注意回调的item参数类型为QTreeWidgetItem | null——Qt 原生信号中该指针可能为空因此在回调内应先判空再访问。3. itemChanged项目内容被编辑itemChanged: (item: QTreeWidgetItem, column: number) void;当项目的某一列数据发生变化时触发例如通过setText、setCheckState修改或用户在可编辑项目中直接编辑。回调携带被修改的item与对应column列号。结合 QTreeWidgetItem.ts 中对setText、setCheckState等方法的封装可以实现数据校验、自动保存、脏标记等业务逻辑。4. itemClicked / itemPressed点击与按下itemClicked: (item: QTreeWidgetItem, column: number) void; itemPressed: (item: QTreeWidgetItem | null, column: number) void;itemClicked在鼠标左键单击项目时触发携带被点击的项目与其所在列itemPressed在鼠标按下尚未释放时触发。二者语义上类似 Qt 按钮的pressed与clicked需要区分按下即响应与释放后响应两种交互时分别监听。注意itemPressed的item参数同样可能为null。5. itemCollapsed / itemExpanded展开与折叠itemCollapsed: (item: QTreeWidgetItem) void; itemExpanded: (item: QTreeWidgetItem) void;当项目被折叠或展开时触发用户点击展开箭头、或代码调用setExpanded等。这两个信号只携带item参数。典型应用是懒加载——在itemExpanded回调中才为节点动态添加子项目避免一次性构建整棵大树。6. itemDoubleClicked双击itemDoubleClicked: (item: QTreeWidgetItem | null, column: number) void;双击项目时触发携带项目与列号。item参数同样可为null需判空。7. itemEntered鼠标悬停进入itemEntered: (item: QTreeWidgetItem, column: number) void;当鼠标移动进入某个项目所在区域时触发。注意该信号依赖鼠标跟踪若需使用需先开启setMouseTracking(true)可参考 handle-events.md 中对QLabel使用MouseMove的示例思路。8. itemSelectionChanged选中集变化itemSelectionChanged: () void;这是唯一一个无参数的自有信号只要选中集合发生变化新增、取消选中、切换多选等即触发不携带具体项目。需要获取当前选中项时可在回调中调用QTreeWidget的selectedItems()方法见 src/lib/QtWidgets/QTreeWidget.ts它会返回包装后的QTreeWidgetItem[]。继承的通用信号customContextMenuRequested(pos: { x: number, y: number }) void请求弹出上下文菜单时触发pos为控件内坐标对象。可配合QMenu实现右键菜单objectNameChanged(objectName: string) voidobjectName变化时触发继承自 QObjectSignalswindowIconChanged(iconNative: NativeElement) void窗口图标变化时触发参数为原生图标句柄类型见 globals.md 中的NativeElementwindowTitleChanged(title: string) void窗口标题变化时触发。这些通用信号在 QWidgetSignals 与 QObjectSignals 接口文档中均有完整定义NodeGui 中所有控件如QPushButton、QListWidget、QMainWindow等都共享它们。在 NodeGui 中监听这些信号NodeGui 的信号订阅统一通过addEventListener完成。根据 handle-events.md 的说明每个控件背后都是一个 Node.jsEventEmitter实例原生 Qt 控件把信号推送到这个事件发射器JS 侧通过addEventListener订阅。同一信号可注册多个监听器全部会被依次调用使用 TypeScript 时回调参数自动获得类型提示。一个完整的实战示例结合 QTreeWidget.ts 中的树构建 APIconst { QMainWindow, QTreeWidget, QTreeWidgetItem } require(nodegui/nodegui); const win new QMainWindow(); const tree new QTreeWidget(); // 构建树顶层项目 子项目 const item1 new QTreeWidgetItem(); item1.setText(0, item-1); const item2 new QTreeWidgetItem(); item2.setText(0, item-2); tree.addTopLevelItem(item1); tree.addTopLevelItem(item2); const child1 new QTreeWidgetItem(item1); child1.setText(0, child-1); const child2 new QTreeWidgetItem(item1); child2.setText(0, child-2); // 订阅信号 tree.addEventListener(currentItemChanged, (current, previous) { console.log(当前项目切换到:, current.text(0), 上一个:, previous previous.text(0)); }); tree.addEventListener(itemClicked, (item, column) { console.log(点击了第 ${column} 列的项目:, item.text(column)); }); tree.addEventListener(itemExpanded, (item) { console.log(展开节点:, item.text(0)); }); tree.addEventListener(itemSelectionChanged, () { const selected tree.selectedItems(); console.log(当前选中:, selected.map((it) it.text(0))); }); win.setCentralWidget(tree); win.show(); global.win win; // 防止被垃圾回收如果你想知道某个控件到底支持哪些信号直接阅读对应控件类的签名接口即可——QTreeWidget的信号面就是本文的QTreeWidgetSignals。源码视角Qt 信号如何抵达 JS 回调理解信号的底层流转可以让排查问题事半功倍。在 NodeGui 中一条QTreeWidget信号的生命周期如下C 侧连接信号NTreeWidget继承QTreeWidget与NodeWidget并在connectSignalsToEventEmitter()中用QObject::connect将每个 Qt 信号与一个 lambda 绑定见 ntreewidget.hpp。例如QObject::connect(this, QTreeWidget::itemClicked, { Napi::Env env this-emitOnNode.Env(); Napi::HandleScope scope(env); auto itemWrap QTreeWidgetItemWrap::fromQTreeWidgetItem(env, item); auto columnWrap Napi::Value::From(env, column); this-emitOnNode.Call( {Napi::String::New(env, itemClicked), itemWrap, columnWrap}); });参数包装lambda 内部通过QTreeWidgetItemWrap::fromQTreeWidgetItem把原生QTreeWidgetItem*包装为可供 JS 使用的对象再连同列号等参数一起传给emitOnNode。触发 EventEmitteremitOnNode指向 JS 侧EventEmitter的emit函数由EventWidget在初始化时通过initNodeEventEmitter注入。信号到达后即触发 JS 回调完成Qt 信号 → Node.js 事件的转译。这一整体机制在 eventwidget.h 与 signal_and_event_handling.md 中有详细说明。值得注意的细节在 C 实现中itemClicked、itemChanged、currentItemChanged、itemActivated、itemDoubleClicked、itemEntered、itemPressed这些携带项目的信号都会先经fromQTreeWidgetItem包装所以 JS 回调里拿到的是可直接调用text()等方法的QTreeWidgetItem实例而itemSelectionChanged由于 Qt 原生信号不带参数JS 回调中也就没有参数需要主动调用selectedItems()获取选中项。常见问题与注意事项itemActivated/itemDoubleClicked/itemPressed的 item 可能为 null回调中务必先判空再访问避免TypeErroritemEntered默认不触发需要先在控件上开启鼠标跟踪setMouseTracking(true)否则悬停信号不会到来信号监听与垃圾回收与 NodeGui 中其他控件一样需要把窗口/控件保存在全局引用如示例中的global.win中防止被 GC 回收导致信号失效相关机制可参阅 understanding-memory.mditemChanged与编辑能力QTreeWidgetItem是否可编辑取决于其ItemFlag设置若项目不可编辑用户无法在界面上修改文本itemChanged主要通过代码层面的setText、setCheckState等触发多列场景绝大多数信号回调都携带column列号处理多列表格如名称 状态两列时记得按列区分业务。延伸阅读QTreeWidget 类参考 与 QTreeWidgetItem 类参考树控件的全部方法与属性QWidgetSignals 与 QObjectSignals继承信号的完整定义handle-events.mdNodeGui 信号与 QEvent 的统一监听方式signal_and_event_handling.md如何在源码层面为控件新增信号支持树控件信号接口源码QTreeWidget.ts、ntreewidget.hpp、qtreewidget_wrap.cpp赞分享桌面应用跨平台【免费下载链接】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 中 QTreeWidget 树形控件的完整实战指南从顶层项管理到信号事件NodeGui 中 QTreeWidget 树形控件的完整实战指南从顶层项管理到信号事件 QTreeWidget 是 NodeGui 提供的树形视图控件它直桌面应用跨平台30分钟产出研究简报Academic Research Skills 快速研究模式完整指南30分钟产出研究简报Academic Research Skills 快速研究模式完整指南 周五晚上十点明早的组会需要你讲清楚「AI 评测方法」这个完全陌生桌面应用跨平台NodeGui QListWidgetSignals 信号接口全解析从事件监听到 C 底层实现NodeGui QListWidgetSignals 信号接口全解析从事件监听到 C 底层实现 本指南以 NodeGui 官方 API 文档 qlistw桌面应用跨平台上一篇旧Mac重生指南用OpenCore Legacy Patcher免费升级最新macOS系统下一篇OpenArk被Windows Defender误报深入解析Windows反病毒软件对ARK工具的误判机制创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表