一、写在前面

欢迎加入鸿蒙 PC 开发者社区，共同打造开发者工具生态：鸿蒙 PC 开发者社区：https://harmonypc.csdn.net/

项目开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_HiJson

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

环境搭建文章：https://blog.csdn.net/lbcyllqj/article/details/161286249?sharetype=blogdetail&sharerId=161286249&sharerefer=PC&sharesource=lbcyllqj&spm=1011.2480.3001.8118

这篇文章记录的是 HiJson 这个 Java Swing 桌面 JSON 工具适配 HarmonyOS PC 的过程。

HiJson 原本是一个 Java 桌面小工具，主要能力是把 JSON 字符串格式化后，用文本区、树形结构和 key/value 表格展示出来。它的定位很明确：开发者拿到一段 JSON 后，可以快速格式化、查看层级、定位字段、复制节点内容。

这类工具看起来不大，但适配时很有代表性。它不是 Electron 项目，也不是现代 Web 项目，而是一个较早期的 NetBeans + Ant + Java Swing 桌面程序。原始工程里大量 UI 逻辑写在 Swing 组件中，如果直接把 Swing 桌面能力搬到鸿蒙端，成本并不低。

所以这次没有选择“硬迁 Swing”，而是采用更快落地的路线：

先把 HiJson 的核心体验 Web 化，再用 HarmonyOS ArkWeb 包一层，形成可以构建 HAP 的鸿蒙 PC MVP。

最终适配完成后，项目新增了一个静态 Web MVP 和一个 HarmonyOS ArkWeb 工程。Web 侧负责 JSON 编辑、格式化、压缩、多标签、树形查看、节点表格和搜索；鸿蒙侧负责 HAP 工程承载、本地资源加载、文件打开/保存、剪贴板桥接。

在这里插入图片描述

二、原项目分析：一个典型 Java Swing 单体桌面工具

适配前先看原项目结构。HiJson 根目录比较简洁，是一个典型 NetBeans Java 桌面工程：

HiJson-master/
├── build.xml
├── manifest.mf
├── nbproject/
├── lib/
│   ├── gson.jar
│   ├── fastjson-1.1.28.jar
│   ├── rsyntaxtextarea.jar
│   ├── org-netbeans-swing-tabcontrol.jar
│   └── ...
├── src/
│   └── hi/chyl/json/
│       ├── MainApp.java
│       ├── MainView.java
│       ├── Kit.java
│       └── resources/
└── store/
    └── HiJson.jar

README 里对项目的描述是：

HiJson，一款json字符串格式化查看的桌面工具

项目要求也比较早：

NetBeans IDE 8
JDK 1.7 or higher

核心代码集中在：

src/hi/chyl/json/MainView.java
src/hi/chyl/json/MainApp.java
src/hi/chyl/json/Kit.java

其中 MainView.java 是适配分析的重点。它里面同时包含窗口、菜单、工具栏、标签页、文本编辑区、JSON 树、表格、格式化逻辑、右键菜单和节点操作。

主要依赖包括：

  • Gson：用于 JSON 格式化、解析和对象转换；
  • fastjson：用于部分 JSON 序列化能力；
  • RSyntaxTextArea：提供带语法体验的文本编辑区；
  • JTree：展示 JSON 层级树；
  • JTable：展示当前节点的 key/value 信息；
  • TabbedContainer：实现多标签编辑；
  • NetBeans Swing Application Framework：承载桌面应用窗口生命周期。

这说明原项目不是“纯算法 + 少量 UI”，而是 UI 和业务行为耦合在一个 Swing 视图类里。

在这里插入图片描述

三、适配路线判断：不直接迁 Swing，先 Web 化再 ArkWeb 包壳

HiJson 这种项目，理论上有三条适配路线。

第一条是继续保留 Java Swing，再想办法让桌面 Java 程序在目标环境运行。这条路对鸿蒙 PC MVP 不友好，因为 Swing/AWT 是传统桌面窗口体系，和 HarmonyOS ArkUI / ArkWeb 不是同一套 UI 运行模型。即使能保留一部分 Java 代码，窗口、菜单、文件选择器、剪贴板和渲染表现也都要重新处理。

第二条是用 ArkTS + ArkUI 完整重写。这个方案长期看更原生，但第一版工作量会比较大。JSON 树、可编辑文本区、多标签、快捷键、查找、表格这些都要在 ArkUI 里重新实现，而且 JSON 编辑器的体验也需要仔细打磨。

第三条是 Web 化 + ArkWeb 包一层。这次选择的是这个方案。

