电绘匣上架:把 QElectroTech 整体搬上鸿蒙 PC—— Qt-OHOS 运行时迁移实录
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
适配开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_QElectroTech
电气原理图工具是工程师桌面上另一类"重"软件:元件库庞大、渲染与编辑引擎深度耦合 Qt、工程文件是自家私有格式。开源界的常青树 QElectroTech 在 Linux/Windows 上服役多年,但 HarmonyOS PC 上一直没有能跑起来的 QElectroTech。我们把它整体迁移上了鸿蒙 PC,做成应用「电绘匣」——主窗口、菜单栏、工具栏、元件库面板、图纸渲染全部是原汁原味的 QElectroTech,可与应用「MPC 里的 K-Lite 播放器」们同框的又一款鸿蒙 PC 工具。

这一次走的是"整体迁移"路线:ArkTS 只做壳——
UIAbility/XComponent提供窗口容器与生命周期管理,Qt-OHOS 运行时(libqohos.so)把 Qt 事件循环接入 HarmonyOS,真正承载业务的libqelectrotech.so由上游源码交叉编译产出。QElectroTech 的业务代码一行没改,主窗口画面与桌面版完全同源。文中代码均取自上架工程的真实源码,截图来自鸿蒙 PC 真机实拍。
先看最终成果——在鸿蒙 PC 的应用市场里,它已经站在可以点击「打开」的位置:

图1:上架后的应用市场详情页实拍。应用名「电绘匣」,副标题"电气原理图绘制软件",分类「工具」,年龄分级 3+,开发者朱博。介绍图主打三张卡片:“一页看懂”、“真实 .qet 工程,整图自适应”、“打开图纸,即刻开工”。截图时正值上架初期:安装 <1万次、1 个评分 5.0。
一、作品速览:电绘匣是什么
电绘匣是一款面向 HarmonyOS PC(2in1 / 平板)设备的电气原理图工具。它承载的不是重写版,而是 QElectroTech 本体:上游 C++/Qt 业务代码交叉编译为 libqelectrotech.so(约 16.6 MB),由 Qt-OHOS 运行时在鸿蒙上拉起——这是与"照着格式重写一个应用"完全不同的迁移思路,换来的是与桌面版逐像素同源的渲染保真度。
在鸿蒙 PC 桌面上启动,它是这样一个原生窗口:Qt 主窗口经 XComponent 挂载,菜单栏、工具栏、左侧元件库面板、图纸区一览无余。启动时只解压示例、不自动加载图纸——空态画布配操作引导,用户从工具栏自主打开内置示例或本地工程:

图2:真机运行实拍。启动即空白画布,不自动加载图纸;空态给出明确操作引导"点击工具栏「示例图纸」查看内置示例,或「打开 .qet…」打开本地工程文件"。这不是功能缺失,而是刻意的保守策略——规避 Qt-OHOS 平台层尚未完善的模态子窗口链路(第四节详述)。
打开内置的 741 运放示例工程后,65 个元件、67 条导线、11 个元件定义全部呈现:三极管、电阻、电容、输入输出端子(Non-inverting/Inverting input/Output),网格、图框、标注一应俱全:

图3:内置示例工程 741.qet 渲染实拍。65 元件、67 导线、11 元件定义与桌面版打开同一文件完全一致——因为渲染这条链路压根就是 QElectroTech 自己的代码在跑,Qt-OHOS 只负责把 QPainter 的输出接到鸿蒙的 surface 上。
放大到 303%,点选一个电阻,界面立刻给出它的全部身份信息:名称 R3 39k、定义路径 embed/import/ozanacan/teklek_08.elt、坐标 (540, 270)、方向 0°、端子与图元数目,选中态以高亮框呈现:

图4:高倍缩放下的元件点选实拍。选中元件高亮、导线端子精确落在图元端点上——这条"元件库定义 → 端子坐标 → 图纸绝对坐标 → 导线闭合"的几何链路是 QElectroTech 原生逻辑,迁移层没有做任何重算。
关于页面则把"它是什么、不是什么"说得很清楚:基于开源 QElectroTech 的电气原理图工具、遵循上游 GPL 许可、示例元件图形来自 QElectroTech 开源项目并单独声明版权、隐私边界与应用能力逐条写明:

