QT开发鸿蒙PC应用：环境搭建及第一个HelloWorld

背景概述

OpenHarmony 作为开源分布式操作系统，其生态逐渐丰富。QT 作为跨平台开发框架，在 OpenHarmony 上的适配为开发者提供了更多可能性。

本文通过环境搭建和第一个helloworld程序实践，旨在为开发者提供一份清晰的QT开发鸿蒙PC应用入门指南。

注：本文档中使用的Qt for OpenHarmony SDK 是由 OpenHarmony SIG 社区基于 Qt 5.15 独立开发和维护的开源项目，非Qt官方版本。

社区项目地址：https://gitcode.com/openharmony-sig/qt
SDK下载链接：https://gitcode.com/openharmony-sig/qt/releases

QT 与 OpenHarmony 的适配现状

QT 作为跨平台应用开发框架，对鸿蒙系统的适配展现出强大的灵活性和前瞻性。其模块化设计和丰富的工具链为开发者提供了高效移植和开发鸿蒙应用的可能。通过 OpenHarmony 的兼容层或原生接口调用，QT 应用能在鸿蒙设备上流畅运行。

QT 的跨平台特性显著降低了鸿蒙应用的多设备适配成本。同一套代码可部署在手机、平板、智能穿戴等多种鸿蒙终端，大幅提升开发效率。图形渲染引擎和 QML 语言特别适合鸿蒙的分布式 UI 设计要求，能快速构建响应式界面。

目前，得益于Qt出色的跨平台能力，许多知名应用如微信、WPS、钉钉、腾讯会议等均已成功适配鸿蒙生态。

环境搭建与配置

本文将详细说明开发环境的搭建步骤，包括QT SDK获取、OpenHarmony工程配置、编译工具链集成等，并提供针对Windows和Mac平台的配置示例。

文档适用范围

OpenHarmony API 15 (5.0.3) 及以上版本（本文示例使用 API 17）
Qt for OpenHarmony (基于 Qt 5.15)
DevEco Studio 5.0.5 及以上版本

前置条件

提前下载好鸿蒙开发者工具 DevEco Studio。
提前下载好 Qt for OpenHarmony SDK。
了解基础的 OpenHarmony 应用开发概念。

基于DevEco Studio的Qt应用创建

1. DevEco Studio下载与安装

官方下载地址 ：DevEco Studio官网
注意事项 ：
- 推荐使用最新稳定版本以获得最佳兼容性。
- 历史版本可能不支持最新的OpenHarmony API，可通过官网指定页面获取。
- 具体安装步骤请参考鸿蒙官方安装教程。

2. Qt SDK下载与配置

2.1 获取Qt for OpenHarmony SDK

Qt for OpenHarmony SDK

从发布页面下载适用于你开发平台（Windows或Mac）的SDK压缩包。

2.2 安装与验证Qt for OpenHarmony SDK

Mac平台示例：

打开终端，创建目录并解压SDK。

bash 复制代码

mkdir ~/QtForOpenHarmony
cd ~/Downloads
tar -xf Qt5.15.12_alpha_v7_arm64-v8a_openharmony_ndk_5.0.3.135_community_macos.tar.gz -C ~/QtForOpenHarmony

验证安装。
bash 复制代码
```
cd ~/QtForOpenHarmony/bin
./qmake -query
```
如果输出中包含 QMAKE_XSPEC:oh-clang，则表明Qt for OpenHarmony SDK安装成功。

Windows平台注意：

使用解压工具（如7-Zip）将SDK压缩包解压到指定目录，例如 C:\QtForOpenHarmony。
后续在DevEco Studio配置中，使用对应的Windows路径。

创建一个Qt Quick工程

1. 新建OpenHarmony工程

打开DevEco Studio，选择"Create Project"。
选择"Native C++"模板。
配置工程信息：
- Project Name : 你的工程名（如QtDemo）
- Bundle Name : 应用唯一标识（如com.example.qtdemo）
- Save Location: 工程保存路径
- Compile SDK : 选择API版本（如API 17）
- Model : 选择Stage
- Device Type : 按需选择（如Phone、Tablet）

2. 修改为OpenHarmony工程

