一、为什么要适配 Geany

Geany 是一款以轻量、启动快和依赖克制著称的桌面代码编辑器。它没有把所有能力都压进一个庞大的语言服务体系，而是围绕多标签编辑、项目浏览、符号导航、构建命令和消息面板组织工作流。对维护脚本、阅读中小型 C/C++ 工程、修改配置文件，或者需要快速进入代码现场的开发者来说，这种“打开即可工作”的体验一直很有价值。

HarmonyOS PC 的生产力生态需要大型 IDE，也需要一款占用可控、可以随手处理源码与工程文件的工具。选择 Geany 进行适配，并不只是把一个传统 Linux 窗口搬到新平台，更重要的是验证几组具有代表性的迁移问题：GTK 应用如何进入 Stage 模型；桌面端可以随意访问文件、启动工具和加载插件的假设，进入应用沙箱后应当怎样收敛；项目搜索、符号、任务和命令输出又怎样在没有完整桌面环境的情况下形成闭环。

本次适配保留仓库根目录中的 Geany 上游源码与原有 Meson、Autotools 构建入口，鸿蒙实现独立放在 harmony_pc/ 下。当前应用版本为 1.0.0，Native 侧标识为 2.0-ohos-qt，包名为 org.geany.openharmony，支持 2in1 与 tablet，目标 ABI 为 arm64-v8a。

二、先划清迁移边界：不是把 GTK 工程换个编译器

Geany 上游并不是一个只依赖标准 C 库的编辑器。主界面基于 GTK，编辑能力围绕 Scintilla 演进，符号系统、文件类型、构建配置、VTE 终端和二进制插件又共同构成桌面生态。即使解决头文件和链接错误，也无法让 GTK 窗口、GModule 插件 ABI、VTE/PTTY 以及 Linux 桌面文件访问语义自然出现在 HarmonyOS PC 上。

因此，本项目采用“保留上游、重建高频闭环”的路线：

层次	上游 Geany	鸿蒙侧实现
应用入口	GTK 主循环与桌面进程	Stage 模型 EntryAbility
窗口承载	GTK 窗口体系	ArkTS XComponent + Qt for OpenHarmony QPA
编辑器	Scintilla	QPlainTextEdit 扩展、行号区与语法高亮器
工程导航	文档、符号与插件协作	项目索引、搜索、符号、任务、书签内建实现
构建与终端	外部命令、VTE/PTTY	逐条命令执行器、输出捕获和诊断解析
插件体系	GTK/GModule 二进制插件	原生替代功能与 External Tools 扩展路径
文件访问	桌面路径与文件对话框	沙箱可读路径、应用内选择器和外部 URI 缓存

这个边界避免了两个容易混淆的结论。第一，当前版本并不是原版 GTK 二进制的重新打包；第二，它也不是只有一张编辑器界面的演示壳。项目、搜索、符号、任务、构建命令、诊断跳转、导出和会话恢复都在鸿蒙版本中形成了真实的数据流，只是没有把平台不具备的插件 ABI 和完整交互式终端包装成“已经兼容”。

三、鸿蒙版本的整体架构

鸿蒙工程采用 ArkTS 宿主与 Native Qt 界面分层。EntryAbility.ets 管理窗口、权限、启动参数和外部文件 URI；Index.ets 创建全屏 XComponent；Qt for OpenHarmony 的 QPA 插件接管绘制，并启动 libentry.so 中的 Geany 主窗口。

EntryAbility
    ├── 窗口尺寸、文件权限、Want/URI 处理
    └── Index.ets / XComponent
          └── qopenharmony QPA 插件
                └── libentry.so
                      ├── Qt Widgets 主窗口与多标签编辑器
                      ├── 项目文件索引、Browse 与 Files 面板
                      ├── 搜索、符号、引用、任务与书签
                      ├── 构建命令、Problems 与 Terminal 面板
                      └── QSettings 会话和偏好持久化

主要目录如下：

ohos_geany/
├── src/、scintilla/、plugins/、data/       # 上游 Geany 源码与资源
├── meson.build / configure.ac             # 上游桌面构建入口
├── README.OpenHarmony_CN.md               # 鸿蒙适配说明
└── harmony_pc/
    ├── AppScope/app.json5                 # 包名、版本、图标
    ├── build-profile.json5                # SDK、签名和产品配置
    ├── qtforharmony_sdk/                  # Qt for OpenHarmony SDK
    └── entry/src/main/
        ├── ets/                           # Ability 与 XComponent 宿主
        ├── module.json5                   # 模块、设备与权限声明
        └── cpp/
            ├── CMakeLists.txt             # Native 构建入口
            └── geany_qt_harmony.cpp       # 编辑器和主要业务实现

