当前位置：首页 > news >正文

PyQt QDoubleSpinBox控件用法详解

news 来源：原创 2025/5/23 2:34:17

QDoubleSpinBox 是 PyQt中用于输入浮点数的控件，支持键盘输入和上下箭头调整数值。与QtSpinBox不同，QtSpinBox是用于输入整数的控件。

关键属性和方法

QDoubleSpinBox 的关键属性和方法如下表所示：

方法/属性	说明
`setRange(min, max)`	设置数值范围
`setSingleStep(step)`	设置步长（箭头点击一次的变化量）
`setDecimals(n)`	设置小数位数
`setValue(value)`	设置当前值
`value()`	获取当前值
`valueChanged`	数值变化时触发的信号
`setPrefix(text)`	添加前缀文本
`setSuffix(text)`	添加后缀文本

基础设置方法

setRange(min, max)
设置数值范围（最小值 min，最大值 max）。
setMinimum(min) / setMaximum(max)
单独设置最小值或最大值。
setSingleStep(step)
设置步长（点击箭头时数值的变化量）。
setDecimals(prec)
设置显示的小数位数（如 prec=2 保留两位小数）。
setValue(value)
直接设置当前值（需确保值在范围内）。
setPrefix(text) / setSuffix(text)
添加前缀或后缀文本（如单位符号）。

值获取方法

value()
返回当前数值（浮点数类型）。
textFromValue(value) / valueFromText(text)
自定义数值与文本的转换逻辑（用于输入验证或格式化）。

行为控制方法

setKeyboardTracking(enabled)
控制是否在输入时实时更新值（默认 True，实时更新；设为 False 则在输入完成后更新）。
stepBy(steps)
按步长增量调整值（正数增加，负数减少）。
stepUp() / stepDown()
触发一次步长增加或减少操作。

输入验证方法

setCorrectionMode(mode)
设置输入修正模式（如 QDoubleSpinBox.CorrectToNearestValue 自动修正非法值）。
validate(text, pos) / fixup(text)
自定义输入验证逻辑（需重写方法）。

信号

valueChanged(double)
数值变化时触发的信号（参数为当前值）。
editingFinished()
用户结束编辑（如按下回车或焦点离开）时触发。

其他实用方法

clear()
清空值（重置为最小值或 0.0，取决于范围）。
setAlignment(alignment)
设置文本对齐方式（如 Qt.AlignRight）。
setReadOnly(enabled)
设为只读模式（用户不可编辑）。

用法示例

控件初始化

from PyQt5.QtWidgets import QApplication, QWidget, QDoubleSpinBox, QVBoxLayout

app = QApplication([])
window = QWidget()
layout = QVBoxLayout()

# 创建控件并设置初始属性
spinbox = QDoubleSpinBox()
spinbox.setRange(-100.0, 100.0)   # 设置数值范围
spinbox.setSingleStep(0.5)        # 设置步长（箭头点击一次的变化量）
spinbox.setDecimals(2)            # 保留两位小数
spinbox.setValue(3.14)            # 设置初始值

layout.addWidget(spinbox)
window.setLayout(layout)
window.show()
app.exec_()

信号与槽连接

当用户修改数值时，触发 valueChanged 信号：

def on_value_changed(value):
    print(f"当前值: {value}")

spinbox.valueChanged.connect(on_value_changed)

动态调整范围

根据条件动态修改范围或步长：

# 当数值超过50时，自动扩展范围
def check_range(value):
    if value > 50.0:
        spinbox.setRange(0.0, 100.0)
    else:
        spinbox.setRange(0.0, 50.0)

spinbox.valueChanged.connect(check_range)

格式化显示

添加前缀/后缀或自定义格式：

spinbox.setPrefix("温度: ")     # 添加前缀
spinbox.setSuffix("°C")        # 添加后缀

# 使用自定义格式（如货币）
spinbox.setDecimals(0)
spinbox.setPrefix("$ ")

输入验证

限制用户输入非法值（如超过范围时自动修正）：

spinbox.setKeyboardTracking(False)  # 输入完成后再验证（而非实时）

def validate_input(value):
    if value < 0:
        return 0.0  # 自动修正为最小值
    return value

spinbox.valueFromText = lambda text: validate_input(float(text))

高级用法：自定义步长逻辑

根据当前值动态调整步长（如对数刻度）：

def dynamic_step(value):
    if value < 1.0:
        return 0.1
    elif value < 10.0:
        return 0.5
    else:
        return 1.0

spinbox.setSingleStep(0.1)  # 初始步长

def on_step_up():
    current = spinbox.value()
    step = dynamic_step(current)
    spinbox.setValue(current + step)

def on_step_down():
    current = spinbox.value()
    step = dynamic_step(current)
    spinbox.setValue(current - step)

# 替换默认的上下箭头行为
spinbox.stepUp.connect(on_step_up)
spinbox.stepDown.connect(on_step_down)