QML调用C++对象必须先注册为QML类型，即继承QObject、声明Q_OBJECT、用Q_PROPERTY和Q_INVOKABLE暴露接口，并通过qmlRegisterType或qmlRegisterSingletonType注册；未注册则运行时报ReferenceError。
QML 调用 C++ 对象：必须注册为 QML 类型才能 new Object
QML 里不能直接 new 一个普通 C++ 类实例，必须先用 qRegisterMetaType 和 qmlRegisterType（或 qmlRegisterSingletonType）暴露给 QML 引擎。没注册就 import 或 new，运行时会报错：ReferenceError: XXX is not defined 或编译期提示类型未识别。
常见做法是让 C++ 类继承 QObject，声明 Q_OBJECT，并用 Q_PROPERTY 暴露成员变量、Q_INVOKABLE 标记可调用方法：
class DataHandler : public QObject {
Q_OBJECT
Q_PROPERTY(QString status READ status WRITE setStatus NOTIFY statusChanged)
public:
explicit DataHandler(QObject *parent = nullptr) : QObject(parent) {}
Q_INVOKABLE void loadData();
QString status() const { return m_status; }
signals:
void statusChanged();
private:
QString m_status;
};
注册时注意作用域和生命周期：
- 用
qmlRegisterType<datahandler>("MyModule", 1, 0, "DataHandler")</datahandler>→ QML 中可写import MyModule 1.0+DataHandler { id: handler } - 若对象需全局单例（如配置管理器），优先用
qmlRegisterSingletonType，避免重复构造和内存管理问题 - 注册必须在
QGuiApplication构造之后、engine.load()之前完成，否则类型不可见
QML 调用 C++ 方法：Q_INVOKABLE 是最简方式，信号槽不直接暴露
QML 只能直接调用带 Q_INVOKABLE 修饰或 public slots 的 C++ 成员函数。普通成员函数、static 函数、未声明 slot 的函数一律不可调用 —— 即使它在 C++ 侧可访问，QML 也会静默失败或报 TypeError: Property 'xxx' of object ... is not a function。
立即学习“C++免费学习笔记（深入）”；
参数和返回值受限于 Qt 元对象系统支持的类型：
- 支持：基本类型（
int,bool,QString）、QVariant、已注册的自定义类型、QList<t></t>（T 需可被元对象识别） - 不支持：裸指针（
int*）、STL 容器（std::vector）、未注册的 struct、lambda 表达式 - 返回
void没问题；返回QObject*时，QML 会自动包装为 JS 对象，但要注意所有权（默认QQmlEngine::CppOwnership）
示例 QML 调用：
import MyModule 1.0
DataHandler {
id: handler
Component.onCompleted: {
handler.loadData(); // ✅ 正确调用
console.log(handler.status); // ✅ 自动映射 Q_PROPERTY
}
}
传参与异步：C++ 方法返回数据后，QML 如何安全接收
同步调用没问题，但一旦 C++ 方法涉及 IO、网络或耗时计算，直接阻塞 QML 线程会导致界面卡死。Qt 推荐模式是“发请求 → 收信号”，而非等返回值。
关键点：
- C++ 方法内部不要 return 大量数据（尤其 QImage、QByteArray），改用信号发射：
emit dataReady(QVariantMap result) - QML 中用
onDataReady: { console.log(result) }响应，确保线程安全（信号自动跨线程排队） - 如果必须同步返回，且数据量小，可用
QVariantMap或QJsonObject（需 includeQJsonDocument并注册类型） - 避免在 C++ 方法里直接操作 QML 对象（如
item.setProperty），这违反线程隔离原则；统一走信号通知
调试与常见崩溃点：QML 侧访问空指针、线程越界、元对象未注册
最常导致应用 crash 的三个场景：
-
Cannot assign to non-existent property "xxx"：Q_PROPERTY 名拼错，或 getter/setter 签名不匹配（比如 setter 参数不是 const ref） - QML 调用后程序立即 crash，堆栈停在
QMetaObject::activate：C++ 对象已被 delete，但 QML 还持有引用 → 用setParent(nullptr)或QQmlEngine::setObjectOwnership(obj, QQmlEngine::CppOwnership)明确管理生命周期 - 信号在非 GUI 线程 emit 后，QML 不响应：确认信号连接用了
Qt::AutoConnection（默认），且接收方（QML）在 GUI 线程；若 C++ 在 worker thread 发信号，Qt 会自动排队到主线程
建议开发期打开 Qt 警告：qputenv("QT_LOGGING_RULES", "qt.qml.binding.removal.debug=true")，能捕获属性绑定失效类问题。
真正麻烦的从来不是怎么注册、怎么调用，而是谁负责 delete、信号在哪条线程触发、QML 对象销毁时 C++ 端有没有及时解绑 —— 这些边界问题不提前想清楚，上线后很难复现和定位。