ArkTS 层保持轻量，文档、项目、搜索结果和命令状态都集中在 Native 侧，避免两套 UI 状态来回同步。CMake 只链接 Qt Core、Gui、Widgets、PrintSupport、OhExtras 以及必要的 QPA、样式和图片插件，最终生成 AArch64 的 libentry.so。

四、把轻量 IDE 的核心工作流在真机上跑通

以下五张图片均来自本项目签名 HAP 在 HarmonyOS PC 真机上的实际运行画面，并非桌面端截图或预留占位图。测试设备为 HUAWEI MateBook Pro（HAD-W32，2in1），系统版本为 OpenHarmony-6.1.0.115，物理分辨率为 3120×2080。本次验证重新安装了仓库当前的 arm64-v8a 签名产物，再在应用沙箱内完成项目打开、任务扫描、符号导航、引用检索和命令执行。

1. 从项目文件到编辑上下文

打开项目后，左侧 Files 面板列出已建立索引的源码和生成文件，中间编辑区显示 C++ 源码。编辑器提供多标签、行号、当前行高亮、关键字与注释着色、缩进、括号配对、修改状态和光标位置等常用能力；状态栏同步显示文件类型、换行符、编码和读写状态。

鸿蒙版本的编辑器基于 QPlainTextEdit 扩展，而不是勉强嵌入上游 GTK 控件。CodeEditor 单独绘制行号和书签标记，MiniHighlighter 根据文件类型装载高亮规则。文件写入使用 QSaveFile 的原子提交路径；编码层识别 UTF-8、带 BOM 的 UTF-16LE/BE、GB18030 与系统 locale，换行符则在 LF、CRLF、CR 之间检测和转换，避免中文源码或 Windows 工程在保存后出现不可逆变化。

2. TODO 不是文本装饰，而是项目任务入口

在 Project 菜单执行 Scan Tasks 后，应用遍历项目与已打开文档，提取 TODO、FIXME、XXX、HACK 和 NOTE，并把文件、行号和摘要写入 Tasks 面板。此次真机扫描得到 4 条任务，覆盖 7 个可扫描文件。

任务扫描会跳过 .git、.hvigor、build、oh_modules、node_modules、target 和 qtforharmony_sdk 等依赖或产物目录，同时遵守项目根目录中的常用忽略规则以及 .geany 文件保存的附加模式。结果项保存真实路径与行号，激活条目即可打开对应文件并定位，而不是把扫描结果做成脱离编辑器的静态列表。

3. 用轻量符号模型补上快速导航

Go to Symbol 会汇总当前项目和已加载 tags 文件中的符号。截图中的 Strict80Runner 被识别为 C++ 类，并标出 main.cpp:3；确认后会回到源码定义位置。

符号提取覆盖 C/C++、Python、JavaScript/TypeScript、ArkTS、Java、Go、Rust、PHP 和宏定义等常见场景，并针对 ArkTS 的组件结构、接口、类型别名和生命周期方法补充规则。它不等同于 clangd 一类完整语义引擎，却不需要在沙箱中维护常驻语言服务进程，适合快速浏览和中小型项目导航。对复杂宏、模板实例化和跨编译单元类型推导，当前版本仍明确按轻量能力处理。

4. 引用检索必须和代码定位使用同一套坐标

选中 Strict80Runner 后执行 Find References，应用在 7 个项目文件中找到 6 处匹配。Search 面板显示相对文件、行列位置和上下文，中间编辑器同步高亮当前文档中的定义与引用。

项目搜索会先排除过大的文件和具有二进制特征的内容，再对文本执行大小写、全词或正则匹配。搜索结果、任务、书签、问题列表和符号跳转共用统一的“路径—行—列”模型，因此双击结果能够稳定回到源码。Find in Files、Replace in Files、定义查找和引用查找也复用项目扫描范围，减少不同功能对“项目里有哪些文件”的理解不一致。

5. 用可控命令执行器承接构建与工具链

原版 VTE/PTTY 没有直接迁入，底部 Terminal 改为逐条执行 Harmony Shell 命令。此次真机依次执行了 pwd、ls . 和 cat main.cpp；截图展示 cat main.cpp 的实际回显，命令读取的是当前项目工作目录中的真实文件。

