PyQt QDoubleSpinBox控件用法详解

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)