SpinBox QML 类型

允许用户从一组预置值中选择。 更多...

导入声明import QtQuick.Controls
继承

Control

属性

信号

方法

详细描述

SpinBox 允许用户通过点击上或下指示按钮，或通过按键盘上的上或下键来选择整数值。可选地，SpinBox 还可以是可编辑的，因此用户可以在输入字段中输入文本值。

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

SpinBox {
    value: 50
}

自定义值

尽管 SpinBox 适用于整数值，但它可以自定义以接受任意输入值。以下代码片段展示了如何使用 validator、textFromValue 和 valueFromText 来自定义默认行为。

SpinBox {
    id: spinBox
    from: 0
    to: items.length - 1
    value: 1 // "Medium"

    property var 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 可以自定义以接受浮点数

SpinBox {
    id: spinBox
    from: 0
    value: decimalToInt(1.1)
    to: decimalToInt(100)
    stepSize: decimalFactor
    editable: true
    anchors.centerIn: parent

    property int decimals: 2
    property real realValue: value / decimalFactor
    readonly property int decimalFactor: Math.pow(10, decimals)

    function decimalToInt(decimal) {
        return decimal * decimalFactor
    }

    validator: DoubleValidator {
        bottom: Math.min(spinBox.from, spinBox.to)
        top:  Math.max(spinBox.from, spinBox.to)
        decimals: spinBox.decimals
        notation: DoubleValidator.StandardNotation
    }

    textFromValue: function(value, locale) {
        return Number(value / decimalFactor).toLocaleString(locale, 'f', spinBox.decimals)
    }

    valueFromText: function(text, locale) {
        return Math.round(Number.fromLocaleString(locale, text) * decimalFactor)
    }
}

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

SpinBox {
    id: spinBox
    from: 0
    value: 11
    to: 100
    editable: true
    anchors.centerIn: parent

    property string prefix: "L="
    property string suffix: "m"

    validator: RegularExpressionValidator { regularExpression: /\D*(-?\d*\.?\d*)\D*/ }

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

    valueFromText: function(text, locale) {
        let re = /\D*(-?\d*\.?\d*)\D*/
        return Number.fromLocaleString(locale, re.exec(text)[1])
    }
}

另请参阅Tumbler、Customizing SpinBox 和 Qt Quick Controls 中的焦点管理。

属性文档

displayText : 字符串 [只读，自 QtQuick.Controls 2.4 (Qt 5.11) 起]

此属性持有 spinbox 的文本值。

属性值基于 textFromValue 和 locale，等于

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

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

另请参阅textFromValue。


向下分组

down.hovered : 布尔

down.implicitIndicatorHeight : 实数

down.implicitIndicatorWidth : 实数

down.indicator : 项

down.pressed : 布尔

这些属性包含向下指示项及其是否被按下或悬停。属性 down.hovered 自 QtQuick.Controls 2.1 起引入，属性 down.implicitIndicatorWidth 和 down.implicitIndicatorHeight 自 QtQuick.Controls 2.5 起引入。

另请参阅decrease()。


editable : 布尔

该属性表示 spinbox 是否可编辑。默认值是 false。

另请参阅validator。


from : 整数

该属性包含范围的起始值。默认值是 0。

另请参阅to 和 value。


inputMethodComposing : 布尔 [只读，自 QtQuick.Controls 2.2 (Qt 5.9) 起]

该属性表示可编辑的 spinbox 是否有输入法输入的文本。

在聚合过程中，输入法可能依赖于来自 spinbox 的鼠标或键盘事件来编辑或提交部分文本。该属性可以用以确定何时禁用可能干扰输入法正确操作的参数。

该属性自 QtQuick.Controls 2.2 (Qt 5.9) 起引入。


inputMethodHints : flags [自 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 [自 6.6 版本开始]

此属性表示是否在用户编辑 displayText 时更新 value。默认值是 false。如果此属性为 true 且用户输入的值有效且位于旋转框 [from, to] 的范围内，则将设置旋转框的值。如果此属性为 false 或用户输入的值超出范围，则值将不会更新，直到按下回车或换行键，或者输入字段失去焦点。

此属性是在 Qt 6.6 版本中引入的。

另请参阅 editable 和 displayText。


stepSize : int

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

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


textFromValue : function

该属性表示一个回调函数，每次需要将整数值转换为显示文本时都会调用该函数。

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

回调函数签名是 string function(value, locale)。函数可以有一个或两个参数，其中第一个参数是要转换的值，可选的第二个参数是用于转换的locale，如果适用的话。

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

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

注意：当为可编辑的微调控件应用自定义 textFromValue 实现时，必须提供匹配的 valueFromText 实现以便能够将自定义文本转换回整数值。

另请参阅：valueFromText、validator 和 locale。


to : int

该属性持有范围的最大值。默认值为 99。

另请参阅：from 和 value。


向上组

up.hovered : bool

up.implicitIndicatorHeight : real

up.implicitIndicatorWidth : real

up.indicator : Item

up.pressed : bool

这些属性持有向上指示器项以及它是否被按下或悬停。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 和 Validate Input Text。


value : int

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


valueFromText : function

该属性持有在需要将输入文本转换为整数值时被调用的回调函数。

只有当为可编辑的微调控件覆盖 textFromValue 时，才需要覆盖此函数。

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

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

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

注意：当为可编辑的微调框应用自定义 textFromValue 实现时，必须提供匹配的 valueFromText 实现才能将自定义文本转换回整数值。

另请参阅 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()

当用户通过触摸、鼠标、滚轮或键盘交互式修改微调框的值时，将发出此信号。在通过键盘交互的情况下，仅在文本被接受时发出信号；这意味着在按 enter 或 return 键或输入字段失去焦点时。

注意：相应的处理程序是 onValueModified。

此信号是在 QtQuick.Controls 2.2（Qt 5.9）中引入的。


方法文档

void decrease()

减小值通过 stepSize，如果没有定义则通过 1。

另请参阅 stepSize。


void increase()

通过 stepSize 增加值，如果没有定义则通过 1。

另请参阅 stepSize。


© 2024 Qt 公司。此处包含的文档贡献者的版权所有。本提供的文档是根据由自由软件基金会发布的 GNU 自由文档许可证版本 1.3 的条款许可的。Qt 和相应的标志是芬兰及/或全世界 Qt 公司的商标。所有其他商标均为其各自所有者的财产。