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

信号

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

方法

• void decrease()
• void increase()

详细说明

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

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

SpinBox {
    value: 50
}

对于浮点数值，请使用DoubleSpinBox 。

自定义值

尽管 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 Controls 中的焦点管理以及DoubleSpinBox 。

属性文档

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 : int

该属性存储范围的起始值。默认值为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 — 活动输入法不应将输入的文本存储在任何持久存储中，例如预测性用户词典。
• 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 : int

该属性用于存储步长。默认值为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

该属性存储范围的结束值。默认值为99 。

另请参阅 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 ；若stepSize 未定义，则减去1 。

另请参阅 stepSize 。

void increase()

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

另请参阅 stepSize 。