选择它的原因很直接：

  • HiJson 的核心数据处理是 JSON 解析、格式化、树展示，适合用浏览器能力快速实现；
  • Web 静态页面可以先在普通浏览器里调试，反馈速度快；
  • ArkWeb 可以直接加载 HAP 内置 rawfile 资源；
  • 文件打开、保存、剪贴板这类桌面能力可以通过 ArkTS 桥接补齐；
  • 首版可以快速形成 MVP，后续再决定是否替换更强的编辑器组件。

所以本次目标不是把每一行 Swing 代码逐字迁移，而是保留 HiJson 的产品体验：

  1. 输入或打开 JSON；
  2. 格式化和压缩 JSON；
  3. 用树查看 JSON 结构；
  4. 选中节点后显示 key/value；
  5. 支持多标签；
  6. 支持搜索；
  7. 支持保存和复制；
  8. 最终可以生成 HarmonyOS PC 可安装的 HAP。

四、第一步：新增静态 Web MVP

项目中新增了：

web-mvp/
├── index.html
├── styles.css
├── app.js
└── ARKWEB_MVP.md

这个 Web MVP 没有引入构建工具，所有代码都是静态资源。这样处理是为了降低第一版适配成本：不需要 Vite、Webpack、npm install，也不需要处理复杂的打包路径，直接复制到 HarmonyOS rawfile 目录后就可以由 ArkWeb 加载。

Web MVP 当前实现了以下能力：

  • JSON 格式化；
  • JSON 压缩；
  • 多标签编辑；
  • JSON 树展示；
  • 当前节点 key/value 表格；
  • 文本搜索；
  • 树节点搜索；
  • 打开本地 JSON/TXT 文件；
  • 保存 JSON 文件；
  • 复制全文、节点路径、节点值、节点 JSON；
  • 左右布局和上下布局切换；
  • 基础快捷键：Ctrl+N、Ctrl+W、Ctrl+O、Ctrl+S、Ctrl+F。

页面结构上尽量贴近 HiJson 原来的使用方式：左侧是文本输入区，中间是 JSON 树，右侧是节点详情表格。这样老用户迁移过来时，使用逻辑不会发生太大变化。

在这里插入图片描述

Web 版本还有一个关键设计：它先使用浏览器标准能力实现文件和剪贴板，再为 ArkWeb 原生桥预留入口。

浏览器里可以使用：

FileReader
Blob + a[download]
navigator.clipboard

而进入 HarmonyOS ArkWeb 后，如果这些能力受限，就优先调用：

window.HiJsonNative

Web 侧做了降级判断：

return window.HiJsonNative || window.HiJsonNativeBridge;

这样同一套页面可以同时满足两个场景：

  • 普通浏览器预览：方便快速调试 UI 和 JSON 逻辑；
  • 鸿蒙 ArkWeb 运行：通过 ArkTS 补齐系统能力。

五、第二步：新增 HarmonyOS ArkWeb 工程

Web MVP 稳定后，项目里新增了 HarmonyOS 工程：

ohos_hap/
├── AppScope/
│   └── app.json5
├── build-profile.json5
├── entry/
│   ├── build-profile.json5
│   ├── hvigorfile.ts
│   ├── oh-package.json5
│   └── src/main/
│       ├── ets/
│       │   ├── entryability/EntryAbility.ets
│       │   ├── pages/Index.ets
│       │   └── bridge/HiJsonNativeBridge.ets
│       ├── module.json5
│       └── resources/rawfile/hijson/
│           ├── index.html
│           ├── styles.css
│           └── app.js
└── README.md

这里选择的是 Stage 模型工程。ArkWeb 加载的资源放在：

entry/src/main/resources/rawfile/hijson/

对应入口地址是：

resource://rawfile/hijson/index.html

这一步的关键是把 Web MVP 作为 HAP 内置资源，而不是依赖远程地址。这样应用启动时不需要外网，也不会因为服务端路径变化导致页面不可用。

在这里插入图片描述

六、第三步：ArkWeb 页面壳

ArkTS 页面入口在：

ohos_hap/entry/src/main/ets/pages/Index.ets

核心加载逻辑如下：

const HIJSON_WEB_URL = 'resource://rawfile/hijson/index.html';

Web({ src: HIJSON_WEB_URL, controller: this.controller })
  .javaScriptAccess(true)
  .domStorageAccess(true)
  .databaseAccess(true)
  .fileAccess(true)
  .imageAccess(true)
  .cacheMode(CacheMode.Default)
  .width('100%')
  .height('100%')

