导读:QML 负责「界面长什么样」,C++ 负责「数据是什么、怎么算」,这句话谁都会说,但真正动手时卡人的永远是三个细节:C++ 对象怎么暴露给 QML、QML 怎么回调 C++、C++ 数据变了界面怎么自动刷新。
本文用仓库里一个能直接跑起来的 Qt Quick 示例(QtQuick3DDemo)把这三件事讲透。它的特别之处在于:同一个窗口里同时跑着两套桥接方案 —— 求和用的是 Qt 6 推荐的 QML_ELEMENT 类型注册,背景色切换用的是传统的 setContextProperty 上下文属性注入。对照组就在眼前,区别一眼就能看懂。
文中所有代码均摘自项目真实源码(main.cpp / Main.qml / backend.* / add.* / CMakeLists.txt),行尾注释为源码原有注释,可整段复制编译。
环境:Qt 6.11.2 + MSVC 2022 64-bit + CMake 3.16+(CMakeLists 中 REQUIRES 6.10 为最低版本)|适合:刚从 QWidget 转 Qt Quick、或者被 QML_ELEMENT / qmlcachegen / 上下文属性生命周期折腾过的开发者。
本文目录
00 先看效果:这个 Demo 做了什么 | 01 环境准备与三步跑起来 | 02 工程结构与整体架构
03 方式一 setContextProperty | 04 方式二 QML_ELEMENT | 05 一次点击的完整链路
06 虚拟键盘 | 07 背景色切换 | 08 退出期 TypeError 复盘 | 09 两种方式怎么选
10 编码约定 | 11 FAQ | 12 小结 | 附录 A / B 完整源码
0. 先看效果:这个 Demo 到底做了什么
启动后是一个 640×480 的窗口,界面很朴素,但每一块都对应着一条 C++ ↔ QML 的通路:

图 0-1 程序主界面,初始状态 12 + 30 = 42

图 0-2 界面元素编号,下面按号说明每个控件背后走的是哪条桥
| 编号 | 界面元素 | 背后发生了什么 |
|---|---|---|
| ① | 窗口标题栏 | ApplicationWindow 的 title,纯 QML |
| ② | 主标题「QML 界面 + C++ 后端示例」 | 纯 QML 文本 |
| ③ | 小字说明 | 点明本项目的对照关系:求和=方式二,背景=方式一 |
| ④ / ⑤ | 两个 SpinBox(默认 12、30) |
纯 QML 输入,可配合虚拟键盘 |
| ⑥ | 「C++ 后端求和」按钮 | QML → C++(方式二):调用 ADD 的两个 Q_INVOKABLE 方法 |
| ⑦ | 结果文本 12 + 30 = 42 |
C++ → QML(方式二):绑定 ADD.sum,靠 NOTIFY 信号自动刷新 |
| ⑧ | 「切换背景色(C++ 后端)」按钮 | QML → C++(方式一):调用 backend.toggleBackground();背景色再经属性绑定回刷界面 |
把加数改成 14 和 29,点一下「C++ 后端求和」,结果立刻变成 43:

图 0-3 14 + 29 = 43,加法本体在 C++ 的 add.cpp 里执行
注意一个容易忽略的细节:SpinBox 上的「+ / −」只改界面上的数,不会触发求和。只有点⑥,数值才会通过 setOperandA/B 交给 C++。这正是「QML 管交互、C++ 管计算」的分工边界。
1. 环境准备与三步跑起来
| 项目 | 版本 / 说明 |
|---|---|
| Qt | 6.11.2(最低要求 6.10,qt_standard_project_setup(REQUIRES 6.10)) |
| 编译器 | MSVC 2022 64-bit(项目里同名构建目录 Desktop_Qt_6_11_2_MSVC2022_64bit_Release) |
| 构建 | CMake 3.16+,Qt Creator 直接打开 CMakeLists.txt 亦可 |
| Qt 模块 | Qt6::Quick,QML 侧另用到 QtQuick.VirtualKeyboard |
命令行构建(把 CMAKE_PREFIX_PATH 换成自己的 Qt 安装路径):
cmake -S . -B build -DCMAKE_PREFIX_PATH=<Qt安装路径>/6.11.2/msvc2022_64
cmake --build build --config Release
.\build\Release\appQtQuick3D.exe
用 Qt Creator 更省事:打开 CMakeLists.txt → 选择套件 Desktop Qt 6.11.2 MSVC2022 64bit → Ctrl+R。环境变量与运行库路径由 IDE 自动配置。
调试提示:CMakeLists.txt 里设了 WIN32_EXECUTABLE TRUE,Windows 下不弹控制台。需要直接看 qDebug() 输出时,可临时改成 FALSE,或者在 Qt Creator 的「应用程序输出」面板里看。
2. 工程结构与整体架构
项目很小,7 个源文件 + 一个可选的设计导入目录,正好适合当教学样例:
| 文件 | 职责 | 关联方式 |
|---|---|---|
main.cpp |
创建 QGuiApplication / QQmlApplicationEngine,注入 Backend,按模块加载 Main.qml |
方式一 |
Main.qml |
界面主体,import QtQuick3DDemo 后实例化 ADD,绑定属性、调用后端方法 |
方式一 / 二 |
backend.h / backend.cpp |
Backend 类:维护背景色列表,暴露只读属性 backgroundColor |
方式一 |
add.h / add.cpp |
ADD 类:QML_ELEMENT 注册为 QML 类型,暴露两个加数与求和结果 |
方式二 |
CMakeLists.txt |
qt_add_executable 收 C++ 源文件,qt_add_qml_module 声明 QML 模块 |
共用 |
importedcontent/ |
Figma 等设计工具导出的内容,目录内有 CMakeLists.txt 时会被自动 add_subdirectory |
可选 |
把上面这张表画成图,就是本文的核心骨架:

