前言欢迎加入鸿蒙PC开发者社区共同打造开发者工具生态鸿蒙PC开发者社区 https://harmonypc.csdn.net/项目开源地址https://atomgit.com/lqjmac/qttc本文围绕一个轻量应用把 AppScope、CMake、QML、HAP 构建和 hdc 启动命令连起来看。本文记录第 17 个 Qt 适配鸿蒙小项目图屉。它的定位是图片浏览器核心功能是本地图片上一张、下一张浏览。这里不读取相册也不依赖外部文件只用内置样例图形模拟图片浏览器的信息结构。图屉 的工程价值不是功能复杂而是把 Qt Quick、OpenHarmony HAP、QML 资源和窗口刷新串成一条可复现路径。提示本文按真实工程路径和真实 Bundle Name 编写命令可以直接对照项目目录执行。推荐阅读顺序确认项目目录、中文展示名和 Bundle Name。检查 Qt SDK 相对路径避免构建机路径绑定。运行构建、安装、启动和日志过滤命令。本文包含的重点元素项目截图配置表格构建命令QML 片段常见问题表一、从用户操作倒推实现1.1 项目解决什么问题图屉不是为了把 图片浏览器 做到复杂而是为了验证 Qt Quick 在鸿蒙桌面窗口里的完整链路。这个链路包含资源配置、Native CMake、QML 首屏、双入口导出、窗口自适应、HAP 构建和设备启动。主要功能如下展示当前图片预览上一张下一张浏览缩放状态切换展示标题尺寸和标签缩略图列表快速切换1.2 最终运行截图图 1图屉 在 OpenHarmony 桌面环境里的运行效果。1.3 关注点速览关注点为什么重要在本项目中的体现应用标识避免 25 个 Demo 安装冲突com.nutpi.tutiQML 状态决定界面是否能即时反馈通过 currentIndex 统一驱动预览、详情和缩略图选中态构建参数决定换机器后能否继续构建-DQT_PREFIX../qtforharmony启动入口避免白屏和符号缺失同时保留main和qtmain二、工程信息2.1 信息总览项目内容应用展示名图屉项目目录名QtImageViewerLiteBundle Namecom.nutpi.tutiCMake projecttuti_imageviewer项目类型图片浏览器核心功能本地图片上一张、下一张浏览这张表建议和 README 中的信息保持一致。项目多了以后最怕的是展示名、包名和目录名互相错位。2.2 目录结构qt_for_harmony/ ├── qtforharmony/ ├── QtImageViewerLite/ │ ├── 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.tuti是否唯一entry/build-profile.json5native 构建参数Qt SDK 相对路径entry/src/main/cppC 入口和 QMLmain.qml是否进入 qrcREADME.md项目说明构建和启动命令是否完整三、配置文件关键点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(tuti_imageviewer) 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 } }实际工程中图屉 使用的是photoModel。这些数据都在 QML 内部适合单机演示。五、状态流转5.1 函数职责表函数职责currentPhoto()切换当前展示内容nextPhoto()切换当前展示内容previousPhoto()切换当前展示内容imageScale()封装业务逻辑setPhoto(indexValue)切换当前展示内容这些函数没有故意抽得很复杂。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 }这段不是要照搬而是说明当前项目的函数组织方式先从模型拿当前数据再执行用户动作最后让绑定表达式刷新界面六、main 与 qtmain6.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 构建 HAPcdQtImageViewerLite /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.tuti-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|tuti|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/tuti_screen.jpeg hdcfilerecv /data/local/tmp/tuti_screen.jpeg ./qt-docs/assets/tuti-screen.jpeg截图不是装饰它是确认首屏真的渲染出来的证据。8.3 当前项目验证点切换图片后详情同步缩放状态文本变化缩略图选中态正确注意文章里提到的业务数据都是 QML 内置示例数据不代表已经接入系统能力或外部服务。九、FAQ9.1 常见问题表现象可能原因处理方式白屏QML 没加载成功或窗口未刷新检查qrc:/main.qml和日志找不到 main只保留了qtmain同时导出main和qtmain构建找不到 QtQT_PREFIX路径错误使用-DQT_PREFIX../qtforharmony启动失败Bundle Name 写错对照com.nutpi.tuti窗口缩放不刷新根对象没有跟随窗口尺寸使用响应式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 适配鸿蒙可以先用这种小项目把链路跑稳再逐步接入更真实的数据和业务。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力
