Jaspersoft Studio CE 鸿蒙 PC 适配全记录：从 Eclipse RCP_SWT 到 Qt 原生报表设计器

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_jaspersoft-studio-ce

环境搭建文章：https://blog.csdn.net/weixin_52908342/article/details/161343743

一、为什么要适配 Jaspersoft Studio CE

Jaspersoft Studio CE 是 JasperReports 生态中最常用的可视化报表设计工具之一。它面向企业报表、账单、清单、运营统计和数据导出等场景，核心价值不只是编辑一份 XML，而是把页面布局、JRXML 结构、字段、参数、表达式、数据源和导出验证放在同一套桌面工作流里。对于长期使用 JasperReports 的团队来说，设计器的可视化画布、属性面板和源码视图之间的往返一致性，直接影响报表维护效率。

HarmonyOS PC 正在进入更多办公和研发场景。适配 Jaspersoft Studio CE 的意义在于验证一类更复杂的传统桌面软件如何落到鸿蒙应用模型中：它不是轻量文本编辑器，也不是单一网络客户端，而是一个由 Eclipse RCP、SWT、Java 服务、JRXML 模型、数据适配器和导出链路共同组成的桌面设计工具。只有把报表创建、画布编辑、源码回写、数据解析和文件导出跑通，才能说明适配结果具备实际使用价值。

本次适配以上游 Jaspersoft Studio CE 6.20.5 为基础，鸿蒙版本包名为 org.jaspersoft.studio.qt.harmony，版本为 6.20.5-qt-preview1，目标设备为 HarmonyOS PC / 2in1，Native ABI 为 arm64-v8a。原始 Eclipse/SWT 源码树保持不改动，鸿蒙适配代码集中在仓库内的 qt-ohos-migration/ 工作区。

二、先确定适配边界：不能把 Eclipse RCP 直接搬进普通 HAP

上游 Jaspersoft Studio CE 是 Java、Eclipse RCP 和 SWT 桌面应用。Eclipse RCP 依赖 OSGi 插件体系、SWT 原生窗口后端和传统桌面 JVM 运行环境；这些假设在 HarmonyOS PC 普通应用沙箱中并不成立。如果直接追求“原工程原样启动”，会同时遇到窗口后端、插件生命周期、JVM 可执行内存、文件权限和打包体积等问题。

因此，本次适配没有把原 RCP 工程硬塞进 HAP，而是把高频报表设计链路抽出来，用 Qt Widgets 和 QGraphicsView 重建桌面界面，并把能脱离 JVM 的能力放到 Native 进程中完成：

这一路线的重点是先把“可编辑、可回写、可预览、可验证”的主线跑通，而不是把暂时无法在普通沙箱内稳定运行的 JVM 编译和完整插件体系包装成已经完成。当前版本对完整 .jasper 编译、通用 JDBC 驱动、Office 格式导出和 JasperReports Server 发布保持明确边界。

三、鸿蒙版本的整体架构

鸿蒙工程位于 qt-ohos-migration/。Qt 负责主窗口、菜单、工具栏、Palette、Report Outline、属性面板、设计画布、源码页和预览页；ArkTS 与 DevEco/Hvigor 工程负责应用生命周期、HAP 打包、签名和 Native 库加载。JasperReports 相关的完整 JVM 能力保留为可选 Java 服务，但不计入当前普通应用沙箱内的真机通过项。

QAbility / HarmonyOS PC 窗口
│
▼
Qt for HarmonyOS QPA
│
▼
libjaspersoftstudioqt.so
├── Qt Widgets 主窗口、菜单和 Dock
├── QGraphicsView 报表设计画布
├── ReportDocument JRXML 模型与无损回写
├── HarmonyOS RDB/SQLite 兼容层
├── CSV / JSON / XML 数据解析
└── PDF / HTML / XML / CSV / RTF 原生导出

主要目录如下：

ohos_jaspersoft-studio-ce/
├── com.jaspersoft.studio*/ # 原 Jaspersoft Studio Eclipse/SWT 源码
├── README.OpenHarmony_CN.md # 鸿蒙适配记录
└── qt-ohos-migration/
├── src/ # Qt 主窗口、JRXML 模型、画布和数据功能
├── resources/ # Qt 资源与 Swiss 风格 QSS
├── java-service/ # 可选 JasperReports Java 服务
├── harmony-app/ # DevEco/Hvigor HAP 壳工程
├── qtforharmony_sdk/ # Qt 5.12.12 HarmonyOS arm64 SDK
├── scripts/ # 构建、校验和打包脚本
├── reports/ # 功能矩阵与真机核验结果
└── evidence/ # 真机截图与证据

这种结构把原始上游代码与鸿蒙重建工程隔离开来。原仓库仍能作为上游参考，鸿蒙版本则按可交付 HAP 的方式维护，避免平台适配反向污染原 Eclipse 插件源码。