图 2-1 三层结构 + 两条桥:橙色为方式一,绿色为方式二
从图里可以抽出混合编程必须解决的三个问题,后面所有代码都是在回答它们:
| 核心问题 | 本项目用的机制 | 对应代码 |
|---|---|---|
| 暴露:C++ 对象如何进入 QML 环境 | 方式一 setContextProperty;方式二 QML_ELEMENT + qt_add_qml_module |
main.cpp / add.h |
| 调用:QML 如何把用户操作回传 C++ | Q_INVOKABLE 方法(也可用 public slots) |
backend.toggleBackground()、ADD::setOperandA/B() |
| 通知:C++ 数据变了界面如何刷新 | Q_PROPERTY(...) + NOTIFY 信号,QML 侧属性绑定自动订阅 |
backgroundColorChanged()、sumChanged() |
3. 方式一:setContextProperty 上下文属性注入(Backend)
一句话概括:在 main.cpp 里把一个 C++ 对象塞进 QML 根上下文,取个名字 backend,此后 QML 任何地方都能直接用这个名字。它像一个运行时全局变量 —— 不用 import、不用注册类型、不用改 CMake,改动量最小,代价也最明显。
3.1 后端类声明:完整 backend.h
三个关键宏凑齐了「可读属性 + 可调用方法 + 变更通知」:
#ifndef BACKEND_H
#define BACKEND_H
#include <QColor>
#include <QList>
#include <QObject>
// 界面后端类:负责主界面背景色切换,QML 绑定 backgroundColor 自动更新
class Backend : public QObject
{
Q_OBJECT
Q_PROPERTY(QColor backgroundColor READ backgroundColor NOTIFY backgroundColorChanged)
public:
explicit Backend(QObject *parent = nullptr);
QColor backgroundColor() const; // 当前主界面背景色
Q_INVOKABLE void toggleBackground(); // 切换到下一种背景色( Q_INVOKABLE 关键字 QML 按钮调用)
signals:
void backgroundColorChanged(); // 背景色变化时通知 QML
private:
QList<QColor> m_colors; // 背景色候选列表
int m_colorIndex = 0; // 当前颜色在列表中的下标
};
#endif // BACKEND_H
注意 Q_PROPERTY 只写了 READ 和 NOTIFY,没有 WRITE —— 这是个QML 侧只读属性:界面只能绑定它,不能赋值;要改只能通过 toggleBackground()。这是很实用的封装手法。
3.2 实现:完整 backend.cpp
#include "backend.h"
// 构造:准备几组浅色背景,保证界面上深色文字清晰可读
Backend::Backend(QObject *parent)
: QObject(parent)
{
m_colors = {
QColor("#eceff1"), // 蓝灰
QColor("#ffe082"), // 琥珀
QColor("#b2dfdb"), // 青绿
QColor("#d1c4e9"), // 淡紫
QColor("#f8bbd0") // 淡粉
};
}
// 返回当前背景色(Q_PROPERTY backgroundColor 的 READ)
QColor Backend::backgroundColor() const
{
return m_colors.isEmpty() ? QColor("#eceff1") : m_colors.at(m_colorIndex);
}
// 每调用一次就切到下一种背景色,并通过信号让 QML 界面自动更新
void Backend::toggleBackground()
{
if (m_colors.isEmpty())
return;
m_colorIndex = (m_colorIndex + 1) % m_colors.size();
// QML 读取属性时,引擎通过元对象系统把该属性的 notify 信号(xxxChanged)连到一个内部回调上,
// emit 触发信号同步回调,引擎据此把依赖它的绑定标记为脏并重新求值
// ——所以根本不是 QML 有“对应槽函数”,而是引擎自动建立了一次隐式连接。
emit backgroundColorChanged();
}
emit backgroundColorChanged() 是整套机制的开关。C++ 里没有任何一行代码去碰 QML 对象,它只负责说「我变了」,剩下的是 QML 引擎的事。源码里那段注释把这件事解释得很到位:不是 QML 有对应槽函数,而是绑定建立时引擎隐式订阅了 NOTIFY 信号。
3.3 入口:完整 main.cpp
#include <QGuiApplication> // 引入 QGuiApplication:Qt Quick 程序使用的 GUI 应用基类
#include <QQmlApplicationEngine> // 引入 QQmlApplicationEngine:用于加载和执行 QML 的引擎类
#include <QQmlContext> // 引入 QQmlContext:用于把 C++ 后端对象注册到 QML 上下文
// 注意:这里不再包含 add.h——ADD 采用“方式二”注册为 QML 类型,由 Main.qml 自行实例化
#include "backend.h" // 引入界面后端类 Backend(方式一:上下文属性,负责背景色切换)
// main 为程序入口函数,argc 是命令行参数个数,argv 是参数字符串数组
int main(int argc, char *argv[])
{
// main 函数体开始
// 设置输入法模块为 Qt 虚拟键盘,用于无系统输入法的触摸/嵌入式设备
qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));
// 创建 GUI 应用程序对象(Qt Quick 界面程序应使用 QGuiApplication)
QGuiApplication app(argc, argv);
// 方式一:创建 Backend 对象,并通过 setContextProperty 暴露给 QML 使用
// 注意声明顺序:局部对象按“声明逆序”销毁。backend 声明在 engine 之前,
// 退出时 engine(连同其中的 QML 场景)先销毁、backend 后销毁;
// 若顺序反过来,backend 会先被销毁而 QML 仍持有它的引用,
// 退出时就会报 TypeError: Cannot read property 'backgroundColor' of null。
Backend backend;
// 创建 QML 应用引擎,负责解析、实例化并运行 QML 场景
QQmlApplicationEngine engine;
engine.rootContext()->setContextProperty("backend", &backend);
// 将引擎的“对象创建失败”信号与退出处理逻辑建立连接
QObject::connect(
&engine, // 信号发送者:QML 引擎对象
&QQmlApplicationEngine::objectCreationFailed, // 信号:QML 加载或创建对象失败时触发
&app, // 信号接收者:应用程序对象
[]() {
QCoreApplication::exit(-1); }, // 槽函数:创建失败则使程序以退出码 -1 结束
Qt::QueuedConnection); // 以队列方式连接,跨线程安全地投递信号
// 从 QtQuick3DDemo 模块加载名为 Main 的 QML 文件作为应用主界面
engine.loadFromModule("QtQuick3DDemo", "Main");
// 进入 Qt 事件循环并阻塞运行,程序退出时返回其退出码
return QGuiApplication::exec();
} // main 函数体结束
两个点值得单独圈出来:
3.4 QML 侧:读属性 + 调方法
Rectangle {
id: backgroundLayer
anchors.fill: parent
// 方式一注入的对象静态检查识别不到,这里关闭 unqualified 提示
// qmllint disable unqualified
color: backend.backgroundColor // 绑定:信号一到自动重算
// qmllint enable unqualified
}
Button {
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("切换背景色(C++ 后端)")
// 同上:backend 来自方式一的上下文注入
// qmllint disable unqualified
onClicked: backend.toggleBackground()
// qmllint enable unqualified
}
backend 是运行时才出现的名字,qmllint 做静态分析时看不见它,会报 unqualified 警告。项目用 // qmllint disable unqualified / enable 成对注释局部关掉 —— 这本身就是方式一「缺少类型信息」的直接证据。
3.5 方式一小结
| 优点 | 代价 |
|---|---|
改动最小:只动 main.cpp,不用改 CMake、不用 import |
只有一个字符串名字,拼错只能在运行时发现 |
| 适合快速暴露已有的单例、全局服务、遗留代码 | QML 侧无类型信息:qmllint、自动补全、跳转、qmlcachegen 全都用不上 |
| 对旧项目迁移友好 | 生命周期完全由 C++ 调用者负责,退出时极易踩悬空引用(见第 8 节) |
4. 方式二:QML_ELEMENT 类型注册(ADD,Qt 6 推荐)
思路完全不同:不注入对象,而是注册类型。C++ 类变成 QML 里的一等公民,QML 自己 ADD { } 实例化,谁用谁创建,生命周期跟着 QML 对象树走。
4.1 类型声明:完整 add.h
#ifndef ADD_H
#define ADD_H
#include <QObject>
#include <QtQml/qqmlregistration.h> // QML_ELEMENT 所在头文件(方式二需要)
// 方式二示例:ADD 通过 QML_ELEMENT 注册成 QtQuick3DDemo 模块的 QML 类型,
// 无需在 main.cpp 里 setContextProperty,Main.qml 中可直接写 ADD {
} 实例化。
class ADD : public QObject
{
Q_OBJECT
QML_ELEMENT // 注册为当前 QML 模块中的类型(方式二的核心标志)
Q_PROPERTY(int operandA READ operandA WRITE setOperandA NOTIFY operandAChanged)
Q_PROPERTY(int operandB READ operandB WRITE setOperandB NOTIFY operandBChanged)
Q_PROPERTY(int sum READ sum NOTIFY sumChanged)
public:
explicit ADD(QObject *parent = nullptr);
int operandA() const; // 第一个加数
int operandB() const; // 第二个加数
int sum() const; // 两数之和(C++ 计算出的结果)
Q_INVOKABLE void setOperandA(int a); // QML 写入加数 A
Q_INVOKABLE void setOperandB(int b); // QML 写入加数 B
signals:
void operandAChanged(); // 加数 A 变化时通知 QML
void operandBChanged(); // 加数 B 变化时通知 QML
void sumChanged(); // 求和结果变化时通知 QML(界面自动刷新)
private:
void recomputeSum(); // 加法运算本体:a + b
int m_operandA = 12; // 加数 A 的初始值
int m_operandB = 30; // 加数 B 的初始值
int m_sum = 0; // 求和结果
};
#endif // ADD_H
与 Backend 对照着看:operandA / operandB 有 WRITE(QML 可写),sum 只有 READ(只读,由 C++ 算出)。只读属性照样能被 QML 绑定,这是新手常问的点。
4.2 实现:完整 add.cpp
#include "add.h"
// 构造:先算一次初始和 12 + 30 = 42
ADD::ADD(QObject *parent)
: QObject(parent)
{
recomputeSum();
}
// 返回第一个加数(Q_PROPERTY operandA 的 READ)
int ADD::operandA() const
{
return m_operandA;
}
// 返回第二个加数(Q_PROPERTY operandB 的 READ)
int ADD::operandB() const
{
return m_operandB;
}
// 返回 C++ 计算出的两数之和(Q_PROPERTY sum 的 READ)
int ADD::sum() const
{
return m_sum;
}
// QML 写入第一个加数:保存值、重新求和并发出信号
void ADD::setOperandA(int a)
{
if (m_operandA == a)
return;
m_operandA = a;
emit operandAChanged();
recomputeSum();
}
// QML 写入第二个加数:保存值、重新求和并发出信号
void ADD::setOperandB(int b)
{
if (m_operandB == b)
return;
m_operandB = b;
emit operandBChanged();
recomputeSum();
}
// 加法运算本体(在 C++ 后端执行):sum = a + b
void ADD::recomputeSum()
{
const int newSum = m_operandA + m_operandB;
if (m_sum == newSum)
return;
m_sum = newSum;
emit sumChanged(); // 通知 QML:结果已更新,请刷新显示
}
setOperandX 里那句 if (m_operandA == a) return; 和 recomputeSum() 里的 if (m_sum == newSum) return; 不是可有可无的洁癖:同值不发信号,能避免高频数据下无意义的绑定重算。做工业采集上位机时,这一句能省下大量无效刷新。
4.3 CMake 配置:qt_add_qml_module
方式二真正「连起来」的地方在构建脚本,关键是 qt_add_executable 与 qt_add_qml_module 使用同一个 target 名:
qt_add_executable(appQtQuick3D
main.cpp
backend.h # 方式一:Backend(main.cpp 中用 setContextProperty 暴露)
backend.cpp
add.h # 方式二:ADD(add.h 中含 QML_ELEMENT,注册为模块 QML 类型)
add.cpp
)
qt_add_qml_module(appQtQuick3D
URI QtQuick3DDemo
QML_FILES
Main.qml
)
add.h 被列进 qt_add_executable,moc 才能扫到 QML_ELEMENT 并把类型登记进 QtQuick3DDemo 模块。完整 CMakeLists.txt 见附录 B。
四个名字必须对得上,错一个就报「类型找不到」:
| 位置 | 值 | 作用 |
|---|---|---|
qt_add_qml_module(... URI ...) |
QtQuick3DDemo |
模块 URI |
Main.qml 头部 |
import QtQuick3DDemo |
QML 侧导入该模块 |
engine.loadFromModule(...) 第 1 个参数 |
"QtQuick3DDemo" |
运行时按模块定位 |
engine.loadFromModule(...) 第 2 个参数 |
"Main" |
对应 QML_FILES 里的 Main.qml |
4.4 QML 侧:实例化 + 调用 + 绑定
import QtQuick3DDemo // 导入本项目 QML 模块:C++ 类型 ADD 就注册在这里(方式二)
ApplicationWindow {
// ... 窗口属性略 ...
// 方式二:ADD 已用 QML_ELEMENT 注册为 QML 类型,直接实例化
ADD {
id: addCalc
}
}
// QML → C++:调用 Q_INVOKABLE 方法,把两个数交给 C++ 求和
Button {
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("C++ 后端求和")
onClicked: {
addCalc.setOperandA(aBox.value)
addCalc.setOperandB(bBox.value)
}
}
// C++ → QML:文本绑定 ADD 实例属性 sum,C++ 重算后通过信号自动刷新
Text {
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("%1 + %2 = %3").arg(addCalc.operandA).arg(addCalc.operandB).arg(addCalc.sum)
font.pixelSize: 28
font.bold: true
color: "#263238"
}
没有 setText,没有 update(),没有 refresh()。绑定表达式 text: ...addCalc.sum 建立时,引擎就订阅了 sumChanged;C++ 一发信号,表达式重算,界面更新。
4.5 方式二小结
| 优点 | 代价 |
|---|---|
QML 侧有完整类型信息:qmllint、补全、跳转、编译期检查、qmlcachegen 全可用 |
QML_ELEMENT + qt_add_qml_module + import 三者缺一不可,配置要对 |
| 生命周期由 QML 对象树托管,退出时不会悬空 | 类型对模块内所有 QML 可见,需要靠命名规范避免歧义 |
| Qt 6 官方推荐,也是 Qt Creator / Design Studio 模板生成的形态 | 对只想「快速露出一个全局对象」的场景略重 |
5. 一次点击的完整链路:数据是怎么流回去的
把第 4 节的代码串成一条时间线,就是下面这张图:

