QC++ / Qt 学习之路

QML 与 C++ 混合编程

打通 QML 与 C++,掌握对象暴露与数据模型集成

进阶第 37 / 48 章第五篇 · QML 与实战项目

#为什么必须混合

纯 QML 能做出漂亮的界面,但它算不了密集数据、访问不了硬件、也做不了复杂的业务逻辑与文件 IO。反过来,纯 C++ 做界面又回到命令式的泥潭。所以真实项目的分工是固定的:

QML 与 C++ 交互架构QML 负责界面,C++ 负责逻辑,QQmlApplicationEngine 充当桥梁QML 层:界面与交互property 绑定onXxx: 信号处理器cppObj.setValue(1)ListView { model: cppModel }delegate: Text { ... }QML 只描述界面与绑定,不写业务逻辑QQmlApplicationEngine + QQmlContext(桥梁)engine.load(url); // 建立上下文并绑定属性C++ 层:QObject 派生类(业务逻辑)Q_PROPERTYQ_INVOKABLEsignals:Q_OBJECT 宏 → moc 生成元对象,属性与信号槽都依赖它三种把 C++ 暴露给 QML 的方式setContextProperty全局单例,QML 直接用名字qmlRegisterTypeQML_ELEMENT:QML 中当类型用QAbstractListModel给 ListView / Repeater 当 model需实现 rowCount / data / roleNames增删时用 begin/endInsertRowsC++ 用 Q_PROPERTY 暴露属性、Q_INVOKABLE 暴露方法、signals 通知变化;QML 用绑定与信号处理器响应
QML 与 C++ 的分层与三种暴露方式
  • QML 负责外观与交互:布局、动画、状态、用户手势;
  • C++ 负责数据与逻辑:网络、数据库、算法、线程、文件系统、设备驱动。

二者通过 Qt 元对象系统(meta-object system)通信。你在第四篇学过的 Q_OBJECT、Q_PROPERTY、信号槽,在这里是唯一的桥梁——只有被 moc 处理过的类才能被 QML 看见。理解这一点,很多"为什么 QML 访问不到我的成员"的困惑就迎刃而解了。

#三种集成方式

#方式一:QQmlApplicationEngine(新项目的默认选择)

QML 完全掌控界面,C++ 只提供对象与逻辑。这是 Qt 6 新建项目的模板写法。

C++
// main.cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQmlContext>
#include "Backend.h"

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    // 注册 C++ 类型,使其在 QML 中可用:import MyApp 1.0 后写 Backend { }
    qmlRegisterType<Backend>("MyApp", 1, 0, "Backend");

    QQmlApplicationEngine engine;

    // 注入一个全局单例对象(无需在 QML 中实例化)
    AppConfig config;
    engine.rootContext()->setContextProperty("appConfig", &config);

    QObject::connect(&engine, &QQmlApplicationEngine::objectCreationFailed,
                     &app, [] { QCoreApplication::exit(1); });
    engine.loadFromModule("MyApp", "Main");   // Qt 6 推荐:按模块加载

    return app.exec();
}

loadFromModule("MyApp", "Main") 依赖 qt_add_qml_module 在 CMake 中声明的 QML 模块名与资源 URI,比 Qt 5 的 engine.load(QUrl("qrc:/main.qml")) 更健壮(编译期检查、自动处理资源前缀)。

#方式二:QQuickWidget(往已有 Widgets 程序里嵌 QML)

你手上有一个几万行的 Widgets 老项目,想把其中某个页面换成 QML(比如一个炫酷的仪表盘),这时用 QQuickWidget——它是个普通 QWidget,可以放进任何布局。

C++
#include <QApplication>
#include <QQuickWidget>
#include <QVBoxLayout>
#include <QPushButton>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QWidget w;
    auto *layout = new QVBoxLayout(&w);

    auto *quick = new QQuickWidget;
    quick->setResizeMode(QQuickWidget::SizeRootObjectToView);  // 关键:跟随控件尺寸
    quick->setSource(QUrl("qrc:/qt/qml/MyApp/Dashboard.qml"));
    quick->setClearColor(Qt::white);

    layout->addWidget(new QPushButton("上面是 QML,下面是 Widgets"));
    layout->addWidget(quick, 1);

    w.resize(800, 600);
    w.show();
    return app.exec();
}