Terminal 维护工作目录和命令历史，内建处理 cd 与 clear，其余命令通过任务进程执行并捕获 stdout、stderr 与退出状态。Build、Compile、Clean、Execute 和 External Tools 共享同一套占位符展开机制，支持 {file}、{dir}、{project}、{name}、{base}、{output} 与 {target}。输出中的 GCC/Clang、hvigor/ArkTS、Python、Rust、CMake 等常见诊断会进入 Problems 面板，保留文件、行列和错误级别，便于继续跳转处理。

五、适配过程中最棘手的几个问题

难点一：GTK、Scintilla 与插件生态不能机械替换

上游 Geany 的窗口、编辑器通知、文件类型、构建配置和插件扩展长期围绕 GTK 与 Scintilla 协作。只把控件名称逐一替换为 Qt，最终仍会留下大量事件模型、对象生命周期和插件 ABI 的断点。本项目先按用户工作流重组界面，再把文档、项目、搜索、符号、任务、命令和偏好做成 Native 内建模块。代价是原版 GTK 二进制插件不能直接加载，收益则是依赖范围清晰，HAP 中的运行时组件可以被完整审计。

难点二：Qt 已经加载，不代表画面已经挂到窗口

ArkTS 创建 XComponent 后，QPA 桥接仍需要从 Ability 取得正确的 LocalStorage 和顶层窗口对象。早期版本曾出现日志显示 Qt 已启动，但真机只停留在白屏的情况，原因是宿主没有提供桥接层需要的 newLocalStorage()。补齐 Ability 接口，并严格调整 loadContent、handleJsTopWindowCreated 与 startQtApplication 的调用顺序后，Qt 窗口才稳定附着到鸿蒙页面。此类问题无法通过 Native 编译成功来判断，只能结合 hilog 和真机窗口状态排查。

难点三：桌面文件路径进入沙箱后不再理所当然

传统编辑器默认任意绝对路径都可读写，HarmonyOS 应用则需要区分应用沙箱、公共目录和经授权的外部 URI。适配层为文件、目录、保存、项目、session、tags、搜索和导出提供应用内路径选择器；外部 file://、content:// 请求先尝试缓存到应用可读位置，再交给 Native 编辑器。保存时还要验证目标目录是否真实可写，不能只依据“目录创建成功”推断后续文件写入一定可用。

难点四：编辑器的数据正确性比界面相似更重要

代码编辑器如果把 GB18030 当成 UTF-8、把 CRLF 全部改成 LF，或者保存时破坏 BOM，即使界面很像 Geany，也不具备真实使用价值。本次适配把编码、换行、最终换行、尾随空格、备份副本和外部文件变更检查纳入文档模型。对 UTF-16 和 GB18030 采用显式编码路径，对项目与全局默认值分层保存，状态栏则持续显示当前文档的真实状态。

难点五：终端能力必须服从平台边界

完整 VTE/PTTY 涉及伪终端、交互式控制序列、子进程会话和桌面权限模型，不能用一个文本框假装已经等价迁移。当前版本明确定位为“逐条命令执行器”：它适合构建、检查、格式化、文件查看和外部工具，不承诺 vim、top、交互式 REPL 等依赖 PTY 的程序可以正常工作。与此同时，退出码、标准输出、标准错误、停止任务和诊断跳转都必须可靠，这些才是编辑器日常调用工具链时最关键的部分。

难点六：PC 应用的会话不能只等关闭事件再保存

移动或桌面融合系统可能直接回收应用，传统窗口的关闭事件不一定总能成为唯一落盘点。鸿蒙版用 QSettings 保存打开文件、活动标签、光标位置、书签、项目根目录、构建命令、最近文件、面板布局和编辑器偏好；项目文件与 .geany-session 也能单独保存这些上下文。状态发生关键变化时及时同步，关闭事件只负责最后一次补充，才能保证重新进入应用后恢复到可工作的现场。

六、构建、安装与启动

首次构建建议使用 DevEco Studio 打开仓库中的 harmony_pc/。工程当前配置的 compatible SDK 与 target SDK 均为 5.0.5(17)，Native 编译器为 BiSheng，ABI 只启用 arm64-v8a。Qt SDK 位于项目内的 harmony_pc/qtforharmony_sdk/，CMake 通过 -DQT_PREFIX=qtforharmony_sdk 引用。

