En esta página

ComboBox QML Type

Botón y lista desplegable combinados para seleccionar opciones. Más...

Import Statement: import QtQuick.Controls
Inherits:

Control

Propiedades

Señales

Métodos

Descripción detallada

ComboBox es una combinación de botón y lista desplegable. Permite presentar al usuario una lista de opciones ocupando el mínimo espacio posible en pantalla.

El ComboBox se rellena con un modelo de datos. El modelo de datos suele ser una matriz de JavaScript, un objeto « ListModel » o un entero, aunque también admite otros tipos de modelos de datos.

ComboBox {
    model: ["First", "Second", "Third"]
}

ComboBox editable

El ComboBox se puede convertir en un « editable ». Un combo box editable autocompleta su texto en función de lo que haya disponible en el modelo.

El siguiente ejemplo muestra cómo añadir contenido a un cuadro combinado editable respondiendo a la señal « accepted ».

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

Ventana emergente del ComboBox

De forma predeterminada, al hacer clic fuera de la ventana emergente del ComboBox, esta se cerrará y el evento se propagará a los elementos situados más abajo en el orden de apilamiento. Para evitar que se cierre la ventana emergente, configura su propiedad « closePolicy »:

    popup.closePolicy: Popup.CloseOnEscape

Para evitar la propagación del evento, establece su propiedad « modal » en « true »:

    popup.modal: true

Roles del modelo del ComboBox

El ComboBox es capaz de visualizar modelos de datos estándar que proporcionan el rol « modelData »:

  • modelos que solo tienen un rol
  • modelos que no tienen roles con nombre (matriz de JavaScript, entero)

Al utilizar modelos que tienen varios roles con nombre, ComboBox debe configurarse para utilizar un « text role » específico para sus instancias « display text » y « delegate ». Si desea utilizar un rol del elemento del modelo que se corresponda con el rol «text», establezca « valueRole ». A continuación, se pueden utilizar la propiedad « currentValue » y el método « indexOfValue()» para obtener información sobre dichos valores.

Por ejemplo:

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    // Used as an example of a backend - this would usually be
    // e.g. a C++ type exposed to QML.
    QtObject {
        id: backend
        property int modifier
    }

    ComboBox {
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
        textRole: "text"
        valueRole: "value"
        // Set currentValue to the value stored in the backend.
        currentValue: backend.modifier
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
    }
}

Nota: Si a ComboBox se le asigna un modelo de datos que tiene varios roles con nombre, pero no se define textRole, ComboBox no podrá visualizarlo y lanzará una excepción de tipo « ReferenceError: modelData is not defined ».

Véase también Personalización de ComboBox, controles de entrada y gestión del foco en los controles de Qt Quick .

Documentación de propiedades

acceptableInput : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si el cuadro combinado contiene texto válido en el campo de texto editable.

Si se ha configurado un validador, el valor es « true » solo si el texto actual es aceptable para el validador como cadena final (no como cadena intermedia).

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también « validator » y « accepted ».

count : int [read-only]

Esta propiedad contiene el número de elementos del cuadro combinado.

currentIndex : int

Esta propiedad contiene el índice del elemento actual en el cuadro combinado.

El valor por defecto es « -1 » cuando « count » es « 0 », y « 0 » en los demás casos.

Véase también activated(), currentText y highlightedIndex.

currentText : string [read-only]

Esta propiedad contiene el texto del elemento actual del cuadro combinado.

Véase también currentIndex, displayText, textRole y editText.

currentValue : var [since QtQuick.Controls 2.14 (Qt 5.14)]

Esta propiedad contiene el valor del elemento actual del cuadro combinado. Al establecer esta propiedad, se asignará a « currentIndex » el elemento con el valor correspondiente o « -1 » si no se encuentra. Establecer tanto « currentIndex » como « currentValue » de forma declarativa dará lugar a un comportamiento indefinido. No se admite establecer esta propiedad con un valor que no sea único.

Para ver un ejemplo de cómo utilizar esta propiedad, consulta ComboBox Model Roles.

Esta propiedad se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Véase también currentIndex, currentText y valueRole.

delegate : Component

