QML 枚举

QML 中使用的枚举既可以在 QML 中定义，也可以在 C++ 中定义。

有关在 QML 中定义枚举的信息，请参阅“枚举属性”。

在 C++ 中定义时，向 QML 公开的枚举必须使用Q_ENUM 或Q_ENUM_NS 宏进行标记，并且必须属于通过QML_NAMED_ELEMENT 或QML_ELEMENT 宏向 QML 公开的类型。有关更多详细信息，请参阅“枚举类型”。

只有命名过的 QML 类型才能包含可在 QML 中使用的枚举。每个枚举都必须由一个命名类型作为外层容器。QML 命名空间也是 QML 类型，可以包含枚举。

因此，枚举值可通过<Type>.<Value> 这种形式引用。例如，Text 类型包含一个名为AlignRight 的枚举值：

Text { horizontalAlignment: Text.AlignRight }

枚举值是类型名称所生成的类型引用上的属性。您也可以使用 JavaScript 的方括号语法来获取它们，尽管这种方法容易出错，因此不建议使用：

// Avoid this if possible
Text { horizontalAlignment: Text["AlignRight"] }

在 QML 中使用枚举

在 QML 中，枚举并非独立的类型，而是其所包含类型的属性。枚举值以枚举的底层类型表示。对于大多数枚举，使用 JavaScript 的Number类型或 QML 的double类型来存储它们是安全的。但是，对于 64 位整数，这种方法并不总是有效，因为它们的范围超出了 64 位双精度数的“安全整数范围”。因此，值超出安全整数范围（从 -(2^53 - 1) 到 2^53 - 1，包含两端）的枚举在 QML 中无法安全使用。对于值落在 32 位有符号整数数值范围内的枚举，您可以安全地使用 QML 的int类型作为存储。

例如：

import QtQuick

Item {
    // refer to Text.AlignRight using an int type
    property int enumValue: textItem.horizontalAlignment

    signal valueEmitted(int someValue)

    Text {
        id: textItem
        horizontalAlignment: Text.AlignRight
    }

    // emit valueEmitted() signal, which expects an int, with Text.AlignRight
    Component.onCompleted: valueEmitted(Text.AlignRight)
}

枚举键字符串 <-> 键值辅助函数

Qt 全局对象提供了辅助方法，可将枚举中的键名映射为其数值，或反之。

Qt.enumStringToValue：将包含键名的字符串映射到其数值
Qt.enumValueToString：将一个值映射为具有该值的键的名称
Qt.enumValueToStrings：将一个值映射为包含该值的所有键名的列表

示例：

// Main.qml
import QtQml

Item {
    enum E { Black = 0, White = 1, Grey = 2, Gray = 2 }

    // 1 (White)
    property int i: Qt.enumStringToValue(Main.E, "White")

    // "Black"
    property string s: Qt.enumValueToString(Main.E, Main.E.Black)

    // ["Grey", "Gray"]
    property list<string> ss: Qt.enumValueToStrings(Main.E, Main.E.Grey)
}

另请参阅 QML 值类型、枚举属性、枚举类型、QtQml::Qt::enumStringToValue 、QtQml::Qt::enumValueToString 以及QtQml::Qt::enumValueToStrings 。

QML 值类型 QML 序列类型

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.