桌面应用跨平台【免费下载链接】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点击查看免费下载QWindow 是 NodeGui 中面向底层原生窗口句柄的封装类负责窗口的状态管理全屏、最大化、最小化、常规显示、可见性控制、系统级拖动与缩放以及屏幕信息查询。本文以官方 API 文档为主体结合仓库源码与原生实现完整讲解 QWindow 的构造约束、全部方法签名、配套枚举取值并给出可直接运行的实战示例帮助读者在自己的 NodeGui 应用中精确控制窗口行为。QWindow 在 NodeGui 中的定位在 NodeGui 的对象体系中QWindow继承自QObjectQWindowSignals其完整继承链为QObjectQWindowSignals ↳ QWindow这一继承关系可以在 QWindow API 文档 的 Hierarchy 一节中直接看到同时反映在 TypeScript 源码export class QWindow extends QObjectQWindowSignals这一行见 src/lib/QtGui/QWindow.ts。需要特别注意的是QWindow与QWidget属于不同抽象层次QWidget是高级窗口部件承载界面渲染与布局FlexLayout、样式等QWindow是底层平台窗口句柄聚焦于窗口状态、可见性和系统级交互。在 NodeGui 中QWindow实例通常不是直接创建的而是通过QWidget.windowHandle()获取。该方法返回当前 widget 对应的原生窗口句柄包装若句柄尚未创建则返回null实现位于 src/lib/QtWidgets/QWidget.tswindowHandle(): QWindow | null { const handle this.native.windowHandle(); if (handle ! null) { return wrapperCache.getQWindow(QWindow, handle); } return null; }构造函数与 native 属性constructor(native: NativeElement)new QWindow(native: NativeElement): QWindow该构造函数接收一个 NativeElement 类型的原生对象引用不接受普通参数。TypeScript 封装层在构造时做了严格校验src/lib/QtGui/QWindow.tsconstructor(native: NativeElement) { if (!checkIfNativeElement(native)) { throw new Error(QWindow cannot be initialised this way.); } super(native); }在 C 原生层QWindowWrap的构造函数只接受一个Napi::ExternalQWindow类型的外部指针否则会抛出NodeGui: QWindowWrap: Bad arguments to constructor.的类型错误见 qwindow_wrap.cpp。这意味着不要试图用new QWindow(...)凭空创建窗口——正确做法是通过widget.windowHandle()拿到已有的原生窗口句柄包装。nativenative: NativeElement | null该属性继承自 Component保存着底层 C 对象的引用是所有原生方法调用的入口。Component 是 NodeGui 世界所有 widget 与 layout 的根基类其职责包括维护对原生 C 实例的引用以及防止子元素被垃圾回收src/lib/core/Component.ts。窗口状态控制QWindow 提供了最常用的窗口状态切换方法均为void返回方法作用showFullScreen()以全屏模式显示窗口showMaximized()以最大化模式显示窗口showMinimized()以最小化模式显示窗口showNormal()恢复为正常非全屏、非最大化模式显示窗口这些方法直接透传给原生层调用qwindow_wrap.cpp 中对应的this-instance-showFullScreen()等。示例const window widget.windowHandle(); if (window) { window.showMaximized(); // 启动即最大化 window.showFullScreen(); // 或直接全屏 window.showNormal(); // 恢复正常窗口 }setWindowState 与 windowState除了一次性切换QWindow 还提供基于枚举的状态设置与查询setWindowState(state: WindowState): void windowState(): WindowStateWindowState枚举定义于 src/lib/QtEnums/WindowState/index.ts取值与 Qt 原生一致均为位标志可组合枚举值数值含义WindowNoState0x00000000无特殊状态WindowMinimized0x00000001最小化WindowMaximized0x00000002最大化WindowFullScreen0x00000004全屏WindowActive0x00000008活动窗口在原生层setWindowState通过static_castQt::WindowState转换后调用QWindow::setWindowStatewindowState则读取并返回Qt::WindowState的无符号整型值qwindow_wrap.cpp。window.setWindowState(WindowState.WindowMinimized); // 最小化 console.log(window.windowState()); // 查询当前状态可见性控制setVisibility(visibility: Visibility): void visibility(): VisibilityVisibility枚举定义于 src/lib/QtEnums/Visibility/index.ts对应 Qt 的QWindow::Visibility枚举值数值含义Hidden0窗口隐藏AutomaticVisibility1可见性由系统自动决定Windowed2窗口模式显示Minimized3最小化Maximized4最大化FullScreen5全屏setVisibility在原生层被转换为QWindow::Visibility枚举后调用qwindow_wrap.cpp。window.setVisibility(Visibility.Hidden); // 隐藏窗口 if (window.visibility() Visibility.Windowed) { console.log(窗口正处于普通窗口模式); }系统级窗口操作startSystemMovestartSystemMove(): boolean启动系统级窗口拖动即从 JavaScript 侧发起与用户按住标题栏拖动等价的操作。返回boolean表示是否成功开始拖动。原生实现为this-instance-startSystemMove()qwindow_wrap.cpp。一个典型场景是自定义标题栏把普通 widget 伪装成标题栏通过MouseButtonPress事件触发系统拖动。startSystemResizestartSystemResize(edges: Edge): boolean启动系统级窗口缩放edges指定从哪些边缘/角落进行缩放。Edge枚举定义于 src/lib/QtEnums/Edge/index.ts取值同样为 Qt 位标志枚举值数值含义TopEdge0x00001顶部边缘LeftEdge0x00002左侧边缘RightEdge0x00004右侧边缘BottomEdge0x00008底部边缘原生层将参数按static_castQt::Edges(edge)转换后调用QWindow::startSystemResize返回boolean表示操作是否成功发起qwindow_wrap.cpp。由于Edge是位标志可以使用|组合多个边缘// 从右下角发起系统级缩放 const ok window.startSystemResize(Edge.RightEdge | Edge.BottomEdge);屏幕信息查询screen(): QScreen返回该窗口当前所在屏幕的 QScreen 包装对象可用于获取分辨率、DPI、刷新率、可用几何区域等信息。原生层在 screen 指针为空时返回env.Null()即 JavaScript 的null否则通过WrapperCache包装后返回qwindow_wrap.cpp。QScreen的 TypeScript 封装src/lib/QtGui/QScreen.ts提供了大量屏幕属性查询方法包括geometry(): QRect、availableGeometry(): QRect—— 屏幕几何区域与可用区域size(): QSize、availableSize(): QSize—— 屏幕尺寸devicePixelRatio(): number—— 设备像素比高分屏适配关键refreshRate(): number—— 刷新率physicalDotsPerInch() / logicalDotsPerInch(): number—— 物理/逻辑 DPIgrabWindow(...): QPixmap—— 截取屏幕内容。const screen window.screen(); console.log(DPI: ${screen.logicalDotsPerInch()}); console.log(刷新率: ${screen.refreshRate()} Hz);信号与事件机制QWindowSignals 信号接口QWindow的信号接口为QWindowSignalssrc/lib/QtGui/QWindow.ts 中的接口定义完整文档见 qwindowsignals.md信号回调签名触发时机screenChanged(screen: QScreen) void窗口所在屏幕发生变化时visibilityChanged(visibility: Visibility) void窗口可见性改变时windowStateChanged(windowState: WindowState) void窗口状态改变时objectNameChanged(objectName: string) void继承自 QObjectSignalsobjectName 改变时这些信号在原生层由connectSignalsToEventEmitter通过QObject::connect与 Qt 原生信号连接再由 N-API 回调投递到 JavaScript 的 EventEmitterqwindow_wrap.cpp。addEventListener 与 removeEventListeneraddEventListener有两个重载信号监听addEventListenerSignalType extends keyof QWindowSignals( signalType: SignalType, callback: QWindowSignals[SignalType], options?: EventListenerOptions ): voidQEvent 监听addEventListener( eventType: WidgetEventTypes, callback: (event?: NativeRawPointerQEvent) void, options?: EventListenerOptions ): voidremoveEventListener具有相同结构的两个重载用于注销监听。EventListenerOptionseventlisteneroptions.md中的afterDefault选项仅对 QEvent 生效设为true时回调会在基类默认处理之后被调用对应内部_after事件名默认在默认处理之前调用。底层的订阅/退订逻辑通过native.subscribeToQtEvent与native.unSubscribeToQtEvent完成实现在 src/lib/core/EventWidget.ts。// 监听信号 window.addEventListener(windowStateChanged, (state) { console.log(窗口状态变为, state); }); window.addEventListener(screenChanged, (screen) { console.log(窗口切换到了新屏幕); }); // 注销信号监听 window.removeEventListener(windowStateChanged, handler);eventProcessed 与 setEventProcessedeventProcessed(): boolean setEventProcessed(isProcessed: boolean): void这一对方法继承自 EventWidget用于控制事件是否继续向上传递在事件处理器中调用setEventProcessed(true)会把当前事件标记为已处理此后 NodeGui 的QObject::event()会直接返回true而不调用父类event()从而阻止该事件的进一步处理eventProcessed()用于查询当前标记状态src/lib/core/EventWidget.ts。继承自 QObject 的通用能力QWindow的大部分方法与QObject完全一致由 qobject.md 继承而来它们都在 src/lib/QtCore/QObject.ts 中实现方法签名说明_id()(): number返回标识底层 C 对象的唯一编号内存地址哈希配合setLogCreateQObject()/setLogDestroyQObject()可排查内存问题objectName() / setObjectName(name)(): string/(name: string): void读写对象名property(name)/setProperty(name, value)(name): QVariant/(name, value): boolean通过动态属性读写元数据inherits(className)(className: string): boolean判断对象是否继承自指定类setParent(parent)/parent()(parent: QObject): void/(): QObject设置/获取父对象注意原生层 QWindow 的 setParent 仅接受 QWindow见 qwindow_wrap.h 中的特殊实现children()(): QObject[]返回子对象列表startTimer(intervalMS, timerType)(intervalMS: number, timerType?): number启动定时器返回 timerIdtimerType默认TimerType.CoarseTimerkillTimer(timerId)(timerId: number): void停止定时器delete()(): void立即删除原生对象deleteLater()(): void事件循环空闲时删除原生对象更安全dumpObjectTree()/dumpObjectInfo()(): void向 stderr 输出对象树/对象信息用于调试startTimer的timerType参数接受 TimerType 枚举枚举值数值含义PreciseTimer0精确定时器尽量按毫秒触发CoarseTimer1粗粒度定时器默认可合并以省电VeryCoarseTimer2极粗粒度定时器秒级底层实现从 TypeScript 到原生 CQWindow 的完整调用链可以概括为三层TypeScript 封装层src/lib/QtGui/QWindow.ts定义类、签名与信号接口并通过wrapperCache.registerWrapper(QWindowWrap, QWindow)与registerNativeWrapFunction注册包装映射N-API 原生层qwindow_wrap.cppQWindowWrap继承自Napi::ObjectWrapQWindowWrap、EventWidget与QObject通过DefineClass注册screen、showFullScreen、startSystemResize等实例方法并通过QOBJECT_REGISTER_WRAPPER(QWindow, QWindowWrap)登记包装器Qt 层所有调用最终落到QPointerQWindow指向的 Qt 原生QWindow实例上。值得留意的是 qwindow_wrap.h 中的注释QWindow 不处理任何 QEventsWe dont use EVENTWIDGET_IMPLEMENTATIONS() here because this class doesnt handle any QEvents但它仍通过installEventFilter安装了事件过滤器将事件转发给EventWidget::event处理同时它在对象析构时会自动removeEventFilter避免悬挂引用。screenChanged等信号在回调中通过WrapperCache::instance.getWrapper(env, screen, true)将原生QScreen*转为 JS 包装对象后投递。由于QWindow只能由windowHandle()等路径产生原生层构造函数对非法参数直接抛错这保证了 JavaScript 侧拿到的每一个 QWindow 都对应一个真实存在的原生窗口句柄。实战示例利用 QWindow 实现窗口控制下面是一个完整的 NodeGui 示例演示如何从QWidget.windowHandle()获取 QWindow并组合使用状态切换、可见性查询与信号监听import { QMainWindow, QPushButton, WindowState, Visibility } from nodegui/nodegui; const win new QMainWindow(); win.setWindowTitle(QWindow 实战示例); win.resize(800, 600); const button new QPushButton(); button.setText(最大化 / 还原); win.setCentralWidget(button); button.addEventListener(clicked, () { const handle win.windowHandle(); if (!handle) return; // 当前不是最大化则最大化否则还原 if (handle.windowState() ! WindowState.WindowMaximized) { handle.setWindowState(WindowState.WindowMaximized); } else { handle.setWindowState(WindowState.WindowNoState); } }); // 监听窗口状态变化 win.windowHandle()?.addEventListener(windowStateChanged, (state) { console.log(窗口状态, state); }); // 全屏切换按 F 进入全屏再按退出 const toggleFullScreen () { const handle win.windowHandle(); if (!handle) return; if (handle.visibility() ! Visibility.FullScreen) { handle.showFullScreen(); } else { handle.showNormal(); } }; // 挂载后执行 win.addEventListener(show, toggleFullScreen); // 示例窗口显示时进入全屏可按需调整 win.show(); (globalThis as any).win win; // 保持引用避免被 GC提示windowHandle()可能返回null原生窗口句柄尚未创建因此在使用前务必判空。窗口显示后再获取句柄通常是更稳妥的方式。小结QWindow 是 NodeGui 中连接 JavaScript 世界与 Qt 原生窗口系统的关键桥梁通过showFullScreen/showMaximized/showMinimized/showNormal与setWindowState完成状态控制通过setVisibility/visibility管理可见性通过startSystemMove/startSystemResize实现系统级拖动与缩放通过screen()查询屏幕信息并通过QWindowSignals与addEventListener感知窗口变化。结合 API 文档、TypeScript 封装src/lib/QtGui/QWindow.ts与原生实现src/cpp/lib/QtGui/QWindow/qwindow_wrap.cpp你可以在 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点击查看免费下载相关推荐Azul窗口管理多窗口应用和窗口状态控制的完整教程Azul窗口管理多窗口应用和窗口状态控制的完整教程 想要构建现代化的跨平台桌面应用 Azul GUI框架 的 窗口管理 功能让多窗口应用开发变得简单高效无桌面应用前端跨平台Polybar窗口管理终极指南X11窗口属性与操作完全解析Polybar窗口管理终极指南X11窗口属性与操作完全解析 Polybar 是一款快速且易用的状态栏工具专为 X11 窗口系统设计能够帮助用户高效管理和监桌面应用GlazeWM窗口管理器终极指南从基础操作到高级窗口控制GlazeWM窗口管理器终极指南从基础操作到高级窗口控制 GlazeWM是一款专为Windows系统设计的平铺式窗口管理器灵感来源于i3wm和Polybar桌面应用上一篇GetQzonehistory 实操3 条命令免费完整导出你 QQ 空间的全部历史说说与图片下一篇打造高质量应用UltimateRecyclerView测试策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考