Esta propiedad contiene un delegado que muestra un elemento en la ventana emergente del cuadro combinado.

Se recomienda utilizar ` ItemDelegate ` (o cualquier otro derivado de ` AbstractButton `) como delegado. Esto garantiza que la interacción funcione según lo esperado y que la ventana emergente se cierre automáticamente cuando sea necesario. Cuando se utilizan otros tipos como delegado, la ventana emergente debe cerrarse manualmente. Por ejemplo, si se utiliza ` MouseArea `:

delegate: Rectangle {
    // ...
    MouseArea {
        // ...
        onClicked: comboBox.popup.close()
    }
}

Desde Qt 6.11, ComboBox ya no asume la propiedad del delegado.

Véase también ItemDelegate y Personalización de ComboBox.

delegateModel : model [read-only]

Esta propiedad contiene el modelo que proporciona instancias de delegado para el cuadro combinado.

Normalmente se asigna a un ` ListView ` en el método ` contentItem ` del ` popup`.

Véase también Personalización deComboBox.

displayText : string

Esta propiedad contiene el texto que se muestra en el botón del cuadro combinado.

De forma predeterminada, el texto que se muestra corresponde a la selección actual. Es decir, coincide con el texto del elemento actual. No obstante, el texto predeterminado se puede sustituir por un valor personalizado.

ComboBox {
    currentIndex: 1
    displayText: "Size: " + currentText
    model: ["S", "M", "L"]
}

Véase también currentText y textRole.

down : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si el botón del cuadro combinado aparece visualmente pulsado.

A menos que se establezca explícitamente, esta propiedad es true cuando pressed o popup.visible son true. Para volver al valor predeterminado, establezca esta propiedad en undefined.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también pressed y popup.