图 5-1 以「改成 14 和 29 后点击求和」为例的六步调用链
配合源码对照着看,链路是:
// ① ② Main.qml:用户改 SpinBox,点击按钮
onClicked: {
addCalc.setOperandA(aBox.value) // 14
addCalc.setOperandB(bBox.value) // 29
}
// ③ ④ add.cpp:C++ 保存、重算、发信号
void ADD::recomputeSum()
{
const int newSum = m_operandA + m_operandB; // 43
if (m_sum == newSum) return;
m_sum = newSum;
emit sumChanged(); // 唯一的「通知」动作
}
// ⑤ ⑥ Main.qml:引擎隐式重算绑定,Text 自动显示 14 + 29 = 43
text: qsTr("%1 + %2 = %3").arg(addCalc.operandA).arg(addCalc.operandB).arg(addCalc.sum)
三条必须记住的机制:
6. 界面细节:虚拟键盘(给触摸屏 / 嵌入式场景)
点击 SpinBox 的输入区会弹出数字键盘,这在 RK3568 这类没有系统输入法的触摸屏设备上很关键:

图 6-1 虚拟键盘由 Qt VirtualKeyboard 提供,加数已改为 14 和 29
启用只需两处配合。C++ 侧在 QGuiApplication 创建之前设置输入法模块:
// main.cpp
qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));
QGuiApplication app(argc, argv);
QML 侧放一个 InputPanel,用状态机控制它从窗口底部滑入滑出:
import QtQuick.VirtualKeyboard
InputPanel {
// 虚拟键盘输入面板
id: inputPanel
z: 99 // 始终显示在最上层
y: window.height // 初始在窗口之外(隐藏)
width: window.width // 宽度跟随窗口
states: State {
name: "visible"
when: inputPanel.active // 激活时自动进入该状态
PropertyChanges {
inputPanel.y: window.height - inputPanel.height // 上移到窗口底部
}
}
transitions: Transition {
from: ""
to: "visible"
reversible: true // 收起时反向播放
NumberAnimation {
properties: "y"
easing.type: Easing.InOutQuad
}
}
}
如果键盘不弹,按顺序查三样:QT_IM_MODULE 是否在 QGuiApplication 之前设置、Qt 安装里是否有 VirtualKeyboard 模块、InputPanel 是否放在 ApplicationWindow 内部且 z 足够大。
7. 背景色切换:C++ → QML 的最短闭环
点一次「切换背景色」,背景从蓝灰变琥珀;再点一次变青绿:

