在 Mac 上用 DevEco + Qt for OpenHarmony 开发你的第一个 QML 应用

时光慢煮

73人浏览 · 2026-06-17 13:03:43

时光慢煮 · 2026-06-17 13:03:43 发布

在 Mac 上用 DevEco + Qt for OpenHarmony 开发你的第一个 QML 应用

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

一句话：不敲命令行交叉编译，在 DevEco Studio 里用 Native C++ 模板 + 社区 Qt SDK，直接写一个在鸿蒙设备上跑的 Qt Quick 应用。
前提：Mac 已装 DevEco Studio + OHOS SDK，有 Qt/C++ 基础。

在这里插入图片描述

一、版本号要对齐

开始之前确认三件事：

软件	要求
DevEco Studio	≥ 5.0.5
OHOS API	≥ 12
Qt SDK	5.15.12 alpha 社区预编译版

Apple Silicon Mac 先装 Rosetta：

softwareupdate --install-rosetta --agree-to-license

在这里插入图片描述

二、下载 Qt for OpenHarmony 社区 SDK

不需要自己编译 Qt。社区有预编译包。

下载地址：https://atomgit.com/openharmony-sig/qt/releases

找到最新 alpha 标签，下 Mac 版，文件名类似 Qt5.15.12_alpha_v7_arm64-v8a_openharmony_ndk_5.0.3.135_community_macos.tar.gz。

mkdir -p ~/QtForOpenHarmony
tar -xzf Qt5.15.12_alpha_v7_*.tar.gz -C ~/QtForOpenHarmony

# 验证
cd ~/QtForOpenHarmony/bin
./qmake -query
# 看到 QMAKE_XSPEC:oh-clang 即成功

支持的 Qt 模块：Core / Gui / Widgets / Network / Qml / Quick / QuickControls2 / QuickWidgets / Sql / Svg / Concurrent / PrintSupport / Multimedia。不支持 QtWebEngine。

在这里插入图片描述

三、新建工程 + 改造为 Qt Quick

步骤 1：新建 Native C++ 工程

DevEco → New Project → Native C++ → Next

Project name：QtForHOHello
Compile SDK：API 12+
Device type：勾 2in1（鸿蒙 PC 必勾）
路径纯英文

步骤 2：删掉模板自带的 napi_init.cpp

右键 entry/src/main/cpp/napi_init.cpp → Delete

步骤 3：拷贝 Qt SDK 文件到工程

QT_SDK=~/QtForOpenHarmony