工程创建后，需要修改工程级 build-profile.json5 文件：

在 products -> default 对象中添加 "compileSdkVersion": 17。

确保 compatibleSdkVersion 和 targetSdkVersion 值为数字（如17）。

json 复制代码

"products": [
  {
    "name": "default",
    "signingConfig": "default",
    "compileSdkVersion": 17,
    "targetSdkVersion": 17,
    "compatibleSdkVersion": 17,
    // ... 其他配置
  }
]

点击"Sync Now"同步工程，在弹出的确认框中点击"Yes"完成设备类型切换。

3. Qt Quick工程配置

3.1 修改Native编译配置

找到模块（通常是entry）下的 build-profile.json5 文件，修改 externalNativeOptions：

arguments: 指定你的Qt SDK绝对路径（-DQT_PREFIX=你的SDK路径）。

abiFilters: 指定设备架构（如["arm64-v8a"]）。

json 复制代码

"externalNativeOptions": {
  "path": "./src/main/cpp/CMakeLists.txt",
  "arguments": "-DQT_PREFIX=D:/Qt/Qt5.15.12_alpha_v7_arm64-v8a_openharmony_ndk_5.0.3.135",
  "cppFlags": "",
  "abiFilters": ["arm64-v8a"]
}

3.2 拷贝依赖文件

拷贝ets文件 ：将Qt SDK目录下的 openharmony/qtbase 文件夹内所有内容，复制并替换到工程 src/main/ets 目录下。
创建资源目录 ：在 src/main/resources 下创建 resfile 目录。
拷贝qml资源：
- 将Qt SDK下的 qml 目录，拷贝到 libs/arm64-v8a 目录下（库依赖）。
- 将Qt SDK下的 qml 目录，拷贝到 src/main/resources/resfile 目录下（资源文件）。

拷贝平台插件 ：将Qt SDK下的 plugins/platforms/libplugins_platforms_qopenharmony.so 文件拷贝到 libs/arm64-v8a 目录下。

3.3 配置UIAbility

确保 module.json5 文件中，EntryAbility 的 "launchType" 设置为 "specified"（指定实例模式，适用于多窗口）。

module.json5文件配置UIAbility组件，这是应用的入口。"launchType": "specified"表示该UIAbility为指定实例模式，若工程需要打开多个窗口时，应将launchType指定为specified。

json 复制代码

{
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntry":"./ets/abilitystage/MyAbilityStage.ets" ,// 关键配置
    // ...
    "abilities": [
      {
        "name": "EntryAbility",
        "launchType": "specified", // 关键配置
        // ... 其他配置
      }
    ]
  }
}

4. 编写Qt Quick的Hello World

4.1 清理与准备

移除 src/main/cpp 目录下默认生成的 napi_init.cpp 文件。
准备以下三个新文件：main.cpp, main.qml, qml.qrc，并将它们放在 src/main/cpp 目录下。

4.2 关键文件代码

CMakeLists.txt

cmake 复制代码

# the minimum version of CMake.
cmake_minimum_required(VERSION 3.5.0)
project(qtdemo)

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)

set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})

list(APPEND CMAKE_FIND_ROOT_PATH ${QT_PREFIX})
include_directories(${NATIVERENDER_ROOT_PATH}
                    ${NATIVERENDER_ROOT_PATH}/include)

find_package(QT NAMES Qt5 Qt6 REQUIRED COMPONENTS Core Widgets)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Concurrent Gui Network Qml Quick QuickControls2 Widgets QuickTemplates2 QmlWorkerScript)

add_library(entry SHARED main.cpp qml.qrc)
target_link_libraries(entry PRIVATE Qt${QT_VERSION_MAJOR}::Concurrent
Qt${QT_VERSION_MAJOR}::Core
Qt${QT_VERSION_MAJOR}::Gui
Qt${QT_VERSION_MAJOR}::Network
Qt${QT_VERSION_MAJOR}::Qml
Qt${QT_VERSION_MAJOR}::Quick
Qt${QT_VERSION_MAJOR}::Widgets
Qt${QT_VERSION_MAJOR}::QuickControls2
Qt${QT_VERSION_MAJOR}::QuickTemplates2
Qt${QT_VERSION_MAJOR}::QmlWorkerScript
  # 链接鸿蒙平台插件
Qt${QT_VERSION_MAJOR}::QOpenHarmonyPlatformIntegrationPlugin
)