图 7-1 第一次点击:#ffe082 琥珀

图 7-2 第二次点击:#b2dfdb 青绿
颜色循环完全由 C++ 维护,QML 只绑了一个属性:
// backend.cpp:只改下标 + 发信号
m_colorIndex = (m_colorIndex + 1) % m_colors.size();
emit backgroundColorChanged();
// Main.qml:只绑属性
color: backend.backgroundColor
五组颜色 #eceff1 → #ffe082 → #b2dfdb → #d1c4e9 → #f8bbd0 → 循环,都是浅色,保证深色文字始终可读。这是方式一最直观的演示:C++ 里没有任何 UI 代码,界面却自己变了。
8. 踩坑实录:退出时 TypeError: Cannot read property 'backgroundColor' of null
这个项目在早期版本关闭窗口时会打印一条错误:
qrc:/qt/qml/QtQuick3DDemo/Main.qml:30: TypeError: Cannot read property 'backgroundColor' of null
它不影响程序退出,很容易被当成「Qt 的小毛病」忽略,但它反映的是真实的对象生命周期设计问题。

图 8-1 局部对象按声明逆序析构,左为错误写法,右为修复后写法
8.1 原因
报错行正是 color: backend.backgroundColor。关闭窗口后 main() 开始析构局部对象,而析构顺序与声明顺序相反。原来的写法是:
QGuiApplication app(argc, argv);
QQmlApplicationEngine engine; // 先声明 → 后析构
Backend backend; // 后声明 → 先析构
engine.rootContext()->setContextProperty("backend", &backend);
于是 backend 先被销毁,engine 后销毁。引擎析构 QML 场景时还会再次求值绑定,此时上下文属性指向的对象已经没了,Qt 返回空对象,读属性自然报 null。
8.2 修复
让被注入的对象比引擎活得久 —— 把 Backend 声明挪到引擎之前(这正是现在 main.cpp 里的写法):
QGuiApplication app(argc, argv);
Backend backend; // 先声明 → 后析构,比引擎活得久
QQmlApplicationEngine engine; // 后声明 → 先析构
engine.rootContext()->setContextProperty("backend", &backend);
等价的另一种写法是把对象挂到 app 上(app 是最后一个被销毁的对象):
auto *backend = new Backend(&app);
engine.rootContext()->setContextProperty("backend", backend);
给绑定加空值保护 color: backend ? backend.backgroundColor : "#eceff1" 也能消掉报错,但那只是掩盖症状,不推荐当修复方案。
8.3 推广到自己的项目
- · 凡是走
setContextProperty注入的 C++ 对象,都要确认它的生命周期覆盖QQmlApplicationEngine。 - · 同类症状还有
Cannot read property 'x' of undefined,多半也是对象提前失效,而不是属性名写错。 - · 方式二不存在这个问题:
ADD由 QML 实例化,随 QML 对象树一起销毁,顺序由引擎保证。这也是推荐新代码优先用类型注册的现实理由之一。
9. 两种方式怎么选
| 对比维度 | 方式一:上下文属性 | 方式二:QML 类型注册 |
|---|---|---|
| 暴露方式 | setContextProperty("backend", &backend) |
类声明加 QML_ELEMENT,编译进 QML 模块 |
| QML 侧使用 | 直接写 backend.backgroundColor |
先 import QtQuick3DDemo,再 ADD { } |
| 类型信息 | 无,仅字符串名字 | 完整,有 qmltypes 描述文件 |
| 静态检查 | qmllint 报 unqualified,需注释屏蔽 |
补全、跳转、编译期检查可用 |
| 生命周期 | 由 C++ 调用者保证,易悬空 | 由 QML 对象树保证 |
| 改动成本 | 仅需修改 main.cpp |
需要正确的 CMake 模块配置 |
| 适用场景 | 快速暴露已有单例、全局服务、遗留代码 | 新建可复用组件、正式项目 |
选型建议:新代码默认选方式二,它把生命周期管理与类型检查都交给框架;只有当必须暴露一个已存在的全局对象、且不愿意为它建模块时,才用方式一。本项目同时保留两者只是为了对照演示,实际项目建议选定一种并贯穿始终,别在一个工程里混着写。
10. 编码约定 Checklist
写任何暴露给 QML 的 C++ 类,按这张表自查:
| # | 约定 | 原因 |
|---|---|---|
| 1 | 类继承 QObject 并写 Q_OBJECT |
元对象系统是所有桥接机制的基础 |
| 2 | 属性一律提供 NOTIFY 信号 |
否则 QML 绑定不会刷新,且不报错 |
| 3 | setter 先比较再发信号 | 避免无意义的重复刷新 |
| 4 | 值真正变化时才 emit |
同上,recomputeSum() 是范例 |
| 5 | 暴露给 QML 的方法加 Q_INVOKABLE 或放进 public slots |
否则 QML 调不到 |
| 6 | 参数/返回值用 QML 原生支持的类型 | int / double / QString / QColor / QVariant |
| 7 | 指针要么由 QML 实例化,要么生命周期长于引擎 | 见第 8 节 |
| 8 | 不在 C++ 工作线程里直接改 QML 属性 | 跨线程走信号槽(默认队列连接) |
| 9 | C++ 不反向持有 / 查找 QML 对象 | 保持解耦,靠绑定单向流动 |
| 10 | 模块 URI、import、loadFromModule 三处一致 |
见 4.3 节对照表 |
11. 常见问题 FAQ
| 现象 | 常见原因 | 处理 |
|---|---|---|
module "QtQuick3DDemo" is not installed |
用了 engine.load(QUrl(...)) 传统路径加载,或 Main.qml 没列进 QML_FILES |
改用 engine.loadFromModule("QtQuick3DDemo", "Main"),确认 qt_add_qml_module 配置 |
ADD is not a type |
漏 QML_ELEMENT / 漏 #include <QtQml/qqmlregistration.h> / add.h 没进 qt_add_executable / 漏 import QtQuick3DDemo / URI 拼错 |
按 4.3 节四项逐一核对,改完执行 CMake 重新配置(让 moc 重跑) |
| C++ 里数值改了,界面不刷新 | Q_PROPERTY 漏 NOTIFY,或改值后没 emit |
补 NOTIFY 信号并在值变化时发出 |
qmllint: unqualified access |
方式一注入的上下文属性没有类型信息 | 用 // qmllint disable unqualified 局部关闭,或改用方式二 |
双击 exe 提示缺 Qt6Core.dll 等 |
Qt 运行库不在搜索路径 | 用 windeployqt 部署,或把 Qt 的 bin 加入 PATH;Qt Creator 里运行无此问题 |
关闭窗口报 Cannot read property ... of null |
上下文属性对象先于引擎析构 | 调整声明顺序,见第 8 节 |
| 虚拟键盘不弹出 | QT_IM_MODULE 设置太晚 / 缺 VirtualKeyboard 模块 / InputPanel 层级不对 |
见第 6 节提示 |
看不到 qDebug() 输出 |
WIN32_EXECUTABLE TRUE 关掉了控制台 |
临时改 FALSE,或看 Qt Creator 应用程序输出 |
12. 小结
把全文压缩成四句话:
这个 Demo 的价值不在「加法」和「换背景」,而在于把两条通路的差异摆在同一个窗口里:左边一行 setContextProperty,右边一个 QML_ELEMENT,剩下的属性绑定机制完全共用。看懂这个对照,再去看 Qt 官方的 QML_SINGLETON、QML_NAMED_ELEMENT、qmlRegisterType 就都是同一个套路了。
附录 A:Main.qml 完整源码
import QtQuick // 导入 QtQuick 核心模块,提供 QML 基础类型
import QtQuick.Controls.Basic // 导入 QtQuick 基础样式控件模块(SpinBox/Button 等)
import QtQuick3DDemo // 导入本项目 QML 模块:C++ 类型 ADD 就注册在这里(方式二)
import QtQuick.VirtualKeyboard // 导入 QtQuick 虚拟键盘模块,用于软键盘输入
ApplicationWindow {
// 应用主窗口,自带标题栏与窗口管理功能
id: window // 窗口对象 id,便于内部组件相互引用
width: 640 // 窗口初始宽度(像素)
height: 480 // 窗口初始高度(像素)
minimumWidth: 200 // 窗口可调整的最小宽度,防止界面被压缩变形
minimumHeight: 250 // 窗口可调整的最小高度
visible: true // 窗口在程序启动后立即可见
title: qsTr("QML + C++ 后端示例(两种桥接方式)") // 窗口标题文本,qsTr 包裹后便于多语言翻译
// 方式二:ADD 已用 QML_ELEMENT 注册为 QtQuick3DDemo 模块的 QML 类型(见 add.h),
// 不需要 C++ 侧 setContextProperty,直接在 QML 中实例化即可使用
ADD {
id: addCalc // ADD 对象实例:加法计算在 C++ 后端执行
}
// 方式一:backend 由 main.cpp 通过 setContextProperty("backend", ...) 注入上下文
// 背景层:颜色绑定 C++ 后端 Backend 的 backgroundColor 属性(C++ → QML)
Rectangle {
id: backgroundLayer
anchors.fill: parent
// 方式一注入的对象静态检查识别不到,这里关闭 unqualified 提示
// qmllint disable unqualified
color: backend.backgroundColor // 后端切换颜色后这里自动刷新
// qmllint enable unqualified
}
// 主示例区:输入两个加数 → 点击按钮 → C++ 后端求和 → 结果自动更新
Column {
anchors.centerIn: parent
spacing: 18
Text {
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("QML 界面 + C++ 后端示例") // 标题文字
font.pixelSize: 22
color: "#37474f"
}
Text {
// 说明两种桥接方式的小字提示
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("求和 = 方式二(ADD, QML类型注册) 背景 = 方式一(Backend, 上下文属性)")
font.pixelSize: 12
color: "#607d8b"
}
Row {
anchors.horizontalCenter: parent.horizontalCenter
spacing: 12
// 第一个加数输入框(可用虚拟键盘直接输入数字)
SpinBox {
id: aBox
from: -999
to: 999
value: 12
editable: true
}
Text {
text: "+"
anchors.verticalCenter: parent.verticalCenter
font.pixelSize: 24
color: "#455a64"
}
// 第二个加数输入框
SpinBox {
id: bBox
from: -999
to: 999
value: 30
editable: true
}
}
// QML → C++:调用方式二创建的 ADD 实例方法,把两个数交给 C++ 求和
Button {
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("C++ 后端求和")
onClicked: {
addCalc.setOperandA(aBox.value)
addCalc.setOperandB(bBox.value)
}
}
// C++ → QML:文本绑定 ADD 实例属性 sum,C++ 重算后通过信号自动刷新
Text {
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("%1 + %2 = %3").arg(addCalc.operandA).arg(addCalc.operandB).arg(addCalc.sum)
font.pixelSize: 28
font.bold: true
color: "#263238"
}
// QML → C++:调用方式一的 backend 对象方法,切换主界面背景色
Button {
anchors.horizontalCenter: parent.horizontalCenter
text: qsTr("切换背景色(C++ 后端)")
// 同上:backend 来自方式一的上下文注入
// qmllint disable unqualified
onClicked: backend.toggleBackground()
// qmllint enable unqualified
}
}
InputPanel {
// 虚拟键盘输入面板,负责键盘的显示与隐藏
id: inputPanel // 键盘面板对象 id
z: 99 // 将层级设为 99,让键盘始终显示在最上层
y: window.height // 初始 y 位于窗口底部之外,使键盘处于隐藏状态
width: window.width // 键盘宽度始终跟随窗口宽度
states: State {
// 为键盘面板声明状态,控制面板的位置
name: "visible" // 状态名称:visible(键盘可见)
when: inputPanel.active // 当键盘被激活时,自动进入该状态
PropertyChanges {
// 状态切换时需要修改的属性列表
inputPanel.y: window.height - inputPanel.height // 将键盘上移到窗口底部,即键盘完全显示的位置
}
}
transitions: Transition {
// 定义状态切换时播放的过渡动画
from: "" // 动画起始状态:空状态(初始/隐藏)
to: "visible" // 动画目标状态:visible(可见)
reversible: true // 允许反向播放,键盘收起时动画同样生效
NumberAnimation {
// 数值动画:让属性值连续平滑变化
properties: "y" // 动画作用的属性为 y(垂直位置)
easing.type: Easing.InOutQuad // 缓动曲线:二次缓入缓出,运动更柔和自然
}
}
}
}
附录 B:CMakeLists.txt 完整源码
cmake_minimum_required(VERSION 3.16)
project(QtQuick3D VERSION 0.1 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Quick)
qt_standard_project_setup(REQUIRES 6.10)
# Content of downloaded design from Figma to Qt or similar
if (EXISTS "${CMAKE_CURRENT_LIST_DIR}/importedcontent/CMakeLists.txt")
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/importedcontent)
endif()
# ===== C++ 与 QML 两种桥接方式示例 =====
# 方式一(上下文属性):Backend 在 main.cpp 中创建,
# 再通过 engine.rootContext()->setContextProperty("backend", ...) 注入 QML,改动最小。
# 方式二(QML 类型注册,Qt 6 推荐):ADD 在 add.h 中用 QML_ELEMENT 宏注册,
# 并编译进下方 qt_add_qml_module 定义的 QtQuick3DDemo 模块,Main.qml 中可直接 ADD { } 实例化。
qt_add_executable(appQtQuick3D
main.cpp
backend.h # 方式一:Backend(main.cpp 中用 setContextProperty 暴露)
backend.cpp
add.h # 方式二:ADD(add.h 中含 QML_ELEMENT,注册为模块 QML 类型)
add.cpp
)
qt_add_qml_module(appQtQuick3D
URI QtQuick3DDemo
QML_FILES
Main.qml
)
# Qt for iOS sets MACOSX_BUNDLE_GUI_IDENTIFIER automatically since Qt 6.1.
# If you are developing for iOS or macOS you should consider setting an
# explicit, fixed bundle identifier manually though.
set_target_properties(appQtQuick3D PROPERTIES
# MACOSX_BUNDLE_GUI_IDENTIFIER com.example.appQtQuick3D
MACOSX_BUNDLE_BUNDLE_VERSION ${PROJECT_VERSION}
MACOSX_BUNDLE_SHORT_VERSION_STRING ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}
MACOSX_BUNDLE TRUE
WIN32_EXECUTABLE TRUE
)
target_link_libraries(appQtQuick3D
PRIVATE Qt6::Quick
)
install(TARGETS appQtQuick3D
BUNDLE DESTINATION .
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)
几个容易忽略的点:qt_standard_project_setup(REQUIRES 6.10) 开启现代 QML 模块所需默认设置;两个 qt_add_* 必须用同一个 target 名,类型才会落到同一模块;WIN32_EXECUTABLE TRUE 让 Windows 下不弹控制台,调试时可临时改 FALSE;importedcontent/ 里若有 CMakeLists.txt 会被自动加入构建。
写在最后
通过网盘分享的文件:QTC++&QML学习混合.rar
链接: https://pan.baidu.com/s/1HIU29yFPeNIWoH2E3IwdXw?pwd=2026 提取码: 2026