QML 与 C++ 混合编程
打通 QML 与 C++,掌握对象暴露与数据模型集成
#为什么必须混合
纯 QML 能做出漂亮的界面,但它算不了密集数据、访问不了硬件、也做不了复杂的业务逻辑与文件 IO。反过来,纯 C++ 做界面又回到命令式的泥潭。所以真实项目的分工是固定的:
- QML 负责外观与交互:布局、动画、状态、用户手势;
- C++ 负责数据与逻辑:网络、数据库、算法、线程、文件系统、设备驱动。
二者通过 Qt 元对象系统(meta-object system)通信。你在第四篇学过的 Q_OBJECT、Q_PROPERTY、信号槽,在这里是唯一的桥梁——只有被 moc 处理过的类才能被 QML 看见。理解这一点,很多"为什么 QML 访问不到我的成员"的困惑就迎刃而解了。
#三种集成方式
#方式一:QQmlApplicationEngine(新项目的默认选择)
QML 完全掌控界面,C++ 只提供对象与逻辑。这是 Qt 6 新建项目的模板写法。
// 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,可以放进任何布局。
#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。适合做小工具或子窗口。
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
有四条路,适用场合不同:
| 方式 | 用法 | 适用 |
|---|---|---|
setContextProperty | QML 中直接用名字访问 | 全局单例:配置、网络客户端、日志器 |
qmlRegisterType | QML 里 import 后当类型实例化 | 通用组件、可被多次创建的类 |
QML_ELEMENT | CMake 自动注册,无需手写 URI/版本 | Qt 6 推荐,替代上一个 |
QML_SINGLETON | QML 里直接用的唯一实例 | Qt 6 推荐的单例写法 |
Qt 6 的推荐做法是宏 + CMake 自动注册,省掉手写 qmlRegisterType 的维护成本:
// 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_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 侧使用:
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 / bool | number / bool |
QString | string |
QUrl / QColor / QFont | url / color / font |
QStringList / QVariantList | 数组 |
QVariantMap | JS 对象 |
QObject* | 对象引用 |
QDateTime / QPointF / QRectF | 对应值类型(Qt 6 支持更好) |
自定义 Q_GADGET 结构体 | 需 Q_GADGET + Q_PROPERTY 暴露成员 |
反过来,C++ 想调用 QML 里的函数或改 QML 对象属性,有两种方式:
// 方式 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 等接口做增量通知。
// 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。三条铁律:
beginInsertRows/endInsertRows、beginRemoveRows/endRemoveRows必须成对,中间才能改数据;忘了调用会导致视图与数据不一致甚至崩溃。rowCount对有效的 parent 必须返回 0(这是列表模型,不是树)。- 模型只能在 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。
#小结
- 分工原则:QML 管外观与交互,C++ 管数据与逻辑,二者靠元对象系统通信。
- 集成三选一:新项目
QQmlApplicationEngine;老 Widgets 项目QQuickWidget;独立小窗口QQuickView。 - 暴露对象四法:
setContextProperty(全局)、qmlRegisterType(类型)、QML_ELEMENT(Qt 6 推荐)、QML_SINGLETON(单例)。 Q_INVOKABLE/public slot 让 QML 调 C++;Q_PROPERTY+NOTIFY让 C++ 值变化自动驱动 QML 绑定。- 供数据必须用
QAbstractListModel+roleNames+ 成对的begin/end通知,且只能在 GUI 线程修改。
#练习
- 写一个
Calculator类(QML_ELEMENT),提供Q_INVOKABLE double add(double, double)和一个带 NOTIFY 的Q_PROPERTY(double lastResult),在 QML 中调用并绑定到 Label。 - 实现
TodoModel : QAbstractListModel,支持append/remove/toggleDone,分别使用正确的begin/end通知;QML 中用 ListView 展示并支持删除动画。 - 用
QQuickWidget把一个 QML 时钟控件嵌入到一个 Widgets 主窗口的布局中,并让 Widgets 侧的按钮能修改 QML 中文本的颜色。 - 制造并修复一个"绑定循环":在两个属性互相同步的代码上观察 Qt 的 Binding loop 警告,然后用判等或单向绑定修正它。