「开源鸿蒙跨平台开发先锋训练营」Day1 初探 QT for OpenHarmony

OpenHarmony与QT框架的适配为开发者提供了跨平台开发新可能。文章详细介绍了基于DevEco Studio的QT开发环境搭建流程，包括SDK配置、工程创建和QtQuick应用开发示例。目前QT已成功适配OpenHarmony系统，支持多窗口组件，微信、WPS等知名应用均已采用该方案。文章还展望了未来技术优化方向，包括性能提升、开发者生态建设等。通过21天开源鸿蒙训练营活动，开发者可快速掌握

JaneConan

1089人浏览 · 2025-11-21 22:25:30

JaneConan · 2025-11-21 22:25:30 发布

背景与概述

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

本次是跟着 GitCode 进行「21天开源鸿蒙跨平台先锋训练营」活动

欢迎大家报名参与 🔗报名链接 https://mp.weixin.qq.com/s/bfA0jRRhD3DlltZgCnbW9Q

请注意！！！ 请注意！！！ 请注意！！！

本文档中使用的Qt for OpenHarmony SDK 是由 OpenHarmony SIG 社区基于 Qt 5.15 独立开发和维护的开源项目，非Qt 官方版本。官方版本还请联系 QT 软件的客户代表。

https://gitcode.com/openharmony-sig/qt

Qt for OpenHarmony SDK 下载链接直达

https://gitcode.com/openharmony-sig/qt/releases

QT 与 OpenHarmony 的适配现状

很有幸和 QT 在大中华区的客户经理交流并了解到了 Qt For OpenHarmony 的生态情况。

在他们和鸿蒙工程师的能力下，已经适配成功了，尤其在 PC 多窗口常用组件等方面做了很大努力。目前 QT 在鸿蒙生态中的公开上架应用有很多，大家熟知的生产力工具微信、 WPS、中望 CAD、钉钉、剪映、福昕、腾讯会议等都是基于 QT 开发的。

以下内容均来自于 QT 官方

我们可以看到，得益于 Qt 出色的跨平台特性，我们很多常用跨平台软件都是基于 QT 去打造的。

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

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

QT 的底层优化与鸿蒙的微内核架构形成互补。事件处理机制和内存管理在鸿蒙环境下表现出色，尤其在资源受限的 IoT 设备上仍能保持稳定帧率。OpenGL ES 支持完美契合鸿蒙的图形加速架构。

QT Creator 提供鸿蒙项目模板和调试插件，支持从编码到部署的全流程。CMake 构建系统与鸿蒙的编译工具链无缝对接，自动化处理依赖管理和二进制打包。实时预览功能加速了鸿蒙特色组件（如 Service Ability）的界面设计。

QT 的开源协议与鸿蒙生态高度兼容，众多第三方库已完成鸿蒙适配。活跃的开发者社区持续产出鸿蒙专用扩展模块，如分布式数据管理接口的 QT 封装。文档中新增的鸿蒙最佳实践指南降低了学习曲线。

那客套话不多说，让我们进入开发状态。

环境搭建与配置

说明开发环境的搭建步骤，包括 QT 版本选择、OpenHarmony SDK 集成、编译工具链配置。

提供针对不同开发平台（这里特别指Windows 和 Mac）的详细配置示例。

文档适用范围

OpenHarmony API 15 (5.0.3)及以上版本（本文代码里用的是 API 17 ）
Qt for OpenHarmony (基于Qt 5.15)
DevEco Studio 5.0.5及以上版本

前置条件

提前下载好鸿蒙开发者工具和 QT OpenHarmony SDK
了解OpenHarmony应用开发基础

基于DevEco Studio的Qt应用创建

1. DevEco Studio下载与安装

官方下载地址：DevEco Studio官网
对于需要使用特定版本DevEco Studio的开发者，可通过以下页面获取历史版本。

注意事项：

推荐使用最新稳定版本以获得最佳兼容性