图5:关于页面实拍。核心能力、格式与互操作、许可与致谢逐条展开——上架应用把"许可边界"写进应用内,而不是只藏在商店文案里,这也是过审的一个加分项。
功能面概括起来是五块:
- 主窗口完整呈现:菜单栏、工具栏、左侧元件库分类树、图纸区、状态栏全套渲染,交互手感与桌面版一致;
- 图纸查看:打开本地或内置
.qet工程,多页图纸翻页,缩放平移,网格/图框/标题栏/元件/导线/文字标注由 QElectroTech 原生渲染; - 元件信息点选:点选元件即得定义路径、坐标、朝向、端子/图元数目等完整身份信息;
- 示例工程内置:6 个
.qet示例随包解压到应用沙箱,启动即达、随开随看; - 系统能力桥接预留:40+ 个 HarmonyOS Kit 已通过桥接层导出给 Qt 侧,文件选择器、打印等链路按需启用。
二、迁移路线:为什么是"搬程序",而不是"搬格式"
两条路线的分界线
面对 QElectroTech 这类应用,社区常见两条路:格式移植——只解析 .qet 文件、用原生 UI 重写一个查看器;整体迁移——把 Qt 程序连同运行时搬上鸿蒙。选择的关键在于上游的核心资产到底在哪。
QElectroTech 的核心资产在程序逻辑里:庞大的元件库体系、图元渲染引擎、导线端子几何、编辑交互、.qet 读写,全部深度耦合在 C++/Qt 代码中。格式移植意味着用另一门技术栈重写一个大而全的绘图软件——保真度低、跟随上游升级的成本无穷大,而且元件库这套"活资产"(上千个社区元件定义、持续更新)根本带不走。所以我们的策略是一句话:
业务代码零改写:ArkTS 做壳(窗口容器 + 生命周期),Qt-OHOS 做桥(事件循环 + QPA 平台插件),交叉编译的
libqelectrotech.so做里子——三层各司其职。
这条路线的代价也很清楚:Qt5 运行时全套 .so 随包(约 40 MB native 库)、需要处理 Qt-OHOS 平台层的成熟度问题、GPL 许可要求合规分发。但换来的是:主窗口渲染、元件库、图纸几何全部与桌面版同源,741.qet 在鸿蒙上打开的每一个像素都是 QElectroTech 自己画的。
工程结构自证
整个工程的目录一眼看下去,"三层架构"落在实处:
ohos_QElectroTech/ # 单仓库,主模块 entry + 特性模块
├── AppScope/ # 应用级配置(bundleName / 图标 / 版本)
├── entry/src/main/ets/
│ ├── qabilitystage/QAbilityStage.ets # AbilityStage:Qt 初始化入口、示例解压
│ ├── qability/QAbility.ets # UIAbility:全生命周期事件桥接给 Qt
│ ├── qability/OhosExportModules.ts # 40+ 系统 Kit 导出给 Qt 侧调用
│ ├── qability/QtUtils.ets # 模块表组装(LocalStorage / EmbeddedUI 注入)
│ ├── pages/ # 主窗口/子窗口/浮窗/Extension 四类 XComponent 容器
│ └── process/QChildProcess.ets # Qt 子进程接入
├── entry/libs/arm64-v8a/ # 全量运行时库(Qt5 + QPA 插件 + libqelectrotech.so)
├── entry/src/main/resources/rawfile/qet_examples/ # 内置 6 个 .qet 示例工程
└── qEmbeddedUiExtensionHost/ # Embedded UI 跨应用嵌入验证模块
需要特别说明:entry/libs/arm64-v8a/ 里的库是全量随仓库交付的——libqelectrotech.so、libqohos.so、libQt5{Core,Gui,Widgets,Network,Sql,Svg,Xml,PrintSupport,Concurrent,OhosExtras}.so、libc++_shared.so,加上 platforms/、styles/、imageformats/ 三个 Qt 插件目录。克隆即可构建,不要求使用者自己交叉编译。
三、核心技术实现
3.1 Qt 应用装载:一次 setupQtApplication 完成初始化
整个迁移的"点火"动作发生在 AbilityStage 里。QAbilityStage 在应用上下文就绪后做三件事:校验 QPA 可加载、解压示例工程到沙箱、把 Qt 应用交给 Qt-OHOS 运行时:
// entry/src/main/ets/qabilitystage/QAbilityStage.ets(节选)
QAbilityStage.setupQtApplicationCalled = true;
qpa.setupQtApplication({
appContext: appContext,
modules: QtUtils.getModulesMapForQt(), // OhosExportModules 导出的系统 API 表
appName: APP_LIBRARY_NAME, // 'libqelectrotech.so'
appArgs: QAbilityStage.appArgs, // 特意不注入自动打开 .qet 的参数
abilityClassName: abilityClassName,
uiExtensionMode: uiExtensionMode,
_unusedQChildProcess: new QChildProcess(),
});
qpa 来自 import qpa from 'libqohos.so'——Qt-OHOS 运行时以 NAPI 模块形态暴露给 ArkTS 侧。appName 指向业务库文件名,运行时据此 dlopen 业务库并驱动它的 main(),QElectroTech 就此跑起来。示例解压是独立的一步:
// 把 rawfile/qet_examples/*.qet 解压到 filesDir/QET_examples/,
// 供用户在应用内手动打开。注意:不注入 argv 让 Qt 启动即加载 .qet,
// 否则会触发 DialogWaitingWindow 子窗口崩溃(平台层问题,见第四节)。
const samplesDir: string | null = QAbilityStage.unpackAllSamples(appContext);
3.2 生命周期桥接:UIAbility 事件全量转发
鸿蒙的前后台语义和 Qt 的事件循环是两套世界,中间靠一层"全量转发"缝合。QAbility 把 UIAbility 的每一个回调原封不动交给 qpa.handleAbility* 系列:
// entry/src/main/ets/qability/QAbility.ets(节选)
onWindowStageCreate(windowStage: Window.WindowStage) {
qpa.handleAbilityOnWindowStageCreate(this, windowStage);
}
onForeground() { qpa.handleAbilityOnForeground(this); }
onBackground() { qpa.handleAbilityOnBackground(this); }
onDestroy(): void | Promise<void> { return qpa.handleAbilityOnDestroy(this); }
onContinue(wantParam: Record<string, Object>) {
return qpa.handleAbilityOnContinue(this, wantParam); // 一多接续也走桥接
}
这样 QApplication 的激活/休眠状态始终与鸿蒙前后台同步,Qt 侧的定时器、动画、文件监听在切后台时正确挂起。onPrepareToTerminate 还处理了鸿蒙的受控退出语义(工程申请了 ohos.permission.PREPARE_APP_TERMINATE),保证用户关窗时 Qt 侧有机会保存现场。
3.3 窗口容器:XComponent 承载 Qt surface
Qt 主窗口最终画在哪?答案是四个页面容器,按场景分流:
// entry/src/main/resources/base/profile/main_pages.json
{ "src": [
"pages/MainWindowNativeNode", // 主窗口:XComponent + NodeContainer 承载 Qt 主 surface
"pages/SubWindowNativeNode", // 子窗口:模态对话框场景预留
"pages/FloatWindowNativeNode", // 浮窗:悬浮面板场景预留(SYSTEM_FLOAT_WINDOW 已申请)
"pages/UiExtensionNativeNode" // Extension 窗口:跨应用嵌入场景
] }
MainWindowNativeNode 是核心路径:XComponent 的 surface 交给 Qt-OHOS 平台插件,QPainter 的绘制输出直接落到鸿蒙渲染管线上。因为渲染和窗口尺寸变化都走同一套 surface,窗口拖拽缩放时 Qt 侧收到的是标准的 QResizeEvent,图纸自适应不需要宿主做任何额外计算。
3.4 系统能力桥接:40+ 个 Kit 一次导出
ArkTS 宿主不只是"壳",还扮演 Qt 侧的系统能力代理。OhosExportModules.ts 把应用框架、窗口、文件、输入、多媒体、网络、蓝牙/USB/定位等 HarmonyOS Kit 组装成一张 NAPI 对象表,随 setupQtApplication 注入:
// entry/src/main/ets/qability/OhosExportModules.ts(节选)
import __ohos__file__picker from '@ohos.file.picker'
import __ohos__window from '@ohos.window'
import { fileManagerService as __kit__FileManagerServiceKit__fileManagerService } from '@kit.FileManagerServiceKit';
// … 40+ 个 Kit 同样方式导入
export function getOhosExportModules(): object {
return {
'@ohos.file.picker': __ohos__file__picker,
'@ohos.window': __ohos__window,
'@kit.FileManagerServiceKit.fileManagerService': __kit__FileManagerServiceKit__fileManagerService,
// …
};
}
QElectroTech 业务里凡是碰到"打开文件""访问窗口属性"这类桌面系统调用,都可以经这张表落到鸿蒙原生实现上——不需要改业务代码,只需要平台层把 QFileDialog 等 Qt 抽象映射过来。权限层面工程已声明 FILE_ACCESS_PERSIST、PRINT、READ_PASTEBOARD、GET_FILE_ICON 等,按能力启用节奏逐步生效。
3.5 构建产物:一个 HAP 装下整个桌面应用
module.json5 声明 deviceTypes: ["tablet", "2in1"]、ABI 仅 arm64-v8a,与鸿蒙 PC 真机一一对应;SDK 版本 6.1.0(23)(build-profile.json5)。最终 HAP 的构成:
entry-default-signed.hap
├── ets/ ArkTS 宿主(AbilityStage / Ability / 四个窗口容器页面)
├── libs/arm64-v8a/
│ ├── libqelectrotech.so # 16.6 MB,业务本体(交叉编译产物)
│ ├── libqohos.so + platforms/ # Qt-OHOS 运行时 + QPA 平台插件
│ ├── libQt5*.so × 10 # Qt 5.12.12 运行时
│ ├── styles/ + imageformats/ # 原生风格插件 + 9 种图片格式编解码
│ └── libc++_shared.so
└── resources/rawfile/qet_examples/ # 6 个 .qet 示例
一个值得强调的工程约束:libqohos.so、libQt5*.so、三个插件目录必须来自同一套 Qt-OHOS 构建产物,混用不同版本的 QPA 插件与 Qt 库会直接崩溃——升级运行时时整套替换,不做拼盘。
四、QA:质量验证与踩坑
4.1 功能分级:T0 / T1 / T2 如实盘点
我们没有用"全部支持"这种模糊话术,而是按 T0(基础承载)/ T1(主要业务)/ T2(增强与受限)三级如实盘点:
| 层级 | 覆盖内容 | 进度 |
|---|---|---|
| T0 基础承载 | HAP 构建签名、安装启动、Qt 应用装载链路、主窗口完整渲染(菜单栏/工具栏/元件库/图纸区)、示例解压、运行时库随包交付 | 100% |
| T1 主要业务 | 元件库浏览、图纸渲染与缩放、元件点选与信息展示、KF5 控件 shim(KColorButton/KColorCombo)、内嵌 SQLite3 | 约 70% |
| T2 增强/受限 | 新建/打开/保存工程、导出与打印、浮窗/子窗口、Embedded UI 跨应用嵌入、一多接续、系统桥接业务化 | 约 25% |
T2 层面的核心阻塞点只有一个根因,见下节。修掉它,文件链路上的多条"待完善"可以批量解锁。
4.2 踩坑记录
坑一:Qt-OHOS 模态对话框崩溃(当前唯一硬阻塞)。 新建工程、打开工程、启动即加载 .qet,这些操作都会触发 DialogWaiting 模态 QDialog,随后 SIGSEGV 闪退。根因定位在 Qt-OHOS 平台插件层,不在业务代码:Qt 的模态对话框依赖独立子窗口 + 父子 transient/modal 语义 + 嵌套事件循环(exec()),平台插件对这条链路的实现不完整,崩溃点表现为 QOhosWindowProxy 路径上的空指针解引用。应对:启动阶段只解压示例、不注入自动打开的 argv(QAbilityStage.ets 里写明了原因),所有会触发 DialogWaitingWindow 的自动路径全部规避;修复路径是完善平台插件的 modal 子窗口实现后重编整套 Qt-OHOS 库,业务层零改动。
坑二:自动签名不会自动挂签名配置。 DevEco「自动签名」只把材料填进 signingConfigs,不会在 products 里写 "signingConfig": "default" 引用——缺了这一行,构建产出的是 unsigned HAP,真机安装直接报 9568320。每次自动签名后必须检查这个引用是否存在。这个坑属于"报错信息完全不指向根因"的类型,值得每个 CLI 构建的人记住。
坑三:包名规范。 鸿蒙包名不能以 ohos 结尾;工程当前用的是示例包名 com.example.qelectrotechohos,正式分发前需改为自有命名,且顺序是先重新生成签名 profile、再改 bundleName——反了会签名与包名不匹配、安装失败。
坑四:GPL 分发合规。 上游 QElectroTech 是 GPL v2+,整体迁移路线意味着 libqelectrotech.so 作为二进制随 HAP 分发,必须满足 GPL 的源码可获得义务——业务库构建脚本与源码入口公开托管,关于页与 README 里明确声明上游许可;内置示例中的元件图形带有独立的 elements_license 声明,单独标注权利归原作者。这比"格式兼容重写"路线的许可处理要重,但合规路径是清晰的。
坑五:运行时库同源性。 真机上一度出现主窗口黑屏但进程存活,排查到是 QPA 插件与 Qt 库版本不配套。结论如 3.5 节:Qt-OHOS 运行时必须整套替换。定位手段是 hdc shell hilog | grep QElectroTechOhos——工程内日志统一走 LOG_TAG = 'QElectroTechOhos',从 setupQtApplication 到 MainWindowNativeNode 挂载全程有日志埋点,哪一环断了看得一清二楚。
五、上架与复现
应用已在鸿蒙 PC 应用市场正式上架(图1)。想复现这条迁移路线,核心命令只有三条——构建、部署、看日志:
# 构建(Windows / DevEco Studio 5.x+,SDK 6.1.0(23))
$env:DEVECO_SDK_HOME = 'C:\Program Files\Huawei\DevEco Studio\sdk'
& 'C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin\hvigorw.bat' `
--mode module -p module=entry@default -p product=default assembleHap --no-daemon
# 真机部署与启动
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a QAbility -b com.example.qelectrotechohos -m entry
# 运行日志(Qt 初始化 / 示例解压 / 生命周期分发全程埋点)
hdc shell hilog | findstr QElectroTechOhos
仓库已按开源规范公开:宿主工程与运行时库全量入库、克隆即可构建;签名材料(p12/cer/p7b 与本机路径)不入仓,公开托管前清空 signingConfigs。
六、总结:整体迁移路线的适用边界
回看这次迁移,"搬程序"和"搬格式"的分界线其实很清晰:
- 上游核心资产在程序逻辑里(渲染引擎、元件库体系、编辑交互深度耦合 Qt),业务代码值得保真 → 整体迁移是最优解:渲染逐像素同源、跟随上游升级几乎零成本、庞大的社区元件库原样带过来;
- 上游核心资产在文件格式里(交互层薄、可原生重写),且对包体/权限有极致要求 → 格式移植更合适,代价是保真度与跟随成本。
电绘匣当前仍有边界:文件的新建/打开/保存闭环受模态对话框平台问题阻塞,浮窗、Embedded UI、跨端接续处于预留状态。但"装得起、起得来、看得见"的 T0 已经闭环,T2 的阻塞是单点、已知、有明确修复路径的平台问题——用户手里的历史工程文件在这个鸿蒙 PC 应用里已经能原样打开浏览,而它打开图纸的每一个像素,都是 QElectroTech 自己画的。这就是整体迁移路线存在的意义。
更多推荐




所有评论(0)