鸿蒙PC：Qt适配OpenHarmony实战【书栖】：图书列表、阅读进度和简介卡片的组合实现

前言

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

项目开源地址：https://atomgit.com/lqjmac/qtsx

我更愿意把这类 Demo 当成工程切片来看：功能要小，链路要完整，运行结果要能验证。
本文记录第 19 个 Qt 适配鸿蒙小项目：书栖。
它的定位是电子书架，核心功能是图书列表、图书简介页面。
书架应用适合练“列表选中后详情联动”，还可以顺便处理进度条和剩余页数。
书栖 的工程价值不是功能复杂，而是把 Qt Quick、OpenHarmony HAP、QML 资源和窗口刷新串成一条可复现路径。

提示：本文按真实工程路径和真实 Bundle Name 编写，命令可以直接对照项目目录执行。

推荐阅读顺序：

1. 确认项目目录、中文展示名和 Bundle Name。
2. 检查 Qt SDK 相对路径，避免构建机路径绑定。
3. 运行构建、安装、启动和日志过滤命令。

本文包含的重点元素：

• 项目截图
• 配置表格
• 构建命令
• QML 片段
• 常见问题表

一、为什么这个 Demo 值得单独写

1.1 项目解决什么问题

书栖不是为了把 电子书架 做到复杂，而是为了验证 Qt Quick 在鸿蒙桌面窗口里的完整链路。
这个链路包含资源配置、Native CMake、QML 首屏、双入口导出、窗口自适应、HAP 构建和设备启动。

主要功能如下：

• 展示书架图书列表
• 点击图书切换详情
• 展示书名作者分类简介
• 展示阅读进度和剩余页数
• 继续阅读状态 UI

1.2 最终运行截图

图 1：书栖 在 OpenHarmony 桌面环境里的运行效果。

1.3 关注点速览

二、项目清单先对齐

2.1 信息总览

这张表建议和 README 中的信息保持一致。项目多了以后，最怕的是展示名、包名和目录名互相错位。

2.2 目录结构

qt_for_harmony/ ├── qtforharmony/ ├── QtBookShelfDemo/ │ ├── AppScope/ │ ├── entry/ │ │ ├── build-profile.json5 │ │ └── src/main/cpp/ │ │ ├── CMakeLists.txt │ │ ├── main.cpp │ │ ├── main.qml │ │ └── qml.qrc │ └── README.md └── qt-docs/

这里有一个朴素但重要的规则：Qt SDK 放在项目同级目录，不塞进每个 Demo 里面。

2.3 模块职责

三、从 UI 布局开始拆

3.1 build-profile.json5

项目需要使用相对路径指定 Qt SDK。当前工程使用的关键片段如下：

{ "externalNativeOptions": { "path": "./src/main/cpp/CMakeLists.txt", "arguments": "-DQT_PREFIX=../qtforharmony", "cppFlags": "", "abiFilters": ["arm64-v8a"] } }

关键规则：项目需要"arguments": "-DQT_PREFIX=../qtforharmony"，SDK 文件请到文末保留的 SDK 仓库自取，并放到项目同级目录qtforharmony中。

3.2 CMakeLists.txt