editText : string [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad contiene el texto del campo de texto de un cuadro combinado editable.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también editable, currentText y displayText.

editable : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si el cuadro combinado es editable.

El valor por defecto es « false ».

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también « validator ».

flat : bool [since QtQuick.Controls 2.1 (Qt 5.8)]

Esta propiedad indica si el botón del cuadro combinado es plano.

Un botón de cuadro combinado plano no muestra fondo a menos que se interactúe con él. En comparación con los cuadros combinados normales, los cuadros combinados planos ofrecen un aspecto que hace que destaquen menos del resto de la interfaz de usuario. Por ejemplo, al colocar un cuadro combinado en una barra de herramientas, puede ser conveniente que el cuadro combinado sea plano para que combine mejor con el aspecto plano de los botones de la barra.

El valor por defecto es « false ».

Esta propiedad se introdujo en QtQuick.Controls 2.1 (Qt 5.8).

highlightOnHover : bool [since QtQuick.Controls 6.12 (Qt 6.12)]

Esta propiedad determina si al pasar el cursor por encima de los elementos estos deben resaltarse.

El valor por defecto es « true ».

Esta propiedad se introdujo en QtQuick.Controls 6.12 (Qt 6.12).

highlightedIndex : int [read-only]

Esta propiedad contiene el índice del elemento resaltado en la lista emergente del cuadro combinado.

Cuando se activa un elemento resaltado, se cierra la ventana emergente, se establece currentIndex en highlightedIndex y el valor de esta propiedad se restablece a -1, ya que ya no hay ningún elemento resaltado.

Véanse también highlighted() y currentIndex.

implicitContentWidthPolicy : enumeration [since QtQuick.Controls 6.0 (Qt 6.0)]

Esta propiedad controla cómo se calcula el valor de « implicitContentWidth » del elemento « ComboBox ».

Cuando el ancho de un « ComboBox » no es lo suficientemente grande como para mostrar el texto, este se omite. Dependiendo de qué partes del texto se omitan, esto puede dificultar la selección de un elemento por parte del usuario final. Una forma eficaz de garantizar que un « ComboBox » tenga el ancho suficiente para evitar que se omita texto es establecer un ancho que se sepa que es lo suficientemente grande:

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

Sin embargo, a menudo no es posible saber si un valor fijado de antemano será lo suficientemente grande, ya que el tamaño del texto depende de muchos factores, como la familia de fuentes, el tamaño de la fuente, las traducciones, etc.

`implicitContentWidthPolicy` ofrece una forma sencilla de controlar cómo se calcula `implicitContentWidth`, lo que a su vez afecta a la ` implicitWidth ` de ` ComboBox ` y garantiza que el texto no se omita.

Los valores disponibles son:

ConstanteDescripción
ContentItemImplicitWidthEl «implicitContentWidth» adoptará por defecto el valor del « contentItem ». Esta es la opción más eficiente, ya que no se realiza ningún ajuste adicional en la disposición del texto.
WidestTextEl «implicitContentWidth» se establecerá en el ancho implícito del texto más grande para el « textRole » dado cada vez que cambie el modelo. Esta opción debe utilizarse con modelos más pequeños, ya que puede resultar costosa.
WidestTextWhenCompletedEl valor de `implicitContentWidth` se establecerá en el ancho implícito del texto más grande del ` textRole ` dado una sola vez tras la llamada a ` component completion`. Esta opción debe utilizarse con modelos más pequeños, ya que puede resultar costosa.

El valor por defecto es ` ContentItemImplicitWidth`.

Dado que esta propiedad solo afecta al implicitWidth del ComboBox, establecer un width explícito puede seguir dando lugar a la elisión.

Nota: Esta función requiere que el «contentItem» sea un tipo derivado de « TextInput ».

Nota: Esta característica requiere que el texto esté maquetado, por lo que puede resultar costada para modelos grandes o cuyos contenidos se actualicen con frecuencia.

Esta propiedad se introdujo en QtQuick.Controls 6.0 (Qt 6.0).

implicitIndicatorHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene el indicador implícito «height».

El valor es igual a indicator ? indicator.implicitHeight : 0.

Normalmente se utiliza, junto con « implicitContentHeight » y « implicitBackgroundHeight », para calcular el « implicitHeight ».

Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Véase también implicitIndicatorWidth.

implicitIndicatorWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene el ancho implícito del indicador.

El valor es igual a « indicator ? indicator.implicitWidth : 0 ».

Normalmente se utiliza, junto con « implicitContentWidth » y « implicitBackgroundWidth », para calcular el « implicitWidth ».

Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Véase también implicitIndicatorHeight.

indicator : Item

Esta propiedad contiene el elemento indicador de desplegable.

Véase también «Personalización del cuadro combinado».

inputMethodComposing : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si un cuadro combinado editable contiene texto introducido parcialmente mediante un método de entrada.

Durante la composición, un método de entrada puede basarse en eventos del ratón o del teclado procedentes del cuadro combinado para editar o confirmar el texto parcial. Esta propiedad se puede utilizar para determinar cuándo desactivar los controladores de eventos que puedan interferir en el correcto funcionamiento de un método de entrada.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

inputMethodHints : flags [since QtQuick.Controls 2.2 (Qt 5.9)]

Proporciona indicaciones al método de entrada sobre el contenido esperado del cuadro combinado y cómo debe funcionar.

El valor por defecto es « Qt.ImhNoPredictiveText ».

El valor es una combinación bit a bit de indicadores o « Qt.ImhNone » si no se han establecido indicaciones.

Los indicadores que modifican el comportamiento son:

  • Qt.ImhHiddenText: los caracteres deben ocultarse, como suele hacerse al introducir contraseñas.
  • Qt.ImhSensitiveData: el texto escrito no debe ser almacenado por el método de entrada activo en ningún almacenamiento persistente, como el diccionario predictivo del usuario.
  • Qt.ImhNoAutoUppercase: el método de entrada no debe intentar cambiar automáticamente a mayúsculas al finalizar una frase.
  • Qt.ImhPreferNumbers: se da preferencia a los números (aunque no es obligatorio).
  • Qt.ImhPreferUppercase: se prefieren las mayúsculas (aunque no son obligatorias).
  • Qt.ImhPreferLowercase: Se prefieren las minúsculas (aunque no son obligatorias).
  • Qt.ImhNoPredictiveText: no se utiliza el texto predictivo (es decir, la búsqueda en el diccionario) mientras se escribe.
  • Qt.ImhDate: el editor de texto funciona como un campo de fecha.
  • Qt.ImhTime: el editor de texto funciona como un campo de hora.

Los indicadores que restringen la entrada (indicadores exclusivos) son:

  • Qt.ImhDigitsOnly: solo se permiten dígitos.
  • Qt.ImhFormattedNumbersOnly: solo se permite la introducción de números. Esto incluye el punto decimal y el signo menos.
  • Qt.ImhUppercaseOnly: solo se permite la introducción de letras mayúsculas.
  • Qt.ImhLowercaseOnly: solo se permite la introducción de letras minúsculas.
  • Qt.ImhDialableCharactersOnly: solo se permiten caracteres aptos para marcar números de teléfono.
  • Qt.ImhEmailCharactersOnly: solo se permiten caracteres adecuados para direcciones de correo electrónico.
  • Qt.ImhUrlCharactersOnly: solo se permiten caracteres aptos para direcciones URL.

Máscaras:

  • Qt.ImhExclusiveInputMask: esta máscara devuelve un valor distinto de cero si se utiliza cualquiera de los indicadores de exclusividad.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

model : model

Esta propiedad contiene el modelo que proporciona los datos para el cuadro combinado.

ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

Véase también « textRole » y «Modelos de datos».

Esta propiedad contiene la ventana emergente.

La ventana emergente se puede abrir o cerrar manualmente, si es necesario:

onSpecialEvent: comboBox.popup.close()

Véase también Personalización del ComboBox.

pressed : bool [read-only]

Esta propiedad indica si el botón del cuadro combinado está pulsado físicamente. Un botón puede pulsarse mediante eventos táctiles o de teclado.

Véase también down.

selectTextByMouse : bool [since QtQuick.Controls 2.15 (Qt 5.15)]

Esta propiedad determina si el campo de texto de un objeto « ComboBox » editable se puede seleccionar con el ratón.

El valor por defecto es « false ».

Esta propiedad se introdujo en QtQuick.Controls 2.15 (Qt 5.15).

textRole : string

Esta propiedad contiene el rol del modelo que se utiliza para rellenar el cuadro combinado.

Cuando el modelo tiene varias funciones, se puede configurar textRole para determinar qué función debe mostrarse.

Véase también model, currentText, displayText y ComboBox Model Roles.

validator : Validator [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad contiene un validador de texto de entrada para un cuadro combinado editable.

Cuando se configura un validador, el campo de texto solo aceptará entradas que dejen la propiedad «text» en un estado intermedio. La señal « accepted » solo se emitirá si el texto se encuentra en un estado aceptable al pulsar la tecla « Return » o « Enter ».

Los validadores compatibles actualmente son « IntValidator », « DoubleValidator » y « RegularExpressionValidator ». A continuación se muestra un ejemplo de uso de validadores, que permite introducir números enteros comprendidos entre « 0 » y « 10 » en el campo de texto:

ComboBox {
    model: 10
    editable: true
    validator: IntValidator {
        top: 9
        bottom: 0
    }
}

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también acceptableInput, accepted y editable.

valueRole : string [since QtQuick.Controls 2.14 (Qt 5.14)]

Esta propiedad contiene el rol del modelo que se utiliza para almacenar el valor asociado a cada elemento del modelo.

Para ver un ejemplo de cómo utilizar esta propiedad, consulta ComboBox Model Roles.

Esta propiedad se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Véase también model y currentValue.

Documentación sobre señales

[since QtQuick.Controls 2.2 (Qt 5.9)] void accepted()

Esta señal se emite cuando se pulsa la tecla « Return » o « Enter » en un cuadro combinado « editable ».

Puedes gestionar esta señal para añadir el elemento recién introducido al modelo, por ejemplo:

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

Antes de que se emita la señal, se comprueba si la cadena existe en el modelo. Si es así, se asignará a currentIndex su índice y a currentText la propia cadena.

Una vez emitida la señal, y si la primera comprobación ha fallado (es decir, el elemento no existía), se realizará otra comprobación para ver si el elemento ha sido añadido por el controlador de la señal. Si es así, currentIndex y currentText se actualizarán en consecuencia. De lo contrario, se establecerán en -1 y "", respectivamente.

Nota: Si hay una propiedad « validator » establecida en el cuadro combinado, la señal solo se emitirá si la entrada se encuentra en un estado aceptable.

Nota: El controlador correspondiente es onAccepted.

Esta señal se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

void activated(int index)

Esta señal se emite cuando el usuario activa el elemento situado en index.

Un elemento se activa cuando se selecciona mientras la ventana emergente está abierta, lo que provoca que esta se cierre (y que cambie currentIndex ), o cuando la ventana emergente está cerrada y se navega por el cuadro combinado mediante el teclado, lo que provoca que cambie currentIndex. La propiedad currentIndex se establece en index.

Nota: El controlador correspondiente es onActivated.

Véase también currentIndex.

void highlighted(int index)

Esta señal se emite cuando el usuario resalta el elemento situado en index dentro de la lista emergente.

La señal «highlighted» solo se emite cuando el menú emergente está abierto y se ha resaltado un elemento, pero no necesariamente « activated ».

Nota: El controlador correspondiente es « onHighlighted ».

Véase también « highlightedIndex ».

Documentación del método

void decrementCurrentIndex()

Disminuye el índice actual del cuadro combinado o el índice resaltado si la lista emergente está visible.

Véase también currentIndex y highlightedIndex.

int find(string text, enumeration flags)

Devuelve el índice del text especificado, o -1 si no se encuentra ninguna coincidencia.

La forma en que se realiza la búsqueda viene definida por el tipo de coincidencia especificado ( flags). Por defecto, el cuadro combinado realiza una coincidencia exacta que distingue entre mayúsculas y minúsculas (Qt.MatchExactly). Todos los demás tipos de coincidencia no distinguen entre mayúsculas y minúsculas, a menos que también se especifique el indicador « Qt.MatchCaseSensitive ».

ConstanteDescripción
Qt.MatchExactlyEl término de búsqueda coincide exactamente (por defecto).
Qt.MatchRegularExpressionEl término de búsqueda coincide como una expresión regular.
Qt.MatchWildcardEl término de búsqueda coincide utilizando comodines.
Qt.MatchFixedStringEl término de búsqueda coincide como una cadena fija.
Qt.MatchStartsWithEl término de búsqueda coincide con el inicio del elemento.
Qt.MatchEndsWithEl término de búsqueda coincide con el final del elemento.
Qt.MatchContainsEl término de búsqueda está contenido en el elemento.
Qt.MatchCaseSensitiveLa búsqueda distingue entre mayúsculas y minúsculas.

Nota: Esta función solo se puede utilizar después de que se haya emitido Component.completed() para el ComboBox.

Por ejemplo:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}

Véase también textRole.

void incrementCurrentIndex()

Aumenta el índice actual del cuadro combinado o el índice resaltado si la lista emergente está visible.

Véase también currentIndex y highlightedIndex.

[since QtQuick.Controls 2.14 (Qt 5.14)] int indexOfValue(object value)

Devuelve el índice del ` value` especificado, o ` -1 ` si no se encuentra ninguna coincidencia.

Para ver un ejemplo de cómo utilizar este método, consulta ComboBox Model Roles.

Nota: Esta función solo se puede utilizar después de que se haya emitido Component.completed() para el ComboBox.

Este método se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Véase también find(), currentValue, currentIndex, valueRole y valueAt.

[since QtQuick.Controls 2.2 (Qt 5.9)] void selectAll()

Selecciona todo el texto del campo de texto editable del cuadro combinado.

Este método se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también editText.

string textAt(int index)

Devuelve el texto correspondiente al index especificado, o una cadena vacía si el índice está fuera de los límites.

Nota: Esta función solo se puede utilizar después de que se haya emitido Component.completed() para el ComboBox.

Por ejemplo:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}

Véase también ` textRole`.

[since QtQuick.Controls 2.14 (Qt 5.14)] var valueAt(int index)

Devuelve el valor situado en la posición index del cuadro combinado.

Este método se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Véase también indexOfValue.

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