代价:QQuickWidget 通过把场景图渲染到纹理再合成,性能略低于纯 QML 窗口,且不支持部分窗口级特性(如半透明窗口)。能用纯 QML 窗口就别用它;它是迁移工具,不是首选架构。

#方式三:QQuickView(轻量窗口)

QQuickView 是一个显示 QML 的独立窗口,比 QQmlApplicationEngine 更轻,但它不负责创建 ApplicationWindow——QML 根对象必须是普通 Item/Rectangle。适合做小工具或子窗口。

C++
QQuickView view;
view.setResizeMode(QQuickView::SizeRootObjectToView);
view.setInitialProperties({{ "targetName", QString("温度") }});  // 给根对象设初值
view.setSource(QUrl("qrc:/qt/qml/MyApp/Panel.qml"));
view.show();

三者的选择规则:新项目用 QQmlApplicationEngine;老 Widgets 项目局部嵌入用 QQuickWidget;需要独立轻量窗口用 QQuickView。

#把 C++ 对象暴露给 QML

有四条路,适用场合不同:

方式用法适用
setContextPropertyQML 中直接用名字访问全局单例:配置、网络客户端、日志器
qmlRegisterTypeQML 里 import 后当类型实例化通用组件、可被多次创建的类
QML_ELEMENTCMake 自动注册,无需手写 URI/版本Qt 6 推荐,替代上一个
QML_SINGLETONQML 里直接用的唯一实例Qt 6 推荐的单例写法

Qt 6 的推荐做法是宏 + CMake 自动注册,省掉手写 qmlRegisterType 的维护成本:

C++
// backend.h
#pragma once
#include <QObject>
#include <QString>
#include <QQmlEngine>

class Backend : public QObject
{
    Q_OBJECT
    QML_ELEMENT                       // 让 qt_add_qml_module 发现并注册它
    Q_PROPERTY(QString userName READ userName WRITE setUserName NOTIFY userNameChanged)
    Q_PROPERTY(int progress READ progress NOTIFY progressChanged)
public:
    explicit Backend(QObject *parent = nullptr) : QObject(parent) {}

    QString userName() const { return m_user; }
    void setUserName(const QString &n) {
        if (m_user == n) return;      // 必须判等,否则可能触发无限循环
        m_user = n;
        emit userNameChanged();
    }
    int progress() const { return m_progress; }

    // Q_INVOKABLE:普通成员方法也能被 QML 调用(public slot 也行)
    Q_INVOKABLE QString greet(const QString &who) const {
        return QStringLiteral("你好,%1(来自 %2)").arg(who, m_user);
    }
    Q_INVOKABLE void startWork();

public slots:
    // 由 QML 或 C++ 调用,内部可能异步
    void onQmlButtonClicked(const QString &payload);

signals:
    void userNameChanged();
    void progressChanged();
    void workFinished(bool ok, const QString &message);   // 带参数,QML 可直接接收

private:
    QString m_user = "匿名";
    int m_progress = 0;
};

配套的 CMake(这是 Qt 6 的关键,漏了就找不到类型):

CMake
cmake_minimum_required(VERSION 3.16)
project(MyApp LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Quick)

qt_standard_project_setup()
qt_add_executable(MyApp main.cpp backend.h backend.cpp)

qt_add_qml_module(MyApp
    URI MyApp
    VERSION 1.0
    QML_FILES Main.qml Dashboard.qml
)

target_link_libraries(MyApp PRIVATE Qt6::Quick)

QML 侧使用:

QML
import QtQuick
import QtQuick.Controls
import MyApp            // 无版本号:Qt 6 会自动匹配 1.0