命令行构建示例如下：

cd harmony_pc

/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode module -p module=entry assembleHap --no-daemon

签名产物位于：

harmony_pc/entry/build/default/outputs/default/entry-default-signed.hap

本次真机验证的 HAP 约 26 MB。安装和启动命令如下：

HDC=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc

"$HDC" list targets
"$HDC" install -r entry/build/default/outputs/default/entry-default-signed.hap
"$HDC" shell aa start -a EntryAbility -b org.geany.openharmony

若更换开发机、证书或包名，应在 DevEco Studio 中重新配置与目标设备匹配的签名材料。仓库中的本机签名路径不应被当成可移植配置。

七、当前已经覆盖的能力与明确边界

当前版本已覆盖轻量 IDE 的主要工作流：

• 多标签编辑、行号、语法高亮、缩进、配对、注释、折叠、书签与常用行操作；
• UTF-8、UTF-16LE/BE、GB18030 编码识别与保存，以及 LF、CRLF、CR 检测转换；
• 文件打开、保存、另存、保存副本、自动保存、外部变更检测和最近关闭文档；
• 文件夹项目、.geany 项目文件、项目过滤、忽略规则、最近项目和会话恢复；
• 文档与项目搜索替换、符号、定义、引用、TODO/FIXME 任务和导航历史；
• 构建、编译、清理、执行、停止、命令历史、Terminal 与 External Tools；
• 构建诊断解析、Problems 跳转、HTML/PDF 导出、打印预览和打印到 PDF；
• Snippets、文件模板、tags、Browse、Split View、Scribble 和常用插件工作流替代。

当前没有按原样迁移的部分同样需要写清楚：

• 原版 GTK/GModule 二进制插件 ABI 与完整第三方插件生态；
• 原版 VTE/PTTY 交互式终端；
• 上游全部 Scintilla/Lexilla 语言细节和复杂编辑扩展；
• clangd 等完整语言服务器所提供的编译数据库语义、模板推导和精确重构；
• 未经系统授权的任意外部路径直读写。

因此，这一版本更准确的定位是“Geany HarmonyOS PC 轻量开发版”。它保住了快速编辑、项目阅读、检索导航和调用工具链这些核心价值，但没有把与 GTK 桌面生态强绑定的能力硬说成已经 1:1 兼容。

八、真机自检与结果口径

除本文展示的五条交互链路外，项目还提供了迁移自检流程，对沙箱保存、文件打开、项目索引、HTML/PDF 导出、文档与项目符号、项目搜索替换、项目文件、书签、Session、任务、引用、构建诊断、文件浏览、Tags、Snippets、模板、偏好、命令历史、Terminal 内建命令和 Split View 等能力逐项检查。

当前仓库随附的真机报告结果为：

38 pass, 3 degraded, 0 fail

其中 3 项 degraded 分别是 GTK 二进制插件 ABI、完整 VTE/PTTY 终端和任意外部 file:// 路径。这三项不是运行失败后被忽略，而是平台架构差异下主动保留的边界。将“已经验证的能力”和“明确降级的能力”分开记录，比用一个笼统的适配百分比更有助于后续维护。

九、总结

Geany 的鸿蒙 PC 适配表明，轻量桌面编辑器的迁移难点并不轻。GTK 窗口、Scintilla 通知、插件 ABI、VTE 终端、任意文件路径和关闭时保存会话，都是传统桌面环境中容易被默认的前提；进入 HarmonyOS PC 后，每一项都需要重新确认平台契约。

本项目用 Stage 模型和 XComponent 接住应用生命周期，以 Qt for OpenHarmony 重建 Geany 风格的桌面界面，再把项目索引、搜索、符号、任务、构建诊断和命令执行收敛到 Native 侧。五张真机截图覆盖了从项目打开到编辑、从任务与符号到引用检索，再到终端读取真实文件的连续流程，说明当前版本已经越过“能启动、能显示”的阶段。

对其他传统代码工具而言，这次实践提供了一条可复用的迁移顺序：先保留最有价值的用户闭环，再处理窗口和文件边界；随后把外部插件与终端能力拆分为平台可承载的内建模块和扩展接口，最后通过真机上的路径、编码、输出、退出状态与会话恢复验证结果。只有这些细节都能连续工作，适配才真正具备使用价值。

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

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

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_geany

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