Qt 6.2+：如何从非QObject的C++代码向QML暴露枚举

针对Qt 6.2+基于QML_ELEMENT的模块系统，非QObject类型（Q_GADGET类或Q_NAMESPACE命名空间）的枚举无法被QML识别的问题，需通过补充QML相关宏完成暴露，以下是两种方案的正确实现方式：

方案1：基于Q_GADGET类的枚举暴露 #

需在类中添加QML_UNCREATABLE宏配合Q_GADGET与Q_ENUM，同时确保类被纳入QML模块：

#include <QObject>

class GadgetEnums : public QObject
{
    Q_GADGET
    QML_UNCREATABLE("Gadget class cannot be instantiated in QML")
    QML_ELEMENT

public:
    enum class TaskStatus {
        Idle,
        Running,
        Failed
    };
    Q_ENUM(TaskStatus)

private:
    GadgetEnums() = default; // 私有构造函数防止实例化
};

QML调用示例：

import YourModuleUri 1.0

Item {
    Component.onCompleted: {
        console.log(GadgetEnums.TaskStatus.Idle)
    }
}

方案2：基于Q_NAMESPACE命名空间的枚举暴露 #

需在命名空间中添加QML_NAMESPACE宏配合Q_NAMESPACE与Q_ENUM_NS，同时在CMake中确保相关头文件被纳入模块：

#include <QObject>

namespace AppEnums {
    Q_NAMESPACE
    QML_NAMESPACE

    enum class DisplayMode {
        Light,
        Dark,
        Auto
    };
    Q_ENUM_NS(DisplayMode)
}

CMake配置示例（需将命名空间头文件加入SOURCES）：

qt_add_qml_module(YourModuleName
    URI YourModuleUri
    VERSION 1.0
    SOURCES
        appenums.h
        # 其他模块源文件
)

QML调用示例：

import YourModuleUri 1.0

Item {
    Component.onCompleted: {
        console.log(AppEnums.DisplayMode.Light)
    }
}

核心注意点 #

• 仅使用Q_ENUM/Q_ENUM_NS不足以让Qt 6的QML模块系统识别非QObject枚举，必须搭配QML_UNCREATABLE（Q_GADGET类）或QML_NAMESPACE（命名空间）宏。
• 确保CMake的qt_add_qml_module包含所有相关头文件，且QML中的import URI与模块配置的URI完全一致。
• Q_GADGET类建议将构造函数设为私有，配合QML_UNCREATABLE明确告知QML无法创建该类实例。

内容的提问来源于stack exchange，提问作者Paul Masri-Stone