ApplicationWindow {
    visible: true
    width: 520; height: 320
    title: backend.userName            // 直接绑定 Q_PROPERTY!

    Backend {                          // QML_ELEMENT 注册的类型,可实例化
        id: backend
        userName: "张三"
        onWorkFinished: (ok, msg) => resultLabel.text = (ok ? "成功:" : "失败:") + msg
    }

    Column {
        anchors.centerIn: parent
        spacing: 12

        Label {
            id: resultLabel
            text: backend.greet("QML")  // 调用 Q_INVOKABLE
        }

        ProgressBar {
            value: backend.progress / 100      // C++ 改值 → 进度条自动更新
            width: 300
        }

        Button {
            text: "开始工作"
            onClicked: backend.onQmlButtonClicked("payload-from-qml")
        }

        TextField {
            placeholderText: "修改用户名"
            onAccepted: backend.userName = text   // 写属性,触发 setter
        }
    }
}

注意 title: backend.userName 这一行:Q_PROPERTY 带着 NOTIFY 信号时,QML 的绑定才会自动更新。如果省略 NOTIFY,绑定只能生效一次,C++ 里改了值界面也不动——这是最高频的坑。

#类型映射与从 C++ 调用 QML

QML 与 C++ 之间所有数据都过 QVariant。基本类型自动转换:

C++QML
int / double / boolnumber / bool
QStringstring
QUrl / QColor / QFonturl / color / font
QStringList / QVariantList数组
QVariantMapJS 对象
QObject*对象引用
QDateTime / QPointF / QRectF对应值类型(Qt 6 支持更好)
自定义 Q_GADGET 结构体需 Q_GADGET + Q_PROPERTY 暴露成员

反过来,C++ 想调用 QML 里的函数或改 QML 对象属性,有两种方式:

C++
// 方式 A:调用 QML 根对象的函数(要求该函数在 QML 中定义)
QObject *root = engine.rootObjects().first();
QVariant returned;
QMetaObject::invokeMethod(root, "qmlFunction",
                          Q_RETURN_ARG(QVariant, returned),
                          Q_ARG(QVariant, 42));
qDebug() << "QML 返回:" << returned;

// 方式 B:直接读写属性(等价于 QML 里的赋值)
root->setProperty("someProperty", QString("来自 C++"));
QString v = root->property("someProperty").toString();

方式 B 会打断 QML 侧的绑定(和上一章讲的属性赋值一样),只在确需"强制覆盖"时使用。更干净的做法是让 QML 声明一个 Invokable 函数,由 QML 自己去改状态。

另一种常见需求是"QML 只是程序的一小部分,主界面仍是 Widgets",此时还有第四条路:在 QQuickWidget 里加载 QML,然后用 rootObject() 拿到 QML 根对象,双向读写属性。但无论哪种方式,都要记住一条底线——C++ 不要去操作 QML 内部的子对象。正确做法是让 QML 把需要被外部访问的東西提升为根对象的属性或函数,C++ 只与根对象对话,QML 内部怎么重构都不会影响 C++。这本质上就是"面向接口而非实现",跨语言的边界上尤其重要。

#QAbstractListModel:给 QML 供数据的正道

把 std::vector 转成 QVariantList 丢给 QML 看似省事,但每次数据变化都要整体替换 model,委托全部重建,滚动位置丢失,性能极差。正确的做法是继承 QAbstractListModel,用 dataChanged/beginInsertRows 等接口做增量通知。

C++
// devicemodel.h
#pragma once
#include <QAbstractListModel>
#include <QString>

struct Device { QString name; QString ip; bool online; double cpu; };

class DeviceModel : public QAbstractListModel
{
    Q_OBJECT
    QML_ELEMENT
public:
    enum Role { NameRole = Qt::UserRole, IpRole, OnlineRole, CpuRole };

    int rowCount(const QModelIndex &parent = {}) const override {
        return parent.isValid() ? 0 : m_data.size();
    }

    QVariant data(const QModelIndex &index, int role) const override {
        if (!index.isValid() || index.row() >= m_data.size()) return {};
        const Device &d = m_data.at(index.row());
        switch (role) {
        case NameRole:   return d.name;
        case IpRole:     return d.ip;
        case OnlineRole: return d.online;
        case CpuRole:    return d.cpu;
        default:         return {};
        }
    }

