前言欢迎加入鸿蒙PC开发者社区共同打造开发者工具生态鸿蒙PC开发者社区 https://harmonypc.csdn.net/项目开源地址https://atomgit.com/lqjmac/qtsyrj我更愿意把这类 Demo 当成工程切片来看功能要小链路要完整运行结果要能验证。本文记录第 11 个 Qt 适配鸿蒙小项目水印日记。它的定位是喝水记录核心功能是记录今日喝水次数。喝水记录不需要复杂后台先把“次数、毫升数、目标进度、时间段状态”做稳。水印日记 的工程价值不是功能复杂而是把 Qt Quick、OpenHarmony HAP、QML 资源和窗口刷新串成一条可复现路径。提示本文按真实工程路径和真实 Bundle Name 编写命令可以直接对照项目目录执行。推荐阅读顺序确认项目目录、中文展示名和 Bundle Name。检查 Qt SDK 相对路径避免构建机路径绑定。运行构建、安装、启动和日志过滤命令。本文包含的重点元素项目截图配置表格构建命令QML 片段常见问题表一、为什么这个 Demo 值得单独写1.1 项目解决什么问题水印日记不是为了把 喝水记录 做到复杂而是为了验证 Qt Quick 在鸿蒙桌面窗口里的完整链路。这个链路包含资源配置、Native CMake、QML 首屏、双入口导出、窗口自适应、HAP 构建和设备启动。主要功能如下记录今日喝水次数点击按钮增加一杯水展示目标进度和总饮水量支持减少误点记录按时间段展示喝水状态1.2 最终运行截图图 1水印日记 在 OpenHarmony 桌面环境里的运行效果。1.3 关注点速览关注点为什么重要在本项目中的体现应用标识避免 25 个 Demo 安装冲突com.nutpi.shuiyinrijiQML 状态决定界面是否能即时反馈用 drinkCount 推导总毫升数和进度百分比减少重复状态构建参数决定换机器后能否继续构建-DQT_PREFIX../qtforharmony启动入口避免白屏和符号缺失同时保留main和qtmain二、项目清单先对齐2.1 信息总览项目内容应用展示名水印日记项目目录名QtWaterReminderDemoBundle Namecom.nutpi.shuiyinrijiCMake projectshuiyinriji_water项目类型喝水记录核心功能记录今日喝水次数这张表建议和 README 中的信息保持一致。项目多了以后最怕的是展示名、包名和目录名互相错位。2.2 目录结构qt_for_harmony/ ├── qtforharmony/ ├── QtWaterReminderDemo/ │ ├── 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 模块职责模块作用检查点AppScope应用包名和展示名com.nutpi.shuiyinriji是否唯一entry/build-profile.json5native 构建参数Qt SDK 相对路径entry/src/main/cppC 入口和 QMLmain.qml是否进入 qrcREADME.md项目说明构建和启动命令是否完整三、从 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../qtforharmonySDK 文件请到文末保留的 SDK 仓库自取并放到项目同级目录qtforharmony中。3.2 CMakeLists.txtcmake_minimum_required(VERSION 3.5.0) project(shuiyinriji_water) 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.qrcRCCqresourceprefix/filemain.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 } }实际工程中水印日记 使用的是periodModel / tipModel。这些数据都在 QML 内部适合单机演示。五、Qt for Harmony 的启动细节5.1 函数职责表函数职责addCup()处理用户操作removeCup()处理用户操作progressRatio()计算界面统计值periodStatus(index)封装业务逻辑totalMl()封装业务逻辑这些函数没有故意抽得很复杂。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 保留双入口externCvoidqtmain(){staticResponsiveQuickView*viewnullptr;if(view!nullptr){return;}configureSurfaceFormat();viewnewResponsiveQuickView();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 构建 HAPcdQtWaterReminderDemo /Users/luqingjiedemac/ohos/command-line-tools/bin/hvigorw assembleHap--stacktrace构建完成后HAP 默认输出在下面这个路径entry/build/default/outputs/default/entry-default-unsigned.hap7.2 安装和启动hdcinstall-rentry/build/default/outputs/default/entry-default-unsigned.hap hdc shell aa start-aEntryAbility-bcom.nutpi.shuiyinriji-mentry启动命令里的 Bundle Name 必须和AppScope/app.json5一致。7.3 构建失败先看哪里QT_PREFIX是否指向同级qtforharmony。CMakeLists.txt的 project 名称是否已经替换。main.qml是否存在于qml.qrc中。八、排错记录8.1 过滤关键日志hdc shell hilog-x-z500|rg-nQtForOpenHarmony|QPAForOpenHarmony|shuiyinriji|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/shuiyinriji_screen.jpeg hdcfilerecv /data/local/tmp/shuiyinriji_screen.jpeg ./qt-docs/assets/shuiyinriji-screen.jpeg截图不是装饰它是确认首屏真的渲染出来的证据。8.3 当前项目验证点增加一杯后进度变化减少记录不会出现负数时间段状态能随次数变化注意文章里提到的业务数据都是 QML 内置示例数据不代表已经接入系统能力或外部服务。九、改造成产品前的检查9.1 常见问题表现象可能原因处理方式白屏QML 没加载成功或窗口未刷新检查qrc:/main.qml和日志找不到 main只保留了qtmain同时导出main和qtmain构建找不到 QtQT_PREFIX路径错误使用-DQT_PREFIX../qtforharmony启动失败Bundle Name 写错对照com.nutpi.shuiyinriji窗口缩放不刷新根对象没有跟随窗口尺寸使用响应式QQuickView刷新策略9.2 排查顺序先看 HAP 是否重新构建。再看安装的包名是不是当前项目。然后看日志里有没有 QML 或 main 符号错误。最后才去调整具体控件布局。十、还能继续加什么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_sdk11.3 为什么只保留三个链接这批文章用于项目发布和读者复现。链接过多会分散注意力所以正文只保留社区入口、OpenHarmony 文档和 Qt SDK 仓库三个入口。总结水印日记 这个 Demo 的重点是记录今日喝水次数。从工程角度看它已经覆盖了 Qt for OpenHarmony 项目里最关键的几步配置 Qt SDK、打包 QML、保留双入口、构建 HAP、安装启动和截图验证。如果你也在做 Qt 适配鸿蒙可以先用这种小项目把链路跑稳再逐步接入更真实的数据和业务。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力
