Qt 6 实战:一个 Demo 讲透 C++ 与 QML 混合编程的两种桥接方式(附完整源码)

简介: 本文以Qt Quick3DDemo示例,直观对比C++与QML交互的两种核心桥接方式:`setContextProperty`(上下文属性)与`QML_ELEMENT`(类型注册)。通过同一窗口并行实现求和(方式二)与背景切换(方式一),详解对象暴露、方法回调、数据自动刷新三大关键问题。代码均来自真实可运行项目,适配Qt 6.11.2,助力Quick新手跨越QWidget迁移门槛。(239字)

导读: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

相关文章
|
8天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
9443 25
|
8天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
2732 14
|
3天前
|
人工智能 安全 应用服务中间件
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行
NGINX曝出两个高危漏洞(CVE-2026-123633和CVE-2026-123007),CVSS 9.2分,均属HTTP/2内存安全缺陷,无需认证即可远程执行代码。影响自2015年起的多个版本,静态站点亦受威胁。修复版本为开源版1.30.7/1.31.9。(239字)
1310 0
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行
|
6天前
|
传感器 安全 区块链
Windows 电脑运行安卓应用教程:开源工具 ApkStart 双击 APK 即装、独立窗口运行
ApkStart 是一款开源Windows工具,让安卓APP像原生软件一样运行:双击APK即安装、生成真实图标、独立窗口启动、开始菜单可搜索。无需传统模拟器,内置QEMU运行时,支持数据互通、ARM兼容与命令行操作。(239字)
|
11天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
11天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
23天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
11430 59
|
6天前
|
人工智能 弹性计算 开发工具
零成本玩各大模型!DeepSeek Harness dsh-our-free-model 插件,13 个厂商模型直接用
总结一下:装这个插件,你不用注册、不用绑卡、不用填一个 Key,就能在 DeepSeek Harness 里用上 DeepSeek V4.1 Flash、Kimi K3 这一批前沿模型,而且是白嫖的、还不限量。三步搞定:下载插件,复制包含 `package.json` 的插件目录路径,在「添加插件」里粘贴路径安装并重启。无论是在阿里云 ECS 上通过命令行部署的 Web 版,还是本地的 Electron 桌面端,都能顺利跑通,快速搭建一套零成本的免费模型使用环境。
1374 1
|
4天前
|
人工智能 弹性计算 IDE
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
适合团队落地代码规范,每次提交自动生成评审报告,降低人工CR工作量。同时支持自定义技能脚本,接入团队内部SDK说明文档,让Codex生成符合团队编码规范的代码。Codex三大客户端覆盖本地开发、服务器远程编码、自动化流水线场景,搭配阿里云百炼的Token Plan、Coding Plan,能够低成本搭建稳定可控的AI编码助手。新手建议先从IDE插件入手,熟悉交互逻辑,再尝试CLI版本部署在阿里云ECS,实现云上项目远程编码、批量脚本处理。只要按照步骤完成环境准备、版本选型、密钥对接、项目初始化,就可以把Codex融入日常开发流程,大幅提升代码编写、问题排查、项目重构的效率。
955 0
|
9天前
|
Linux API iOS开发
【DSH】DeepSeek Harness新手保姆教程(下载+安装+配置+使用,2026最新实测)
DeepSeek Harness(dsh)是DeepSeek AI开源的智能体框架,秉持“一切皆插件”理念,支持读文件、改代码、跑命令、处理表格、联网搜索等操作。免费开源,兼容Windows/macOS/Linux,提供桌面端与网页端,可灵活安装插件扩展能力。

热门文章

最新文章