    // roleNames 决定 QML 委托里能写 model.name / model.cpu 这样的名字
    QHash<int, QByteArray> roleNames() const override {
        return { {NameRole, "name"}, {IpRole, "ip"},
                 {OnlineRole, "online"}, {CpuRole, "cpu"} };
    }

    Q_INVOKABLE void updateCpu(int row, double cpu) {
        if (row < 0 || row >= m_data.size()) return;
        m_data[row].cpu = cpu;
        // 精确通知:只刷这一行的这一个角色
        QModelIndex idx = index(row);
        emit dataChanged(idx, idx, { CpuRole });
    }

    void appendDevice(const Device &d) {
        beginInsertRows({}, m_data.size(), m_data.size());   // 必须成对调用
        m_data.append(d);
        endInsertRows();
    }

private:
    QList<Device> m_data;
};

QML 侧委托与上一章的 ListModel 版本完全一样,只把 model: taskModel 换成 model: deviceModel。三条铁律:

  1. beginInsertRows / endInsertRows、beginRemoveRows / endRemoveRows 必须成对,中间才能改数据;忘了调用会导致视图与数据不一致甚至崩溃。
  2. rowCount 对有效的 parent 必须返回 0(这是列表模型,不是树)。
  3. 模型只能在 GUI 线程修改。工作线程里的改动要通过信号槽排队到主线程(信号槽默认的 AutoConnection 会自动跨线程排队)。

#常见坑清单

  • 忘了 Q_OBJECT 或 QML_ELEMENT:QML 报 "is not a type",检查 CMake 是否用了 qt_add_qml_module 并把头文件列入了目标源。
  • Q_PROPERTY 没有 NOTIFY:绑定只生效一次。只读属性也要给 NOTIFY(或写成 CONSTANT)。
  • setter 里没判等就 emit:A 通知 B、B 又通知 A,造成绑定循环,Qt 会输出 "Binding loop detected" 警告并可能卡死。
  • 跨线程直接改模型:ListView 崩溃或渲染错乱。用 QMetaObject::invokeMethod(obj, ..., Qt::QueuedConnection)。
  • setContextProperty 的对象生命周期:必须保证它比 engine 活得久,否则 QML 访问野指针。用栈对象写在 main() 里是安全的,用堆对象记得设 parent。
  • QML 里访问不到 enum:用 Q_ENUM 注册,QML 中写作 Backend.NameRole;如需字符串键名用 Q_ENUM + roleNames 组合。
  • 把 QObject* 传给 QML 但没有父对象:QML/JS 引擎可能尝试回收它导致悬空,建议设 parent 或用 QQmlEngine::setObjectOwnership。

#小结

  1. 分工原则:QML 管外观与交互,C++ 管数据与逻辑,二者靠元对象系统通信。
  2. 集成三选一:新项目 QQmlApplicationEngine;老 Widgets 项目 QQuickWidget;独立小窗口 QQuickView。
  3. 暴露对象四法:setContextProperty(全局)、qmlRegisterType(类型)、QML_ELEMENT(Qt 6 推荐)、QML_SINGLETON(单例)。
  4. Q_INVOKABLE/public slot 让 QML 调 C++;Q_PROPERTY + NOTIFY 让 C++ 值变化自动驱动 QML 绑定。
  5. 供数据必须用 QAbstractListModel + roleNames + 成对的 begin/end 通知,且只能在 GUI 线程修改。

#练习

  1. 写一个 Calculator 类(QML_ELEMENT),提供 Q_INVOKABLE double add(double, double) 和一个带 NOTIFY 的 Q_PROPERTY(double lastResult),在 QML 中调用并绑定到 Label。
  2. 实现 TodoModel : QAbstractListModel,支持 append/remove/toggleDone,分别使用正确的 begin/end 通知;QML 中用 ListView 展示并支持删除动画。
  3. 用 QQuickWidget 把一个 QML 时钟控件嵌入到一个 Widgets 主窗口的布局中,并让 Widgets 侧的按钮能修改 QML 中文本的颜色。
  4. 制造并修复一个"绑定循环":在两个属性互相同步的代码上观察 Qt 的 Binding loop 警告,然后用判等或单向绑定修正它。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。