拓十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

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

NodeGui QProgressBar 实战指南:用 JavaScript 创建与操控原生进度条控件

NodeGui QProgressBar 实战指南:用 JavaScript 创建与操控原生进度条控件 桌面应用跨平台【免费下载链接】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点击查看免费下载QProgressBar 是 NodeGui 中对 Qt 原生进度条控件的 TypeScript/JavaScript 封装类用于在跨平台桌面应用中创建、操控和美化进度条。本文基于 NodeGui 仓库中 QProgressBar 官方 API 文档 展开并结合其 TypeScript 包装层与 C 原生实现源码完整讲解构造函数、值域范围、文本格式、方向外观、事件信号等核心用法读完即可在你的 NodeGui 应用中落地一个可运行的进度条组件。类概述与继承层级Create and control progress bar widgets.正如 QProgressBar 类的 JSDoc 描述 所言QProgressBar是 Qt 原生QProgressBar类的一个 JS 包装它提供添加和操控原生进度条控件的能力。它并不从零实现绘制逻辑而是把 JS 层的属性设置与信号监听桥接到 Qt C 的原生控件上。在类型层级上QProgressBar直接继承自 QWidget并以QProgressBarSignals作为其信号泛型参数QWidgetQProgressBarSignals ↳ QProgressBar这意味着凡是QWidget能做的几何管理、显示隐藏、样式表、焦点、拖放等QProgressBar全部继承可用同时它额外扩展了进度条专属的属性、方法与信号。构造函数构造函数签名如下覆盖自QAbstractSlider的构造器new QProgressBar(arg?: QWidgetQWidgetSignals | NativeElement): QProgressBar无参数调用new QProgressBar()创建一个独立进度条传入父控件new QProgressBar(parentWidget)创建并挂载到指定父控件下传入原生句柄arg也可以是NativeElement用于包装已有的 C 原生实例通常由框架内部使用。属性QProgressBar继承自组件体系的三个基础属性属性类型说明_rawInlineStylestring原始内联样式字符串来自 QMenu 基类nativeNativeElement \| null底层 C 原生对象的引用来自 Componenttypestring控件类型标识同样继承自QMenu基类快速上手创建第一个进度条官方文档给出的最小示例const { QProgressBar } require(nodegui/nodegui); const progressBar new QProgressBar();在 NodeGui 中进度条通常要配合一个窗口和 Flex 布局才能显示出来。一个最小可运行的完整示例const { QMainWindow, QProgressBar, QWidget, FlexLayout } require(nodegui/nodegui); const win new QMainWindow(); const root new QWidget(); root.setObjectName(root); root.setLayout(new FlexLayout()); const progressBar new QProgressBar(root); progressBar.setRange(0, 100); // 值域 0 ~ 100 progressBar.setValue(65); // 当前进度 65% progressBar.setFixedWidth(280); root.layout().addWidget(progressBar); win.setCentralWidget(root); win.resize(320, 120); win.show(); global.win win; // 防止被垃圾回收该示例展示了进度条的核心三件套设定范围setRange→ 设定当前值setValue→ 加入布局显示。核心方法详解值域、文本与外观QProgressBar自身定义的方法与对应取值方法成对出现遵循 Qt 属性系统惯例下面按功能分组完整讲解。值域与进度控制方法类型说明setMinimum(minimum: number)/minimum(): numbernumber设置/读取进度条最小值默认 0setMaximum(maximum: number)/maximum(): numbernumber设置/读取进度条最大值默认 100setRange(minimum: number, maximum: number)void一次性设置最小值和最大值setValue(value: number)/value(): numbernumber设置/读取当前进度值取值会被自动钳制在[minimum, maximum]区间内reset()void将当前值重置为最小值其中setRange、reset、resetFormat三个方法并不是通过 Qt 属性系统实现的而是直接在 C 原生层暴露为实例方法。从 qprogressbar_wrap.cpp 可以看到NodeGui 的 C 包装类QProgressBarWrap只显式导出了这三个方法其余全部复用QWIDGET_WRAPPED_METHODS_EXPORT_DEFINE宏继承自QWidget的通用方法setRange的底层实现就是把两个整型参数直接转发给 Qt 的QProgressBar::setRangeNapi::Value QProgressBarWrap::setRange(const Napi::CallbackInfo info) { Napi::Env env info.Env(); int minimum info[0].AsNapi::Number().Int32Value(); int maximum info[1].AsNapi::Number().Int32Value(); this-instance-setRange(minimum, maximum); return env.Null(); }文本与显示格式方法类型说明format(): string/setFormat(format: string)string读取/设置进度条上显示的文本模板resetFormat()void将显示格式重置为 Qt 默认模板%p%即百分比text(): stringstring返回当前实际显示的文本内容只读setTextDirection(textDirection: QProgressBarDirection)/textDirection(): QProgressBarDirection枚举设置/读取文本绘制方向见下文QProgressBarDirectionsetTextVisible(visible: boolean)/isTextVisible(): booleanboolean显示/隐藏进度百分比文本Qt 的进度条文本模板支持以下占位符可直接用在setFormat的字符串中占位符含义示例%p完成百分比65%%v当前值65%m剩余值最大值 − 当前值35例如progressBar.setFormat(%v / %m 剩余)会显示类似65 / 35 剩余的文本。调用resetFormat()后回到默认的%p%。方向与外观方法类型说明setOrientation(orientation: Orientation)/orientation(): Orientation枚举设置/读取进度条方向横向或纵向setInvertedAppearance(invert: boolean)/invertedAppearance(): booleanboolean反转填充方向默认从左到右 / 从下到上填充反转后相反setAlignment(alignment: AlignmentFlag)/alignment(): AlignmentFlag枚举设置/读取进度条上文本的对齐方式信号与事件监听QProgressBar通过泛型参数绑定的信号接口是QProgressBarSignals。从 QProgressBar.ts 的源码可以看到它只扩展了一个专属信号export interface QProgressBarSignals extends QWidgetSignals { valueChanged: (value: number) void; }valueChanged在进度值每次变化时触发回调参数为新的值。它的底层连接实现在 C 原生类 NProgressBar 中——NProgressBar继承自QProgressBar并实现了NodeWidget接口在connectSignalsToEventEmitter()里把 Qt 信号转发为 NodeGui 事件发射QObject::connect(this, QProgressBar::valueChanged, { Napi::Env env this-emitOnNode.Env(); Napi::HandleScope scope(env); this-emitOnNode.Call({Napi::String::New(env, valueChanged), Napi::Number::New(env, value)}); });因此 JS 侧可以这样监听进度变化progressBar.addEventListener(valueChanged, (value) { console.log(当前进度: ${value}); });同时由于继承自 EventWidget你还可以通过WidgetEventTypes监听HoverEnter、MouseMove等底层控件事件并通过setEventProcessed(isProcessed)标记事件已处理、阻止其继续冒泡。移除监听则使用removeEventListener。相关枚举参考QProgressBarDirection定义于 QProgressBar.ts用于setTextDirection/textDirection()枚举值数值含义TopToBottom0文本从上到下排列BottomToTop1文本从下到上排列AlignmentFlag用于setAlignment定义于 AlignmentFlag/index.ts核心取值可按位组合水平/垂直各取其一枚举值数值含义AlignLeft0x0001水平左对齐AlignRight0x0002水平右对齐AlignHCenter0x0004水平居中AlignTop0x0020垂直顶部对齐AlignBottom0x0040垂直底部对齐AlignVCenter0x0080垂直居中AlignCenter0x0084水平垂直双向居中AlignHCenter \| AlignVCenterOrientation用于setOrientation定义于 Orientation/index.ts枚举值数值含义Horizontal0x1水平进度条默认Vertical0x2垂直进度条从源码看 QProgressBar 的封装原理TypeScript 包装层QProgressBar.ts 是 JS 侧的核心封装值得注意的实现细节构造函数三分支通过checkIfNativeElement(arg)判断参数类型——原生句柄直接复用、QWidget传入作为父控件、无参数则调用new addon.QProgressBar()创建独立实例QProgressBar.ts 第 25-36 行。属性桥接机制绝大多数setXxx方法并没有直接调用原生方法而是走this.setProperty(xxx, value)读取时用this.property(xxx).toInt() / .toString() / .toBool()。这意味着这些配置项全部通过 Qt 的动态属性系统写入原生控件而 Qt 的QProgressBar会把属性名映射到对应的原生属性上——这是 NodeGui 封装属性成对方法的通用模式。WrapperCache 注册类定义末尾执行wrapperCache.registerWrapper(QProgressBarWrap, QProgressBar)第 104 行将 JS 类注册进 NodeGui 的包装缓存系统用于保证同一个原生控件在 JS 侧始终对应同一个包装实例避免重复包装与内存泄漏。C 原生层包装类qprogressbar_wrap.cpp 用 N-API 定义QProgressBar类构造函数支持无参新建 / 传父控件新建 / 包装既有 External 实例三种路径并调用extrautils::configureQWidget完成控件的基础配置。注册入口该包装类在 src/cpp/main.cpp 被引入并在 第 201 行 通过QProgressBarWrap::init(env, exports)注册到 Node.js addon 的导出对象上从而暴露为 JS 侧的addon.QProgressBar。节点化基类NProgressBar同时继承QProgressBar与NodeWidget使其具备 Yoga 布局节点能力因此进度条可以像其他 NodeGui 控件一样参与 Flex 布局并接受内联样式。继承的方法体系QProgressBar实例实际可调用的方法远不止上述专属方法——文档索引中列出的其余方法全部来自继承链主要包括QWidget 几何与显示show()/hide()/resize()/move()/setGeometry()/setFixedSize()/setMinimumSize()/setMaximumSize()/setVisible()/setWindowTitle()等QWidget 样式setInlineStyle(style, postprocess?)/setStyleSheet(styleSheet, postprocess?)/repolish()/setFont()QObject 对象模型objectName()/setObjectName()/property()/setProperty()/delete()/deleteLater()/inherits()/startTimer()Yoga/Flex 布局getFlexNode()/setFlexNodeSizeControlled()见 YogaWidget焦点与拖放setFocusPolicy()/setAcceptDrops()/setCursor()等。完整方法索引见 QProgressBar API 文档。综合实战带动画效果的下载进度条结合本文全部知识点给出一个完整的实战示例——用定时器模拟下载进度并实时更新文本格式const { QMainWindow, QProgressBar, QWidget, FlexLayout } require(nodegui/nodegui); const win new QMainWindow(); const root new QWidget(); root.setObjectName(root); root.setLayout(new FlexLayout()); const progressBar new QProgressBar(root); progressBar.setRange(0, 100); progressBar.setValue(0); progressBar.setFormat(%v / %m 剩余); progressBar.setAlignment(1); // Qt.AlignLeft可改用 AlignmentFlag.AlignLeft progressBar.setFixedSize(280, 30); root.layout().addWidget(progressBar); win.setCentralWidget(root); win.resize(320, 120); win.show(); let current 0; const timer setInterval(() { current 5; if (current 100) { clearInterval(timer); progressBar.setFormat(完成); return; } progressBar.setValue(current); // 触发 valueChanged 信号 }, 200); progressBar.addEventListener(valueChanged, (value) { console.log(进度: ${value}%); }); global.win win;要点回顾setRange(0, 100)与setValue()共同决定进度条的表现与valueChanged信号的触发setFormat支持%p、%v、%m占位符resetFormat()恢复默认百分比显示valueChanged信号监听用于在进度更新时联动 UI 或日志需要纵向进度条时使用setOrientation(Orientation.Vertical)需要反向填充时使用setInvertedAppearance(true)。相关资源官方 API 文档website/docs/api/generated/classes/qprogressbar.mdTypeScript 封装源码src/lib/QtWidgets/QProgressBar.tsC 包装实现src/cpp/lib/QtWidgets/QProgressBar/qprogressbar_wrap.cppC 原生节点类src/cpp/include/nodegui/QtWidgets/QProgressBar/nprogressbar.hpp信号接口website/docs/api/generated/interfaces/qprogressbarsignals.md枚举定义QProgressBarDirection | AlignmentFlag | Orientation赞分享桌面应用跨平台【免费下载链接】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 QScrollBar 实战指南在 Node.js 桌面应用中创建与操控原生滚动条NodeGui QScrollBar 实战指南在 Node.js 桌面应用中创建与操控原生滚动条 NodeGui 为 Qt 的 QScrollBar 提供了完桌面应用跨平台Envoy 上游集群Upstream Clusters配置完全指南Cluster Manager、健康检查与运行时调优Envoy 上游集群Upstream Clusters配置完全指南Cluster Manager、健康检查与运行时调优 导读 本指南围绕 Envoy 配置桌面应用跨平台NodeGui QTextEdit 开发指南在原生桌面应用中创建与操控富文本编辑控件NodeGui QTextEdit 开发指南在原生桌面应用中创建与操控富文本编辑控件 NodeGui 是一个用 Node.js 与 CSS 构建跨平台原生桌面桌面应用跨平台上一篇Maestro AI功能解析自动检测UI缺陷与提取文本下一篇Jellyscrub跨平台使用指南Web、桌面、iOS全客户端适配技巧创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表