En esta página

Enumeraciones de QML

Las enumeraciones utilizadas en QML pueden definirse tanto en QML como en C++.

Para obtener información sobre cómo definir enumeraciones en QML, consulta «Atributos de enumeración».

Cuando se definen en C++, las enumeraciones expuestas a QML deben marcarse con las macros « Q_ENUM » o « Q_ENUM_NS » y formar parte de un tipo expuesto a QML mediante las macros « QML_NAMED_ELEMENT » o « QML_ELEMENT ». Para obtener más detalles, consulta Tipos de enumeración.

Solo los tipos QML con nombre pueden contener enumeraciones utilizables en QML. Cada enumeración debe estar rodeada por un tipo con nombre. Los espacios de nombres de QML también son tipos QML y pueden contener enumeraciones.

Como resultado, se puede hacer referencia a un valor de enumeración como <Type>.<Value>. Por ejemplo, el tipo Text tiene un valor de enumeración AlignRight:

Text { horizontalAlignment: Text.AlignRight }

Los valores de enumeración son propiedades de la referencia de tipo generada por el nombre del tipo. También se pueden recuperar utilizando la sintaxis de corchetes de JavaScript, aunque esto es propenso a errores y no se recomienda:

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

Uso de enumeraciones en QML

Las enumeraciones no son tipos independientes en QML, sino propiedades de los tipos que las rodean. Un valor de enumeración se representa como el tipo subyacente de la enumeración. Para la mayoría de las enumeraciones, es seguro utilizar el tipo `Number` de JavaScript o el tipo `double` de QML para almacenarlas. Sin embargo, esto no siempre funciona con los enteros de 64 bits, ya que su rango excede el rango seguro de los enteros de los tipos `double` de 64 bits. Por lo tanto, las enumeraciones con valores fuera del rango seguro de enteros (desde -(2^53 - 1) hasta 2^53 - 1, ambos inclusive) no pueden utilizarse de forma segura en QML. Para las enumeraciones cuyos valores se encuentran dentro del rango numérico de un entero con signo de 32 bits, se puede utilizar con seguridad el tipo «int» de QML como almacenamiento.

Por ejemplo:

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)
}

Funciones auxiliares para la conversión entre cadena de clave de enumeración y valor de clave

El objeto global Qt proporciona métodos auxiliares que permiten asignar el nombre de una clave de la enumeración a su valor numérico, o viceversa.

  • Qt.enumStringToValue: asigna una cadena que contiene el nombre de una clave a su valor numérico
  • Qt.enumValueToString: asigna un valor al nombre de la clave que corresponde a ese valor
  • Qt.enumValueToStrings: asigna un valor a una lista de nombres de las claves con ese valor

Ejemplo:

// 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)
}

Véase también Tipos de valor de QML, Atributos de enumeración, Tipos de enumeración, QtQml::Qt::enumStringToValue, QtQml::Qt::enumValueToString y QtQml::Qt::enumValueToStrings.

© 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.