历史版本可能不支持最新的OpenHarmony API

下载前请确认版本与你的项目需求匹配

2. 安装步骤

在安装界面中，将“DevEco-Studio.app”拖拽到“Applications”中，等待安装完成。

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-software-install

详情请见鸿蒙官方教程，这里就不详细赘述了。

3. Qt SDK下载与配置

3.1 获取Qt for OpenHarmony SDK

下载地址：Qt for OpenHarmony SDK
版本说明：基于Qt 5.15开发，由OpenHarmony SIG社区维护
推荐版本：建议使用最新版本

3.2 安装Qt for OpenHarmony SDK

我是使用的 Mac 进行开发，所以

在终端执行以下命令，解压Qt SDK到指定目录（当然你也可以直接解压并拷贝）。

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

在终端继续执行以下命令，验证 Qt for OpenHarmony 的安装。

cd bin
./qmake -query

打印QMAKE_XSPEC:oh-clang即为Qt for OpenHarmony版本，Qt for OpenHarmony SDK安装完成。

至此基于DevEco Studio的Qt for OpenHarmony应用开发环境搭建完毕。

创建一个Qt Quick工程

1. 打开DevEco Studio新建项目，选择Native C++类型的模板工程创建空工程。

修改工程名称，并根据实际情况选择工程最终需要运行的设备类型，Bundle name为应用唯一标识需确保不和其它应用冲突，Save location可自行选择工程路径，Compatible SDK可根据设备的API版本号自行修改，主模块名称可自行修改:

参考鸿蒙官方文档指南开发环境搭建工程创建创建一个新的工程

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-create-new-project#section1826317225311

创建OpenHarmony工程（可选）

在完成创建HarmonyOS工程后，根据如下操作修改工程级build-profile.json5文件中相关字段：

在工程级build-profile.json5文件添加compileSdkVersion字段。
将compatibleSdkVersion、compileSdkVersion、targetSdkVersion（若有）字段赋值为数值类型。

将runtimeOS从"HarmonyOS"修改为**"OpenHarmony"**。

"products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compileSdkVersion": 15,
        //指定OpenHarmony应用编译时的版本，当前以API 15 为例
        "targetSdkVersion": 15,
        //指定OpenHarmony应用运行所需的目标SDK版本，当前以API 15 为例
        "compatibleSdkVersion": 15,
        //指定OpenHarmony应用兼容的最低版本，当前以API 15 为例
        "runtimeOS": "OpenHarmony",
        "buildOption": {
          "nativeCompiler": "BiSheng",
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ],

单击Sync Now进行同步。在Sync Check弹窗中点击Yes，同意将module.json5/config.json文件中的phone切换为OpenHarmony支持的default类型，并删除在OpenHarmony不适用的其他设备类型，同步成功无其他报错则工程创建完成。

2. Qt Quick工程配置

修改基础配置 ：找到创建工程时使用的模块对应目录下的build-profile.json5文件，修改arguments字段(指定Qt SDK路径)和abiFilters字段(最终运行的设备架构)：

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

拷贝ets文件依赖： 将Qt SDK目录下的openharmony/qtbase所有目录复制替换到工程模块下的src/main/ets目录下：

拷贝qml资源及库文件依赖： 将Qt SDK目录下的qml目录分别拷贝到工程模块下的libs/arm64-v8a(qml库依赖)和src/main/resources/resfile(qml资源文件依赖)目录下(resfile目录需要自己创建)

并将Qt SDK目录下的plugins/platforms/libplugins_platforms_qopenharmony.so拷贝到工程模块下的libs/arm64-v8a目录下：

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

{
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntry": "./ets/abilitystage/MyAbilityStage.ets",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "launchType": "specified",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ]
      }
    ],
    "extensionAbilities": [
      {
        "name": "EntryBackupAbility",
        "srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
        "type": "backup",
        "exported": false,
        "metadata": [
          {
            "name": "ohos.extension.backup",
            "resource": "$profile:backup_config"
          }
        ]
      }
    ]
  }
}

