SpinBox QML Type
Permite al usuario seleccionar entre un conjunto de valores predefinidos. Más...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
Propiedades
- displayText : string
(since QtQuick.Controls 2.4 (Qt 5.11)) - down
- down.hovered : bool
- down.implicitIndicatorHeight : real
- down.implicitIndicatorWidth : real
- down.indicator : Item
- down.pressed : bool
- editable : bool
- from : int
- inputMethodComposing : bool
(since QtQuick.Controls 2.2 (Qt 5.9)) - inputMethodHints : flags
(since QtQuick.Controls 2.2 (Qt 5.9)) - live : bool
(since 6.6) - stepSize : int
- textFromValue : function
- to : int
- up
- up.hovered : bool
- up.implicitIndicatorHeight : real
- up.implicitIndicatorWidth : real
- up.indicator : Item
- up.pressed : bool
- validator : Validator
- value : int
- valueFromText : function
- wrap : bool
(since QtQuick.Controls 2.3 (Qt 5.10))
Señales
- valueModified()
(since QtQuick.Controls 2.2 (Qt 5.9))
Métodos
Descripción detallada

SpinBox permite al usuario seleccionar un valor entero haciendo clic en los botones indicadores de subir o bajar, o pulsando las teclas de flecha arriba o abajo del teclado. Opcionalmente, SpinBox también puede configurarse como « editable », de modo que el usuario pueda introducir un valor de texto en el campo de entrada.
Por defecto, SpinBox ofrece valores discretos en el rango de [0-99] con un stepSize de 1.
SpinBox {
value: 50
}Para valores de punto flotante, utilice DoubleSpinBox.
Valores personalizados