四、真机上的核心运行结果

以下五张截图均来自当前签名 HAP 在 HarmonyOS PC 真机上的实际运行画面，通过 snapshot_display 从设备画面直接获取。验证设备为 HUAWEI MateBook Pro（HAD-W32，2in1），系统版本为 6.1.0.117，截图分辨率为 3120×2080。截图前已重新构建、签名并安装 arm64-v8a HAP，界面也针对高分辨率 PC 屏幕完成了字体、菜单、工具栏、Dock 和属性面板的放大优化。

1. 桌面报表设计器要先具备可读、可操作的信息架构

启动后可以看到典型报表设计器布局：顶部是菜单和工具栏，左侧是 Palette 与 Report Outline，中间是 Design、Source、Preview 三个工作页，右侧是 Properties 属性面板。Qt Widgets 在鸿蒙 PC 上承载了传统桌面软件需要的菜单、Dock、分栏、表单和状态栏。

这次适配后，界面不再沿用开发机上的小字号，而是根据 HarmonyOS PC 屏幕尺寸放大字体和 QSS 尺寸。对于报表设计器而言，这一点很关键：Palette、属性编辑和源码页都需要长时间阅读，如果只是“能启动”，但实际文字过小，工具就很难进入日常使用。

2. 设计画布需要支持真实元素创建和属性联动

在 Design 页中，从 Palette 拖入 Static Text 与 Rectangle 后，画布上会出现实际报表元素。选中元素后，右侧属性面板同步显示类型、文本、坐标和尺寸；Undo 按钮也能感知本次新增操作。

画布基于 QGraphicsView/QGraphicsScene 实现，支持拖放、选择、移动、缩放、网格背景和页面边界。这里验证的不是静态图片，而是 JRXML 模型、图形项、属性面板和 Undo 栈之间的同步关系。后续保存和切换 Source 页时，这些元素会回写为标准 JasperReports XML 节点。

3. JRXML 源码页必须和可视化模型保持一致

切换到 Source 页后，可以看到刚才在画布中添加的 staticText 和 rectangle 已经写入 JRXML。元素的 x、y、width、height、uuid 等属性都来自当前模型，而不是预置示例文本。

源码页的价值在于兼容实际报表维护习惯。很多企业报表会手工调整 JRXML，或者包含当前简化模型暂时不认识的节点。适配中专门处理了未知 XML 节点和属性的保留，避免用户打开复杂模板后，因为 Design/Source 往返编辑而破坏原文件结构。

4. 数据适配器不能停留在输入框层面

JasperReports 的报表设计离不开字段。当前鸿蒙版本在 Native 进程内实现了 CSV、JSON 和 XML 三类数据解析，并在真机上分别验证 3 个字段、2 行数据的读取结果。截图中的 PASS 来自应用内真实解析过程。

这部分没有依赖桌面 JVM，也没有把文件内容当作普通字符串展示。CSV 解析处理表头与数据行，JSON 解析数组对象结构，XML 解析重复节点集合，并统一转换为字段列表和预览表格。导入字段后，字段名会进入 JRXML 模型，供表达式和查询配置继续使用。

5. 常用导出能力在设备进程内闭环

报表工具最终要交付文件。当前鸿蒙版本已经在真机上完成 PDF、HTML、XML、CSV 和 RTF 的原生导出验证，并检查了输出字节数和文件签名。截图中五种格式均为 PASS，说明导出逻辑确实在设备端执行并生成文件。

其中 PDF 使用 Qt 绘制能力生成，HTML/XML/CSV/RTF 则由当前报表模型直接序列化。完整 Office 格式导出仍依赖 JasperReports JVM 生态，当前普通应用沙箱内尚未计为真机可用；这也是适配报告中明确标出的能力边界。

五、适配过程中遇到的主要困难

难点一：Eclipse RCP/SWT 与鸿蒙应用模型差异太大

Jaspersoft Studio CE 的桌面入口、菜单、编辑器、属性页和插件体系都围绕 Eclipse RCP 设计。HarmonyOS PC 普通应用无法直接提供 SWT 后端和完整 OSGi 桌面运行环境。适配时没有尝试逐个替换 SWT 控件，而是按报表设计流程重新划分能力，用 Qt 重建主窗口、Palette、Outline、属性面板、画布和源码页。

难点二：报表模型必须能在 Design 和 Source 之间往返

简单绘制几个矩形并不等于完成报表设计器。真正的难点是 JRXML 模型：页面尺寸、边距、Band、字段、参数、变量和报表元素都要能被解析、显示、修改并写回。对于暂时没有建模的 XML 内容，还需要继续保留，避免破坏用户已有模板。当前 ReportDocument 负责这条链路，并通过主机测试和真机操作共同验证。

难点三：JVM 能力在普通应用沙箱内存在硬边界