这段代码做的事情很明确：创建一个全屏 ArkWeb，把 rawfile 中的 HiJson Web 页面加载进来。

为了方便调试，页面启动时打开了 Web 调试：

webview.WebviewController.setWebDebuggingAccess(true);

同时页面上加了一个简单的加载进度层。这样如果 rawfile 路径写错、页面加载失败，至少不会只看到空白界面，能够通过错误日志和加载状态快速判断问题。

在这里插入图片描述

这一步适配中最容易忽略的是资源路径。普通 Web 项目经常使用 /xxx.js、/assets/xxx.css 这种根路径资源，但 HAP 内本地资源加载更适合相对路径。HiJson Web MVP 本身就是静态三文件结构，所以这里没有复杂的路径改造，index.html 直接通过相对路径引用：

<link rel="stylesheet" href="styles.css">
<script src="app.js"></script>

这也是第一版不引入构建工具的好处：路径清晰，排查简单。

七、第四步：文件和剪贴板原生桥

只让页面打开还不够。HiJson 是开发者工具，文件打开、保存、复制、粘贴都是核心能力。

因此新增了 ArkTS 原生桥：

ohos_hap/entry/src/main/ets/bridge/HiJsonNativeBridge.ets

它向 Web 页面暴露的对象名是：

HiJsonNative

在 Index.ets 中通过 javaScriptProxy 注册：

.javaScriptProxy({
  object: this.bridge,
  name: 'HiJsonNative',
  methodList: [
    'readClipboard',
    'writeClipboard',
  ],
  asyncMethodList: [
    'openFile',
    'saveFile',
  ],
  controller: this.controller,
})

这里把同步和异步能力分开：

  • readClipboard()：读取剪贴板文本；
  • writeClipboard(text: string)：写入剪贴板文本；
  • openFile()：通过系统文档选择器打开 .json 或 .txt；
  • saveFile(name: string, text: string)：通过系统文档选择器保存 JSON。

桥接接口实际返回的是字符串形式的 JSON，方便 Web 侧解析：

{ "name": "example.json", "text": "{...}" }

保存时返回：

{ "ok": true, "uri": "file uri" }

Web 侧调用时先判断原生桥是否存在。如果在普通浏览器里运行，就回退到浏览器 API；如果在 ArkWeb 里运行，就走 HiJsonNative。

这种设计的好处是边界非常清楚：

  • Web 负责页面状态、JSON 解析、树展示；
  • ArkTS 负责系统文件选择器和剪贴板；
  • 两边通过少量字符串数据通信；
  • 后续要增强原生能力时，只需要继续扩展 bridge。

在这里插入图片描述

八、第五步：构建 HAP

适配完成后，可以直接使用 DevEco Studio 自带的 hvigorw 构建 HAP。

本机 SDK 路径是：

/Applications/DevEco-Studio.app/Contents/sdk

构建命令如下：

cd ~/XM/HiJson-master/ohos_hap

DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
HOS_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode module -p module=entry assembleHap --analyze=normal --parallel --incremental --daemon

构建输出目录：

ohos_hap/entry/build/default/outputs/default/

当前已经生成：

entry-default-unsigned.hap
entry-default-signed.hap

其中未签名包路径为：

~/XM/HiJson-master/ohos_hap/entry/build/default/outputs/default/entry-default-unsigned.hap

构建过程中可能会看到一些警告，例如签名配置、部分 API 废弃提示、文件 API 使用提示等。它们不影响这次 MVP 的 HAP 构建结果。后续如果要正式上架或真机长期验证，需要在 DevEco Studio 中补齐正式签名配置，并根据目标 SDK 版本清理 API 警告。

在这里插入图片描述

九、测试 JSON 和功能验证

为了验证 JSON 查看器能力，项目里新增了一个测试 JSON 文件：

test-data/hijson-test.json

这个文件用于覆盖常见 JSON 结构：

  • 基础字符串、数字、布尔值；
  • 对象嵌套；
  • 数组；
  • 多层 children；
  • 空对象或空数组；
  • URL、路径、中文文本等开发中常见字段。

验证时主要看几个点：

  1. 打开测试 JSON 后，文本区能正常展示内容；
  2. 点击格式化后，JSON 缩进正确；
  3. 点击压缩后，JSON 能恢复为单行结构；
  4. 树形区域能展示对象和数组层级；
  5. 点击树节点后，右侧表格能展示 key、type、value；
  6. 搜索字段时能定位到文本或树节点；
  7. 复制节点路径、节点值、节点 JSON 能正常写入剪贴板；
  8. 保存文件时能调用鸿蒙文档选择器。

