桌面应用 / 系统课时
用 QML_ELEMENT 暴露 C++ 类型
用 QML_ELEMENT 暴露 C++ 类型
本篇解决 QML 无法直接创建自定义 C++ 对象的问题。通过 Qt 6 的 QML 类型注册机制,将 C++ 类纳入 QML 模块后,界面代码可以像使用内置类型一样创建和调用这些对象。
学习目标
- 理解 QML_ELEMENT 在 C++ 与 QML 类型系统之间的作用
- 掌握 qt_add_qml_module 注册 C++ 类型的基本流程
- 能够创建一个可被 QML 使用的自定义类型
C++ 类型为什么需要注册
QML 与 C++ 是两个独立的类型系统。普通 C++ 类虽然可以被 Qt 对象模型管理,但 QML 引擎并不知道它的存在,因此无法直接写出类似下面的代码:
qml
MyController {
}Qt 6 推荐使用 QML 模块方式组织类型。C++ 类通过宏声明自身属于某个 QML 模块,再由构建系统生成类型注册代码,最终让 QML 引擎能够发现并实例化它。

使用 QML_ELEMENT 声明类型
QML_ELEMENT 是 Qt 6 中推荐的类型注册方式。它要求类继承自 QObject,并且所在模块通过 qt_add_qml_module 管理。
下面创建一个简单的 C++ 类型。
cpp
// appcontroller.h
#pragma once
#include <QObject>
#include <qqmlintegration.h>
class AppController : public QObject
{
Q_OBJECT
QML_ELEMENT
public:
explicit AppController(QObject *parent = nullptr);
Q_INVOKABLE void refresh();
};QML_ELEMENT 会告诉 Qt 元对象系统:这个类需要作为 QML 类型导出。Q_INVOKABLE 则允许 QML 调用对应方法。
实现文件如下:
cpp
// appcontroller.cpp
#include "appcontroller.h"
#include <QDebug>
AppController::AppController(QObject *parent)
: QObject(parent)
{
}
void AppController::refresh()
{
qDebug() << "refresh called from QML";
}使用 qt_add_qml_module 注册模块
CMake 项目需要通过 qt_add_qml_module 声明 QML 模块,并把 C++ 类型加入该模块。
cmake
qt_add_executable(MyApp
main.cpp
appcontroller.cpp
appcontroller.h
)
qt_add_qml_module(MyApp
URI MyApp
VERSION 1.0
QML_FILES
Main.qml
SOURCES
appcontroller.h
appcontroller.cpp
)构建系统会根据模块信息生成类型注册代码。实际模块名称由 URI 决定,QML 中导入时必须保持一致。
验证时,可以在 QML 中导入模块并创建对象:
qml
import QtQuick
import MyApp
Item {
AppController {
id: controller
}
Component.onCompleted: {
controller.refresh()
}
}常见注册失败原因
如果 QML 报告类型不存在,通常检查以下位置:
- C++ 类是否继承自 QObject,并包含
Q_OBJECT - 是否包含
qqmlintegration.h qt_add_qml_module中是否加入对应源文件- QML 中的
importURI 是否与 CMake 中一致 - 构建目录是否重新生成了 QML 类型注册信息
QML_ELEMENT 的价值在于让 C++ 类型成为正式 QML 模块的一部分,而不是依赖运行时手动注入对象。对于大型桌面应用,这种方式更容易维护类型边界,也更符合 Qt 6 的工程化实践。
按自己的节奏,确认真正理解。