完整 JasperReports 编译、填充和 Office 导出依赖 JVM。真机环境中虽然可以找到 BiSheng/OpenJDK 17，但普通应用沙箱阻止 HotSpot 建立可执行代码内存，因此不能把 .jasper 编译和全部 Java 导出能力写成已完成。当前版本把能原生实现的功能先落到 Qt 进程内，必须依赖 JVM 的部分保留为后续系统服务或更高权限通道。

难点四：文件访问和数据库能力需要遵守鸿蒙权限边界

桌面软件习惯直接使用本地路径，HarmonyOS 文件选择器则可能返回 URI 或授权文件描述符。适配中通过平台层把授权 URI 转换为可读写路径，再交给 Qt 文件逻辑处理。数据库方面，界面仍兼容 jdbc:sqlite: 的配置形式，但设备端实际映射到 HarmonyOS 原生 RDB/SQLite，避免在普通沙箱里依赖 JVM JDBC 驱动。

难点五：高分辨率 PC 屏幕需要重新校准桌面 UI

初版 Qt 界面在真机上可以运行，但菜单、Palette 和属性面板显示偏小，不适合长期使用。后续根据 HarmonyOS PC 屏幕尺寸增加了 UI 缩放：字体、QSS 像素尺寸、工具栏图标、Dock 宽度、Palette 行高、属性面板间距和对话框尺寸都随设备放大。优化后，截图中的菜单和表格已经可以在 3120×2080 屏幕上直接阅读。

六、构建、安装与启动

首次构建需要准备 DevEco Studio、HarmonyOS Native SDK 和 Qt for HarmonyOS。当前仓库随 qt-ohos-migration/qtforharmony_sdk/ 提供 Qt 5.12.12 HarmonyOS arm64-v8a SDK，构建脚本会先检查 qmake、Qt 库、QPA 插件和 SDK 可迁移性。

主机侧快速验证：

cd qt-ohos-migration
cmake -S . -B build-host -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake –build build-host
ctest –test-dir build-host –output-on-failure

HarmonyOS 交叉编译与 HAP 构建：

cd qt-ohos-migration
./scripts/check-vendored-qt.sh
./scripts/build-ohos.sh
./scripts/build-hap.sh

签名产物位于：

qt-ohos-migration/harmony-app/entry/build/default/outputs/default/
├── entry-default-signed.hap
└── entry-default-unsigned.hap

连接 HarmonyOS PC 后，可安装并启动：

hdc list targets
hdc install -r harmony-app/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -b org.jaspersoft.studio.qt.harmony -a QAbility

本次文档截图使用的 HAP 已在真机安装并启动，五张截图均来自同一设备的当前运行画面。

七、当前能力与边界

当前版本已经覆盖 Jaspersoft Studio CE 在鸿蒙 PC 上的主要报表设计闭环：

• 新建、打开、保存 JRXML；
• Design / Source / Preview 三页切换；
• Palette 拖放创建常用报表元素；
• 元素选择、移动、缩放、属性编辑和 Undo/Redo；
• Report Outline 显示参数、字段、变量和 Band；
• JRXML 解析、源码回写和未知节点保留；
• 表达式编辑与字段引用检查；
• jdbc:sqlite: 到 HarmonyOS RDB/SQLite 的兼容映射；
• CSV、JSON、XML 数据解析与字段导入；
• PDF、HTML、XML、CSV、RTF 原生导出；
• HarmonyOS PC 窗口、键鼠、剪贴板和文件打开能力。

仍未完整适配的能力包括通用 JVM JDBC 驱动、完整 .jasper 编译与填充、XLSX/DOCX/PPTX 等 Office 格式真机导出，以及 JasperReports Server 资源浏览和发布。当前版本更准确的定位是“Jaspersoft Studio CE 的 HarmonyOS PC 原生报表设计预览版”：它已经能完成 JRXML 设计、字段导入和常用格式导出，但不等同于桌面 Eclipse RCP 版本的逐项复制。

八、总结

Jaspersoft Studio CE 的适配说明，传统桌面生产力软件迁移到 HarmonyOS PC 时，关键不只是把窗口显示出来，而是要重新识别平台能直接承载的能力、必须重建的界面层，以及受沙箱限制需要后续系统能力支持的部分。Eclipse RCP/SWT 和完整 JVM 报表引擎不能简单机械迁移，报表设计的核心流程却可以通过 Qt 原生重建先落地。

从真机结果看，当前版本已经形成连续工作流：启动报表设计器，创建元素，回写 JRXML，解析 CSV/JSON/XML 数据源，并在设备端生成 PDF、HTML、XML、CSV 和 RTF 文件。后续继续推进时，优先方向应放在更完整的数据源管理、JVM 编译服务化、Office 导出和 JasperReports Server 集成上。对于其他大型 Java 桌面工具，这次实践也提供了一条相对稳妥的路径：先保护原源码，再重建高频用户闭环，最后用真机截图和功能矩阵确认每一项能力是否真正可用。