在这里插入图片描述

对 HiJson 这种工具来说，验证重点不是页面有多复杂，而是“拿到一段 JSON 后能不能快速定位问题”。所以首版测试围绕格式化、树展示、搜索、复制和保存这些日常动作展开。

十、适配成果和当前边界

这次适配已经完成的内容包括：

  • 分析原 Java Swing 项目结构和核心功能；
  • 新增静态 Web MVP；
  • 实现 JSON 格式化、压缩、多标签、树展示、表格展示和搜索；
  • 新增 HarmonyOS ArkWeb 工程；
  • 将 Web MVP 放入 rawfile 并通过 resource://rawfile/hijson/index.html 加载；
  • 新增 ArkTS 原生桥 HiJsonNativeBridge.ets；
  • 支持文件打开、保存、剪贴板读写；
  • 生成 HarmonyOS HAP；
  • 新增测试 JSON 文件用于功能验证。

当前边界也比较清楚：

  • Web MVP 还没有引入 CodeMirror 这类专业编辑器，文本编辑能力是第一版够用状态；
  • 超大 JSON 的树渲染还没有做虚拟滚动，后续可以优化性能；
  • 文件编码当前按 UTF-8 处理，GBK 等编码兼容可以后续补；
  • 当前重点是 MVP 和 HAP 构建，正式发布前还需要完善签名、图标、权限说明和更多真机测试；
  • 原 Java Swing 的所有菜单细节没有逐一复刻，优先保留核心 JSON 查看体验。

这也是 Web 化 MVP 路线的特点：先把核心工具能力跑通，再逐步增强体验。

十一、这次适配的几个经验

第一，老 Java Swing 工具不一定适合直接迁 UI。很多早期桌面工具的业务和界面都写在一个 View 类里，直接迁移会变成大规模重写。与其纠结 Swing 组件怎么搬，不如先拆出产品核心动作。

第二，开发者工具适配时要优先保证“可用闭环”。HiJson 的闭环不是页面打开，而是输入 JSON、格式化、查看树、搜索字段、复制结果、保存文件。只要这条链路稳定，MVP 就有实际价值。

第三，ArkWeb 包静态页面时，资源路径越简单越好。首版没有使用构建工具，反而减少了 /assets、hash 文件名、base path 等问题。

第四，文件和剪贴板不要硬塞在 Web 里。浏览器预览时用 Web API，鸿蒙运行时用 ArkTS bridge，这样开发和适配都更舒服。

第五，桥接接口要小。HiJsonNativeBridge 只做打开、保存、读剪贴板、写剪贴板四件事，Web 侧和 ArkTS 侧边界清晰，后续维护成本低。

十二、总结

HiJson 这次适配走的是一条比较适合老桌面工具的路线：

Java Swing 原项目分析
        ↓
抽取核心 JSON 查看体验
        ↓
实现静态 Web MVP
        ↓
ArkWeb 加载 rawfile 本地资源
        ↓
ArkTS bridge 补齐文件和剪贴板
        ↓
构建 HarmonyOS PC HAP

它没有追求一步到位复刻所有 Swing 细节，而是先把最重要的 JSON 工具链路做成鸿蒙 PC 上可运行、可构建、可继续迭代的版本。

对于类似 HiJson 这种小而实用的开发者工具，Web 化 + ArkWeb 包壳 是一个非常适合首版 MVP 的方案。它能快速验证产品体验，也能为后续 ArkUI 原生化、编辑器增强、性能优化和正式发布留下清晰空间。

到这里，HiJson 从一个 NetBeans Java Swing 桌面小工具，已经完成了到 HarmonyOS PC ArkWeb HAP 的第一版适配。

# harmonyos # java # json
Logo
HarmonyOS开发者社区

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

更多推荐

cover

鸿蒙PC适配：Pinta GTK 图像编辑器鸿蒙 PC ArkWeb 适配全记录：从 .NET_GTK4 桌面到 HarmonyOS PC HAP

avatar HarmonyOS开发者社区
cover

鸿蒙新手原生应用实战（三）ArkUI：从零开发一个 GIF 动图制作器 App

avatar HarmonyOS开发者社区

定时器与任务调度：setTimeout与setInterval的正确使用（19）

在 HarmonyOS 开发中，setTimeout和是处理延迟操作和周期性任务的核心 API。它们分别适用于单次延迟和重复执行场景，但在实际使用中，必须严格遵循生命周期管理和防内存泄漏的最佳实践。

avatar HarmonyOS开发者社区