桌面应用 / 系统课时

用 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 模块注册 C++ 类型流程示意图

使用 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 中的 import URI 是否与 CMake 中一致
  • 构建目录是否重新生成了 QML 类型注册信息

QML_ELEMENT 的价值在于让 C++ 类型成为正式 QML 模块的一部分,而不是依赖运行时手动注入对象。对于大型桌面应用,这种方式更容易维护类型边界,也更符合 Qt 6 的工程化实践。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 QML_ELEMENT 暴露 C++ 类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通