Aunque SpinBox funciona con valores enteros, se puede personalizar para que acepte valores de entrada arbitrarios. El siguiente fragmento de código muestra cómo se pueden utilizar validator, textFromValue y valueFromText para personalizar el comportamiento predeterminado.
SpinBox {
id: spinBox
from: 0
to: items.length - 1
value: 1 // "Medium"
property list<string> items: ["Small", "Medium", "Large"]
validator: RegularExpressionValidator {
regularExpression: new RegExp("(Small|Medium|Large)", "i")
}
textFromValue: function(value) {
return items[value];
}
valueFromText: function(text) {
for (var i = 0; i < items.length; ++i) {
if (items[i].toLowerCase().indexOf(text.toLowerCase()) === 0)
return i
}
return spinBox.value
}
}Se pueden añadir un prefijo y un sufijo utilizando expresiones regulares:
SpinBox {
id: spinBox
from: -100
value: 11
to: 100
editable: true
anchors.centerIn: parent
property string prefix: "L="
property string suffix: "m"
readonly property regexp numberExtractionRegExp: /\D*?(-?\d*\.?\d*)\D*$/
validator: RegularExpressionValidator { regularExpression: numberExtractionRegExp }
textFromValue: function(value, locale) {
return prefix + Number(value).toLocaleString(locale, 'f', 0) + suffix
}
valueFromText: function(text, locale) {
return Number.fromLocaleString(locale, numberExtractionRegExp.exec(text)[1])
}
}Véase también Tumbler, Personalización de SpinBox, Gestión del foco en controles Qt Quick y DoubleSpinBox.
Documentación de propiedades
displayText : string [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]
Esta propiedad contiene el valor textual del cuadro de selección.
El valor de la propiedad se basa en textFromValue y locale, y es igual a:
var text = spinBox.textFromValue(spinBox.value, spinBox.locale)Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).
Véase también textFromValue.
down group
down.hovered : bool
down.implicitIndicatorHeight : real
down.implicitIndicatorWidth : real
down.indicator : Item
down.pressed : bool
Esta propiedad agrupada contiene el elemento indicador de «abajo» y sus propiedades asociadas.
La propiedad « down.hovered » se introdujo en QtQuick.Controls 2.1, y las propiedades « down.implicitIndicatorWidth » y « down.implicitIndicatorHeight » se introdujeron en QtQuick.Controls 2.5.
Véase también decrease().
editable : bool
Esta propiedad indica si el cuadro de selección de valores es editable. El valor por defecto es « false ».
Véase también validator.
from : int
Esta propiedad contiene el valor inicial del rango. El valor por defecto es 0.
inputMethodComposing : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]
Esta propiedad indica si un cuadro giratorio 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 de selección 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)]
Esta propiedad proporciona indicaciones al método de entrada sobre el contenido esperado del cuadro de selección y sobre cómo debe funcionar.
El valor por defecto es Qt.ImhDigitsOnly.
El valor es una combinación bit a bit de indicadores o « Qt.ImhNone » si no se ha establecido ninguna indicación.
Los indicadores que modifican el comportamiento son:
- Qt.ImhHiddenText: los caracteres deben aparecer ocultos, 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 utilizar texto predictivo (es decir, 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 introducir letras minúsculas.
- Qt.ImhDialableCharactersOnly: solo se permiten caracteres aptos para marcar un número 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 exclusivos.
Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).
live : bool [since 6.6]
Esta propiedad determina si el campo « value » se actualiza cuando el usuario edita el campo « displayText ». El valor por defecto es « false ». Si esta propiedad está configurada como « true » y el valor introducido por el usuario es válido y se encuentra dentro de los límites del cuadro de selección [from, to], se establecerá el valor del campo « SpinBox ». Si esta propiedad es « false » o el valor introducido por el usuario se encuentra fuera de los límites, el valor no se actualizará hasta que se pulsen las teclas «Intro» o «Retorno», o hasta que el campo de entrada pierda el foco.
Esta propiedad se introdujo en Qt 6.6.
Véase también editable y displayText.
stepSize : int
Esta propiedad contiene el tamaño del paso. El valor por defecto es 1.
Véase también increase() y decrease().
textFromValue : function
Esta propiedad contiene una función de devolución de llamada que se ejecuta cada vez que es necesario convertir un valor entero para mostrarlo como texto.
La función predeterminada se puede sobrescribir para mostrar un texto personalizado para un valor determinado. Esto se aplica tanto a los cuadros de selección editables como a los no editables; por ejemplo, al utilizar los botones de subir y bajar o la rueda del ratón para incrementar o disminuir el valor, el nuevo valor se convierte a texto visible mediante esta función.
La firma de la función de devolución de llamada es ` string function(value, locale)`. La función puede tener uno o dos argumentos: el primero es el valor que se va a convertir y el segundo, opcional, es la configuración regional que se debe utilizar para la conversión, si procede.
La implementación predeterminada realiza la conversión mediante Number.toLocaleString():
textFromValue: function(value, locale) { return Number(value).toLocaleString(locale, 'f', 0); }Nota: Al aplicar una implementación personalizada de ` textFromValue ` para los campos de selección editables, debe proporcionarse una implementación correspondiente de ` valueFromText ` para poder volver a convertir el texto personalizado en un valor entero.
Véase también valueFromText, validator y locale.
to : int
Esta propiedad contiene el valor final del rango. El valor por defecto es 99.
up group
up.hovered : bool
up.implicitIndicatorHeight : real
up.implicitIndicatorWidth : real
up.indicator : Item
up.pressed : bool
Esta propiedad agrupada contiene el elemento indicador «arriba» y sus propiedades asociadas.
La propiedad « up.hovered » se introdujo en QtQuick.Controls 2.1, y las propiedades « up.implicitIndicatorWidth » y « up.implicitIndicatorHeight » se introdujeron en QtQuick.Controls 2.5.
Véase también increase().
validator : Validator
Esta propiedad contiene el validador de texto de entrada para los campos de selección editables. Por defecto, SpinBox utiliza IntValidator para aceptar la introducción de números enteros.
SpinBox {
id: control
validator: IntValidator {
locale: control.locale.name
bottom: Math.min(control.from, control.to)
top: Math.max(control.from, control.to)
}
}Véase también editable, textFromValue, valueFromText, locale y Validación de texto introducido.
value : int
Esta propiedad toma valores comprendidos entre from y to. El valor por defecto es 0.
valueFromText : function
Esta propiedad contiene una función de devolución de llamada que se activa cada vez que es necesario convertir el texto introducido en un valor entero.
Esta función solo debe sobrescribirse cuando se sobrescribe ` textFromValue ` para un cuadro de selección editable.
La firma de la función de devolución de llamada es ` int function(text, locale)`. La función puede tener uno o dos argumentos: el primero es el texto que se va a convertir, y el segundo, opcional, es la configuración regional que se debe utilizar para la conversión, si procede.
La implementación por defecto realiza la conversión utilizando Number.fromLocaleString():
valueFromText: function(text, locale) { return Number.fromLocaleString(locale, text); }Nota: Al aplicar una implementación personalizada de ` textFromValue ` para los campos de selección editables, debe proporcionarse una implementación correspondiente de ` valueFromText ` para poder volver a convertir el texto personalizado en un valor entero.
Véase también textFromValue, validator y locale.
wrap : bool [since QtQuick.Controls 2.3 (Qt 5.10)]
Esta propiedad determina si el cuadro de selección de valor se ajusta a la línea. El valor por defecto es « false ».
Si wrap es true, al pasar de to, el valor cambia a from y viceversa.
Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).
Documentación de señales
[since QtQuick.Controls 2.2 (Qt 5.9)] valueModified()
Esta señal se emite cuando el usuario ha modificado de forma interactiva el valor del cuadro de selección mediante el tacto, el ratón, la rueda o las teclas. En el caso de la interacción mediante el teclado, la señal solo se emite cuando se ha aceptado el texto; es decir, cuando se pulsan las teclas «Intro» o «Retorno», o cuando el campo de entrada pierde el foco.
Nota: El controlador correspondiente es onValueModified.
Esta señal se introdujo en QtQuick.Controls 2.2 (Qt 5.9).
Documentación del método
void decrease()
Reduce el valor en stepSize, o en 1 si stepSize no está definido.
Véase también stepSize.
void increase()
Aumenta el valor en stepSize, o en 1 si stepSize no está definido.
Véase también stepSize.
© 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.