配置module.json5文件内容如下图所示。

3. 编写一个Qt Quick的Hello World工程

移除napi_init.cpp文件，修改CMakeLists.txt文件，并添加main.cpp、main.qml以及qml.qrc文件。

CMakeLists.txt

# 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

// main.cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QSurfaceFormat>

int main(int argc, char *argv[])
{
    // 配置 OpenGL ES 表面格式
    QSurfaceFormat format;
    format.setAlphaBufferSize(8);      // 确保 Alpha 通道位数
    format.setBlueBufferSize(8);       // 蓝色通道位数
    format.setGreenBufferSize(8);      // 绿色通道位数
    format.setRedBufferSize(8);        // 红色通道位数
    format.setDepthBufferSize(24);     // 深度缓冲区位数
    format.setStencilBufferSize(8);    // 模板缓冲区位数
    format.setRenderableType(QSurfaceFormat::OpenGLES); // 使用 OpenGL ES
    format.setVersion(3, 0);           // OpenGL ES 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

// main.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 鸿蒙"
            font.pixelSize: 80
            color: "darkblue"
            anchors.centerIn: parent
        }

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

qml.qrc

<?xml version="1.0" encoding="UTF-8"?>
<RCC>
    <qresource prefix="/">
        <file>main.qml</file>
    </qresource>
</RCC>

4. 启动，运行应用程序。

此为真机运行情况

未来展望

OpenHarmony作为华为推出的开源操作系统，正逐步构建跨设备、全场景的生态体系。QT作为成熟的跨平台开发框架，其与OpenHarmony的融合将为开发者提供更多可能性。QT的跨平台特性与OpenHarmony的分布式能力结合，有望简化多设备应用开发流程。

技术适配与优化方向

QT需要针对OpenHarmony的架构进行深度适配，包括对方舟编译器、分布式软总线等核心技术的支持。优化QT在OpenHarmony上的渲染性能、事件处理机制，确保应用在不同设备间流畅运行。针对OpenHarmony的FA/PA模型，提供相应的开发模板和工具链支持。

社区与开发者生态建设

建立QT for OpenHarmony的开发者社区，提供完善的文档、示例代码和技术支持。举办开发者大赛或黑客松活动，鼓励基于QT的OpenHarmony应用创新。与高校合作开设相关课程，培养具备QT和OpenHarmony双技能的开发人才。

商业化应用场景探索

在智能家居领域，利用QT的UI优势开发OpenHarmony分布式控制面板。工业物联网场景中，结合QT的图表功能和OpenHarmony的设备管理能力构建监控系统。车载信息娱乐系统方面，发挥QT的多媒体处理能力与OpenHarmony的车机互联特性。

长期演进路线规划

短期聚焦基础框架适配，实现QT核心模块在OpenHarmony上的稳定运行。中期发展领域专用库，如自动化测试、3D渲染等垂直领域支持。长期构建完整的QT for OpenHarmony开发生态，形成从设计到部署的全流程工具链。保持与OpenHarmony主版本同步更新，及时支持新特性和API。

参考资料

特别感谢坚果老师的指导 🌰 坚果派 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://edu.csdn.net/course/detail/40825

并考取开发者认证证书

https://developer.huawei.com/consumer/cn/training/classDetail/a23831c901814ad5a874553abc65ca93

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

以递归的方式快速创建文件和目录开源项目AdvancedNewFile命令行工具适配开源鸿蒙PC实战指南

人工智能6S服务平台

0基础入门昇腾CANN课程：30分钟写出首个高性能算子（附可直接运行代码）

人工智能6S服务平台

为什么你的播放器总“差半拍”？[特殊字符][特殊字符]——鸿蒙OS多媒体栈到底怎么把一切对上节拍的？

人工智能6S服务平台

所有评论(0)

查看更多评论

JaneConan

@weixin_31236533

已为社区贡献2条内容