cmake_minimum_required(VERSION 3.5.0) project(shuqi_bookshelf) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) get_filename_component(PROJECT_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../.." ABSOLUTE) if (NOT IS_ABSOLUTE "${QT_PREFIX}") get_filename_component(QT_PREFIX "${PROJECT_ROOT}/${QT_PREFIX}" ABSOLUTE) endif() list(PREPEND CMAKE_PREFIX_PATH ${QT_PREFIX}) find_package(Qt5 REQUIRED COMPONENTS Core Gui Qml Quick QuickControls2) add_library(entry SHARED main.cpp qml.qrc)

这段配置先把相对的QT_PREFIX转成绝对路径，再交给 CMake 查找 Qt。

3.3 qml.qrc

<RCC><qresourceprefix="/"><file>main.qml</file></qresource></RCC>

把 QML 打进 Qt 资源系统后，运行时可以统一通过qrc:/main.qml加载。

四、数据模型放在哪里

4.1 首屏布局

书籍列表放一侧，详情卡片放主区域，阅读进度作为视觉锚点。
这种布局不是为了炫技，而是为了让 Demo 的功能一眼就能被看懂。

4.2 根节点尺寸策略

Rectangle { id: root width: 960 height: 1080 color: "#F5F6FA" property real margin: Math.max(20, Math.min(48, width * 0.042)) property real gap: Math.max(12, Math.min(24, width * 0.022)) property real titleSize: Math.max(34, Math.min(58, width * 0.054)) }

根节点给出默认尺寸，真正运行时由QQuickView::SizeRootObjectToView接管。

4.3 本项目的数据模型

ListModel { id: demoModel ListElement { name: "示例项一"; state: "ready" } ListElement { name: "示例项二"; state: "active" } ListElement { name: "示例项三"; state: "done" } }

实际工程中，书栖 使用的是bookModel。这些数据都在 QML 内部，适合单机演示。

五、Qt for Harmony 的启动细节

5.1 函数职责表

这些函数没有故意抽得很复杂。Demo 项目最重要的是让读者能从 QML 文件里直接看懂状态从哪里来、又流向哪里。

5.2 典型交互片段

MouseArea { anchors.fill: parent onClicked: { // 点击后修改模型状态，界面绑定会自动刷新 demoModel.setProperty(index, "state", "done") } }

点击事件只负责改变状态，展示层通过绑定更新，这比手动到处刷新文本更稳。

5.3 业务函数示意

function demoFlow(row) { var current = row var before = demoModel.count demoModel.setProperty(row, "state", "done") return before }

这段不是要照搬，而是说明当前项目的函数组织方式：

• 先从模型拿当前数据
• 再执行用户动作
• 最后让绑定表达式刷新界面

六、把 HAP 构建出来

6.1 保留双入口

extern"C"voidqtmain(){staticResponsiveQuickView*view=nullptr;if(view!=nullptr){return;}configureSurfaceFormat();view=newResponsiveQuickView();loadQml(view);}intmain(intargc,char*argv[]){configureSurfaceFormat();QGuiApplicationapp(argc,argv);ResponsiveQuickView view;if(!loadQml(&view)){return-1;}returnapp.exec();}

之前遇到过只导出qtmain时运行时报Symbol not found: main的情况，所以这一批 Qt Demo 都统一保留两个入口。

6.2 标题和 QML 加载

boolloadQml(ResponsiveQuickView*view){view->setTitle(QStringLiteral("书栖"));view->setSource(QUrl(QStringLiteral("qrc:/main.qml")));if(view->status()==QQuickView::Error){qWarning()<<"Failed to load qrc:/main.qml";returnfalse;}view->showResponsive();returntrue;}

这里标题要和应用展示名保持一致。运行时如果日志出现 QML 加载失败，优先检查qml.qrc。

七、安装启动与截图

7.1 构建 HAP

cdQtBookShelfDemo /Users/luqingjiedemac/ohos/command-line-tools/bin/hvigorw assembleHap--stacktrace

构建完成后，HAP 默认输出在下面这个路径：

entry/build/default/outputs/default/entry-default-unsigned.hap

7.2 安装和启动

hdcinstall-rentry/build/default/outputs/default/entry-default-unsigned.hap hdc shell aa start-aEntryAbility-bcom.nutpi.shuqi-mentry

启动命令里的 Bundle Name 必须和AppScope/app.json5一致。

7.3 构建失败先看哪里

1. QT_PREFIX是否指向同级qtforharmony。
2. CMakeLists.txt的 project 名称是否已经替换。
3. main.qml是否存在于qml.qrc中。

八、排错记录

8.1 过滤关键日志

hdc shell hilog-x-z500|rg-n"QtForOpenHarmony|QPAForOpenHarmony|shuqi|Failed|failed|Error|error|qrc|main function|Symbol not found|QML|ReferenceError|TypeError"

我重点看这些信号：

• 是否出现Symbol not found: main
• 是否出现Failed to load qrc:/main.qml
• 是否出现 QML 的ReferenceError或TypeError
• 是否能看到应用进程还在运行

8.2 截图命令

hdc shell snapshot_display-f/data/local/tmp/shuqi_screen.jpeg hdcfilerecv /data/local/tmp/shuqi_screen.jpeg ./qt-docs/assets/shuqi-screen.jpeg

截图不是装饰，它是确认首屏真的渲染出来的证据。

8.3 当前项目验证点

1. 切换图书后详情变化
2. 剩余页数计算正确
3. 进度条宽度稳定

注意：文章里提到的业务数据都是 QML 内置示例数据，不代表已经接入系统能力或外部服务。

九、改造成产品前的检查

9.1 常见问题表

9.2 排查顺序

1. 先看 HAP 是否重新构建。
2. 再看安装的包名是不是当前项目。
3. 然后看日志里有没有 QML 或 main 符号错误。
4. 最后才去调整具体控件布局。

十、还能继续加什么

10.1 可以继续做的功能

• 增加章节列表
• 保存阅读进度
• 接入本地书籍封面

这些扩展不建议一口气全做。Qt 适配鸿蒙的早期样例，优先目标应该是结构稳定、运行稳定、验证路径稳定。

10.2 工程增强方向

QtObject { id: appState property int currentIndex: 0 property bool dirty: false property string message: "ready" }

当页面状态继续变多，可以把零散属性收进一个QtObject，这样顶层不会越来越乱。

10.3 清理和重建

rm-rfentry/build entry/.cxx .hvigor /Users/luqingjiedemac/ohos/command-line-tools/bin/hvigorw assembleHap--stacktrace

遇到缓存比较顽固的问题时，可以清掉构建产物后重建。正常开发时不需要每次都清理。

十一、资料保留

11.1 OpenHarmony 文档入口

OpenHarmony 文档中心：https://docs.openharmony.cn/

11.2 Qt for Harmony SDK 仓库

Qt for Harmony SDK 仓库：https://atomgit.com/nutpi/qtforharmony_sdk

11.3 为什么只保留三个链接

这批文章用于项目发布和读者复现。链接过多会分散注意力，所以正文只保留社区入口、OpenHarmony 文档和 Qt SDK 仓库三个入口。

总结

书栖 这个 Demo 的重点是图书列表、图书简介页面。
从工程角度看，它已经覆盖了 Qt for OpenHarmony 项目里最关键的几步：配置 Qt SDK、打包 QML、保留双入口、构建 HAP、安装启动和截图验证。
如果你也在做 Qt 适配鸿蒙，可以先用这种小项目把链路跑稳，再逐步接入更真实的数据和业务。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！