SpinBox QML Type

允许用户从一组预设值中进行选择。更多

• 所有成员（包括继承成员）的列表

属性

• 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 : double
• 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 : double
• 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))

信号

• valueModified() (since QtQuick.Controls 2.2 (Qt 5.9))

方法

• void decrease()
• void increase()

详细说明

SpinBox 允许用户通过点击向上或向下指示按钮，或按键盘上的向上或向下键来选择一个整数值。SpinBox 也可以选择设置为editable ，这样用户就可以在输入框中输入文本值。

默认情况下，SpinBox 提供的离散值范围为[0-99] ，stepSize 为1 。

SpinBox {
    value: 50
}

自定义值

尽管 SpinBox 使用的是整数值，但也可以对其进行自定义，以接受任意输入值。下面的代码段演示了如何使用validator 、textFromValue 和valueFromText 来定制默认行为。

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

可以使用正则表达式添加前缀和后缀：

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

另请参阅 Tumbler 、自定义 SpinBox 和 Qt Quick 控件中的焦点管理。

属性文档

displayText : string [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

该属性用于保存自旋框的文本值。

该属性的值基于textFromValue 和locale ，并等于：

var text = spinBox.textFromValue(spinBox.value, spinBox.locale)

该属性在 QtQuick.Controls 2.4 (Qt 5.11) 中引入。

另请参阅 textFromValue 。

down group

该分组属性包含向下指示符项及其相关属性。

down.hovered 属性在QtQuick.Controls 2.1 中引入，down.implicitIndicatorWidth 和down.implicitIndicatorHeight 属性在QtQuick.Controls 2.5 中引入。

另请参阅 decrease()。

editable : bool

该属性用于确定自旋框是否可编辑。默认值为false 。

另请参见 validator 。

from : double

该属性保存范围的起始值。默认值为0 。

另请参阅 to 和value 。

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

此属性表示可编辑的自旋框是否有来自输入法的部分文本输入。

在合成时，输入法可能会依赖来自自旋框的鼠标或按键事件来编辑或提交部分文本。此属性可用于确定何时禁用可能干扰输入法正确操作的事件处理程序。

此属性在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

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

该属性为输入法提供有关旋转框预期内容和操作方法的提示。

默认值为Qt.ImhDigitsOnly 。

该值是标志的位数组合，如果没有设置提示，则为Qt.ImhNone 。

可改变行为的标志有

• Qt.ImhHiddenText - 字符应被隐藏，通常用于输入密码。
• Qt.ImhSensitiveData - 输入的文本不应由 Active 输入法存储在任何持久性存储中，如预测用户字典。
• Qt.ImhNoAutoUppercase - 输入法不应尝试在句子结束时自动切换到大写字母。
• Qt.ImhPreferNumbers - 数字是首选（但不是必需）。
• Qt.ImhPreferUppercase - 首选大写字母（但不是必需的）。
• Qt.ImhPreferLowercase - 首选小写字母（但不是必需的）。
• Qt.ImhNoPredictiveText - 输入时不使用预测文本（即字典查询）。
• Qt.ImhDate - 文本编辑器具有日期字段的功能。
• Qt.ImhTime - 文本编辑器作为时间字段运行。

限制输入的标志（排他性标志）有

• Qt.ImhDigitsOnly - 只允许输入数字。
• Qt.ImhFormattedNumbersOnly - 只允许输入数字。这包括小数点和减号。
• Qt.ImhUppercaseOnly - 只允许输入大写字母。
• Qt.ImhLowercaseOnly - 只允许输入小写字母。
• Qt.ImhDialableCharactersOnly - 只允许输入适合电话拨号的字符。
• Qt.ImhEmailCharactersOnly - 只允许输入适合电子邮件地址的字符。
• Qt.ImhUrlCharactersOnly - 只允许使用适合 URL 的字符。

掩码：

• Qt.ImhExclusiveInputMask - 如果使用了任何独占标志，该掩码将产生非零值。

此属性在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

live : bool [since 6.6]

当用户编辑displayText 时，该属性将决定是否更新value 。默认值为false 。如果该属性为true ，且用户输入的值有效并在自旋框 [from,to] 的范围内，则将设置SpinBox 的值。如果该属性为false ，或者用户输入的值超出了边界，则该值不会更新，直到按下回车键或返回键，或者输入框失去焦点。

此属性在 Qt 6.6 中引入。

另请参阅 editable 和displayText 。

stepSize : double

该属性表示步长。默认值为1 。

另请参阅 increase() 和decrease() 。

textFromValue : function

该属性包含一个回调函数，每当需要将整数值转换为显示文本时，就会调用该函数。

可以重写默认函数，以便为给定值显示自定义文本。这适用于可编辑和不可编辑的自旋框；例如，当使用上下按钮或鼠标滚轮递增和递减数值时，新数值将使用此函数转换为显示文本。

回调函数的签名是string function(value, locale) 。该函数可以有一个或两个参数，其中第一个参数是要转换的值，可选的第二个参数是转换时应使用的本地语言（如果适用）。

默认实现使用Number.toLocaleString() 进行转换：

textFromValue: function(value, locale) { return Number(value).toLocaleString(locale, 'f', 0); }

另请参阅 valueFromText,validator, 和locale 。

to : int

该属性用于保存范围的终值。默认值为2 。

另请参阅 from 和value 。

up group

该分组属性包含向上指标项及其相关属性。

up.hovered 属性在QtQuick.Controls 2.1 中引入，up.implicitIndicatorWidth 和up.implicitIndicatorHeight 属性在QtQuick.Controls 2.5 中引入。

另请参阅 increase()。

validator : Validator

该属性用于保存可编辑自旋框的输入文本验证器。默认情况下，SpinBox 使用IntValidator 接受整数输入。

SpinBox {
    id: control
    validator: IntValidator {
        locale: control.locale.name
        bottom: Math.min(control.from, control.to)
        top: Math.max(control.from, control.to)
    }
}

另请参阅 editable,textFromValue,valueFromText,locale 和验证输入文本。

value : int

该属性的值范围为from -to 。默认值为0 。

valueFromText : function

该属性包含一个回调函数，每当需要将输入文本转换为整数值时，就会调用该函数。

只有当textFromValue 被重载为可编辑的自旋框时，才需要重载该函数。

回调函数的签名是int function(text, locale) 。该函数可以有一个或两个参数，其中第一个参数是要转换的文本，可选的第二个参数是转换时应使用的本地语言（如果适用）。

默认实现使用Number.fromLocaleString() 进行转换：

valueFromText: function(text, locale) { return Number.fromLocaleString(locale, text); }

另请参阅 textFromValue,validator, 和locale 。

wrap : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

该属性用于确定旋转框是否包裹。默认值为false 。

如果 wrap 为true ，则跨过to 会将值更改为from ，反之亦然。

此属性在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

信号文档

[since QtQuick.Controls 2.2 (Qt 5.9)] valueModified()

当用户通过触摸、鼠标、滚轮或按键对旋转框的值进行交互式修改时，就会发出该信号。在通过键盘交互的情况下，只有当文本被接受（即按下回车键或回车键或输入框失去焦点）时，才会发出该信号。

该信号在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

方法文档

void decrease()

通过stepSize 或1 （如果stepSize 没有定义）减少数值。

另请参阅 stepSize 。

void increase()

增加stepSize 的值，如果stepSize 未定义，则增加1 的值。

另请参阅 stepSize 。