Qt Quick中调用C++函数必须用Q_INVOKABLE、public slots或signal标记，否则QML调用静默失败返回undefined；跨线程操作需分离GUI与非GUI任务，大数据传递应避免QVariant改用QQuickImageProvider或共享内存。
Qt Quick 里调用 C++ 对象必须用 Q_INVOKABLE 或信号槽
直接暴露普通成员函数给 QML 会失败，QML 引擎只认 Q_INVOKABLE 标记的函数、public slots 或 signal。不加标记的函数在 QML 中调用时静默失败，控制台无报错，但 JS 侧拿到 undefined —— 这是最常被忽略的“黑盒”问题。
实操建议：
- 在 C++ 类中继承
QObject，并用Q_OBJECT宏 - 需要被 QML 调用的函数前必须加
Q_INVOKABLE，比如：Q_INVOKABLE void processImage(const QString &path) - 避免返回裸指针或栈对象引用；返回
QVariant、QList或已注册的Q_GADGET更安全 - 若函数耗时超过 10ms，别在主线程同步调用，否则 QML 渲染卡顿——后面会说到怎么拆出去
C++ 向 QML 推送数据：优先用信号，别轮询或定时器
常见错误是让 QML 每 100ms 调一次 C++ 的 getData() 函数查状态，这不仅浪费 CPU，还容易因线程不同步导致读取到中间态数据。Qt 的信号机制天然线程安全（配合 QueuedConnection），且 QML 自动绑定响应，延迟低、无冗余调用。
实操建议：
- 在 C++ 类中定义信号，如：
void frameReady(const QByteArray &data, int width, int height) - 在 QML 中用
Connections监听：Connections { target: myCppObj; onFrameReady: { /* 处理帧 */ } } - 跨线程发信号时，确保连接类型是
Qt.QueuedConnection（默认行为通常满足，但显式写更稳） - 避免高频信号塞满事件队列：对视频流这类场景，用
QMetaObject::invokeMethod(..., Qt.QueuedConnection)做节流，或在 C++ 层做帧率限速
大量数据传递（图像/点云）必须绕过 QVariant，走 QQuickImageProvider 或共享内存
把一帧 1080p 图像转成 QVariant(QByteArray) 再传给 QML，会触发至少两次深拷贝（C++ → QVariant → QML JS heap），实测 30fps 场景下 CPU 占用飙升 40%+。这不是设计缺陷，而是 QVariant 的语义决定它不适合大数据。
实操建议：
- 图像类数据统一走
QQuickImageProvider：注册后 QML 用image://myprovider/key加载，C++ 侧重写requestImage()，零拷贝返回QImage - 实时性要求极高的场景（如工业相机），用 POSIX 共享内存（
QSharedMemory） + 信号通知，QML 侧通过自定义QQuickItem子类直接映射渲染 - 绝对不要在信号参数里传
QImage或大QByteArray—— 即使编译通过，运行时性能也崩
QML 和 C++ 线程模型不一致：所有非 GUI 操作必须移出 QGuiApplication 线程
新手常把图像解码、网络请求、JSON 解析全塞在 QObject 子类里，然后用 Q_INVOKABLE 暴露给 QML。结果是 QML 主线程被阻塞，界面冻结，还误以为是“QML 性能差”。Qt 的线程模型很明确：GUI 只能在主线程操作，其他都该挪走。
实操建议：
- 用
QThread或QtConcurrent::run()把重任务移到子线程，完成后用信号通知主线程 - 子线程中不能访问
QQuickItem、QImage（除非标记Qt::AutoConnection并确认线程亲和性），也不能调用QMetaObject::invokeMethod()到 QML 对象上——得先 invoke 到主线程的代理对象 - 调试时打开
qInstallMessageHandler()，过滤"QThread" "QObject"关键字，能快速定位跨线程违规访问
真正难的不是“怎么连”，而是判断哪段逻辑该在哪条线程跑、数据在哪一刻可以安全移交。很多卡顿和崩溃，根源都在这个边界没划清楚。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
