欢迎加入开源鸿蒙 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 挂载,菜单栏、工具栏、左侧元件库面板、图纸区一览无余。启动时只解压示例、不自动加载图纸——空态画布配操作引导,用户从工具栏自主打开内置示例或本地工程:

鸿蒙 PC 桌面运行:空态引导

图2:真机运行实拍。启动即空白画布,不自动加载图纸;空态给出明确操作引导"点击工具栏「示例图纸」查看内置示例,或「打开 .qet…」打开本地工程文件"。这不是功能缺失,而是刻意的保守策略——规避 Qt-OHOS 平台层尚未完善的模态子窗口链路(第四节详述)。

打开内置的 741 运放示例工程后,65 个元件、67 条导线、11 个元件定义全部呈现:三极管、电阻、电容、输入输出端子(Non-inverting/Inverting input/Output),网格、图框、标注一应俱全:

内置示例工程:741 运放电路

图3:内置示例工程 741.qet 渲染实拍。65 元件、67 导线、11 元件定义与桌面版打开同一文件完全一致——因为渲染这条链路压根就是 QElectroTech 自己的代码在跑,Qt-OHOS 只负责把 QPainter 的输出接到鸿蒙的 surface 上。

放大到 303%,点选一个电阻,界面立刻给出它的全部身份信息:名称 R3 39k、定义路径 embed/import/ozanacan/teklek_08.elt、坐标 (540, 270)、方向 0°、端子与图元数目,选中态以高亮框呈现:

缩放 303% 点选元件查看属性

图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 自己画的。这就是整体迁移路线存在的意义。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