# Qt 头文件 + 库
cp -r $QT_SDK/openharmony/qtbase/* entry/src/main/ets/

# QML 运行库
cp -r $QT_SDK/qml entry/libs/arm64-v8a/
mkdir -p entry/src/main/resources/resfile
cp -r $QT_SDK/qml entry/src/main/resources/resfile/

# 平台插件
cp $QT_SDK/plugins/platforms/libplugins_platforms_qopenharmony.so \
   entry/libs/arm64-v8a/

步骤 4：替换 CMakeLists.txt

entry/CMakeLists.txt 全替换为：

cmake_minimum_required(VERSION 3.5.0)
project(QtForHOHello)

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

list(APPEND CMAKE_FIND_ROOT_PATH ${QT_PREFIX})

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
    OpenHarmonyPlatformIntegrationPlugin)

add_library(entry SHARED main.cpp qml.qrc)

target_link_libraries(entry PRIVATE
    Qt${QT_VERSION_MAJOR}::Core Qt${QT_VERSION_MAJOR}::Gui
    Qt${QT_VERSION_MAJOR}::Quick Qt${QT_VERSION_MAJOR}::Qml
    Qt${QT_VERSION_MAJOR}::QuickControls2 Qt${QT_VERSION_MAJOR}::Widgets
    Qt${QT_VERSION_MAJOR}::Concurrent Qt${QT_VERSION_MAJOR}::Network
    Qt${QT_VERSION_MAJOR}::OpenHarmonyPlatformIntegrationPlugin)

步骤 5：写 3 个 Qt 文件

在 entry/src/main/cpp/ 下新建：

main.cpp：

#include <QGuiApplication>
#include <QQmlApplicationEngine>

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

main.qml：

import QtQuick 2.15
import QtQuick.Window 2.15
import QtQuick.Controls 2.15

Window {
    width: 640; height: 480; visible: true
    title: "Qt Quick on HarmonyOS"

    Rectangle {
        width: 400; height: 240; color: "#e0f0ff"; radius: 12
        anchors.centerIn: parent

        Column {
            anchors.centerIn: parent; spacing: 16
            Text {
                text: "Hello from Qt Quick!"
                font.pixelSize: 28; font.bold: true
                color: "#1a1a2e"
                anchors.horizontalCenter: parent.horizontalCenter
            }
            Text {
                text: "Running on HarmonyOS via DevEco"
                font.pixelSize: 14; color: "#555"
                anchors.horizontalCenter: parent.horizontalCenter
            }
            Button {
                text: "Click Me"
                anchors.horizontalCenter: parent.horizontalCenter
                onClicked: console.log("Clicked!")
            }
        }
    }
}

qml.qrc：

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

步骤 6：配 build-profile.json5

entry/build-profile.json5，找到 externalNativeOptions，改成：

"arguments": "-DQT_PREFIX=/Users/<你的用户名>/QtForOpenHarmony",
"abiFilters": ["arm64-v8a"]

注意：QT_PREFIX 绝对路径必须对。

步骤 7：module.json5 支持多窗口

entry/src/main/module.json5，把 abilities[0].launchType 改成 "specified"——否则多窗口 Qt 应用会受限。

四、编译 + 运行

DevEco → File → Sync Project（等一下 ohpm 装依赖）
DevEco → Build → Build App（⌘+F9） 或直接 ▶ Run（⌃+R）

连上鸿蒙设备，点 Run。预期结果：设备屏幕出现一个蓝色圆角矩形，中间写着 “Hello from Qt Quick!” + 一个可点击按钮。

五、6 个常见坑

#1 `QT_PREFIX` 路径不对

现象：cmake 配置报 Could NOT find Qt5
解决：entry/build-profile.json5 里 QT_PREFIX 必须是绝对路径且指向 ~/QtForOpenHarmony（不是 ~/QtForOpenHarmony/bin）

#2 忘了删 napi_init.cpp

现象：编译报 multiple definition of main
解决：删除 entry/src/main/cpp/napi_init.cpp

#3 没有拷贝 QML 到 resfile

现象：应用启动白屏，hilog 报 qrc:/main.qml not found
解决：mkdir -p entry/src/main/resources/resfile && cp -r $QT_SDK/qml entry/src/main/resources/resfile/

#4 launchType 没改成 specified

现象：第二个 Qt 窗口打不开
解决：module.json5 里 launchType: "specified"

#5 Qt SDK 版本和 OHOS API 不匹配

现象：链接时 undefined symbol 一大片
解决：Qt SDK 文件名里有 ndk_5.0.3.135 字样——这个 NDK 版本必须和 DevEco 装的 OHOS API 的 Native SDK 版本一致

#6 arm64-v8a 滤镜没设

现象：编译产物是 x86_64 不是 aarch64
解决：build-profile.json5 中 abiFilters 写 ["arm64-v8a"]

六、5 个关键 Qt API 提示

场景	用哪个
窗口应用	`QGuiApplication` + `QQmlApplicationEngine`
Widget 应用	`QApplication` + QWidget 子类
多窗口	`launchType: specified` + 多个 Window 对象
系统能力查询	Qt 提供了 `QSysInfo::productType()` 等 API，但不能替代 ArkTS 的 `canIUse()`
资源加载	QML 里的图片/SVG 走 `qrc:/` 前缀

七、如果遇到"编译通过但真机黑屏"

按顺序排查：

hdc shell hilog | grep QtForHO——看有没有明显错误
确认 entry/libs/arm64-v8a/ 下有 libplugins_platforms_qopenharmony.so
确认 entry/src/main/resources/resfile/qml/ 下有 QML 运行库
确认 module.json5 里有 2in1 在 deviceTypes 里

八、什么时候用这条路 vs 用已有的 Qt Widget 老项目

新项目：首选本路径（DevEco + Qt Quick / QML）——从零开发快、声明式 UI 改起来方便
老项目：如果已有 Qt Widget 应用，能做两件事：优先评估能不能用 QML 重写核心界面；如果不适合重写，再考虑交叉编译整包移植
团队习惯 C++ 多于 QML：可以先跑通本篇的 Hello World 感受一下，再决定长期用哪种方式

九、配套资源

资源	链接
Qt for OpenHarmony Wiki	`wiki.qt.io/Qt_for_OpenHarmony/zh`
社区预编译 Qt SDK 下载	`atomgit.com/openharmony-sig/qt/releases`
DevEco Studio 下载	`developer.huawei.com/consumer/cn/deveco-studio/`