main.cpp

cpp 复制代码

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QSurfaceFormat>

int main(int argc, char *argv[])
{
    // 配置 OpenGL ES 表面格式
    QSurfaceFormat format;
    format.setAlphaBufferSize(8);
    format.setBlueBufferSize(8);
    format.setGreenBufferSize(8);
    format.setRedBufferSize(8);
    format.setDepthBufferSize(24);
    format.setStencilBufferSize(8);
    format.setRenderableType(QSurfaceFormat::OpenGLES);
    format.setVersion(3, 0);
    QSurfaceFormat::setDefaultFormat(format);

    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    if (engine.rootObjects().isEmpty())
        return -1;
    return app.exec();
}

main.qml

qml 复制代码

import QtQuick 2.15
import QtQuick.Window 2.15

Window {
    width: 800
    height: 1200
    visible: true
    title: "Qt for 鸿蒙"

    Rectangle {
        anchors.fill: parent
        color: "lightblue"

        Text {
            id: myText
            text: "你好，Qt for 鸿蒙 blog.csdn.net/yyz_1987"
            font.pixelSize: 80
            color: "darkblue"
            anchors.centerIn: parent
        }

        MouseArea {
            anchors.fill: parent
            onClicked: {
                myText.text = "QTDemo by 猫哥"
            }
        }
    }
}

qml.qrc

xml 复制代码

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

5. 运行应用程序

使用USB数据线连接OpenHarmony开发板或鸿蒙PC（需开启开发者模式）。
在DevEco Studio顶部选择你的设备。
点击绿色运行按钮 (Run 'entry')。
如果运行在鸿蒙PC，需签名才能装。当然调式期间可以让自动生成debug签名后安装。
应用将自动编译、安装并运行在设备上。你将看到一个蓝色背景，中央显示"你好，Qt for 鸿蒙"的窗口，点击窗口任意位置，文字会发生变化。

构建过程总结

CMake在鸿蒙与Qt的结合中扮演着桥梁的角色。它不仅要负责Qt自身的MOC（元对象编译器）、UIC（UI编译器）流程，还要负责将鸿蒙的NDK能力注入到应用中。

为了更好地理解Qt项目是如何被编译并打包进HAP（Harmony Ability Package）的，我们需要先建立一个全局的构建流程图。这不仅仅是编译代码，更涉及到了资源处理、元数据合并以及签名等步骤。

如上图所示，核心产物是libapp.so，它承载了Qt应用的全部逻辑。而CMake的任务就是确保这个动态库能够正确地找到Qt的依赖（如Qt5Core, Qt5Gui）以及鸿蒙系统的底层能力（如Hilog, Rawfile）。

未来展望

OpenHarmony作为面向全场景的分布式操作系统，其与QT的深度融合潜力巨大。当前适配主要聚焦于移动设备，但未来向PC端的拓展值得期待。这需要QT社区与OpenHarmony SIG在以下方面持续努力：

深度技术适配：进一步优化QT在OpenHarmony内核上的性能，特别是针对PC形态的窗口管理、输入设备和高分辨率渲染的支持。
开发体验提升：完善QT Creator对OpenHarmony项目的直接支持，提供更流畅的编码、调试和部署体验。
生态建设：鼓励更多基于QT的流行开源库和组件适配OpenHarmony，丰富开发生态。
跨设备协同：探索利用QT框架与OpenHarmony分布式能力结合，简化跨手机、平板、PC等多设备应用开发的场景。

通过社区和开发者的共同努力，QT有望成为OpenHarmony生态中，尤其是未来PC应用开发的重要工具之一。

参考资料

坚果派 GitCode repo https://gitcode.com/nutpi/qtdemo/

GitCode 开源鸿蒙 repo Qt For OpenHarmony https://gitcode.com/openharmony-sig/qt/

QT官方wiki https://wiki.qt.io/Qt_for_OpenHarmony/zh

https://blog.csdn.net/lbcyllqj/article/details/155139449

技术博客-HarmonyOS-Qt应用开发