QAbstractSpinBox类详细介绍

QAbstractSpinBox 是 PyQt5 中所有数值调节控件（如 QSpinBox、QDoubleSpinBox）的抽象基类，定义了数值输入和调节的核心功能。它提供了一套统一的接口和信号，支持整数、浮点数、日期等多种数据类型的输入，并允许自定义步长、范围、格式和验证逻辑。以下是详细介绍及常用方法：

一、核心功能

• ​数值调节：通过上下箭头按钮或键盘增减数值。
• ​范围限制：设置最小/最大值约束。
• ​输入验证：校验用户输入是否符合格式要求。
• ​自定义显示：支持前缀、后缀、特殊文本（如"无"）。
• ​步长控制：定义单步增减的幅度（如每次增减1或0.1）。
• ​键盘交互：支持方向键、PageUp/PageDown 等快捷操作。

二、常用方法

​1. 数值操作

方法	说明	示例
setValue(value)	设置当前值	spinbox.setValue(50)
value() -> Any	获取当前值	current_val = spinbox.value()
setMinimum(min)	设置最小值	spinbox.setMinimum(0)
setMaximum(max)	设置最大值	spinbox.setMaximum(100)
setRange(min, max)	同时设置最小和最大值	spinbox.setRange(0, 100)
setSingleStep(step)	设置单步增减幅度	spinbox.setSingleStep(5)
setAccelerated(enable)	启用加速（长按箭头时快速增减）	spinbox.setAccelerated(True)

​2. 显示与格式

方法	说明	示例
setPrefix(prefix: str)	设置前缀文本（如"$"）	spinbox.setPrefix("$")
setSuffix(suffix: str)	设置后缀文本（如"℃"）	spinbox.setSuffix("℃")
setSpecialValueText(text: str)	设置最小值时的特殊显示文本	spinbox.setSpecialValueText("无")
setButtonSymbols(symbols: QAbstractSpinBox.ButtonSymbols)	设置按钮符号（如隐藏箭头）	spinbox.setButtonSymbols(QAbstractSpinBox.NoButtons)

​3. 输入与验证

方法	说明	示例
setReadOnly(enable: bool)	设为只读模式	spinbox.setReadOnly(True)
setKeyboardTracking(enable: bool)	启用键盘输入实时跟踪	spinbox.setKeyboardTracking(False)
setCorrectionMode(mode: QAbstractSpinBox.CorrectionMode)	设置输入修正模式	spinbox.setCorrectionMode(QAbstractSpinBox.CorrectToNearestValue)
validate(text: str, pos: int) -> Tuple[QValidator.State, str, int]	验证输入文本（需子类实现）	-
fixup(text: str) -> str	修正输入文本（需子类实现）	-

​4. 信号

信号	说明
valueChanged(value: Any)	数值改变时触发
editingFinished()	编辑完成（焦点离开或按下回车）时触发

---

​三、代码示例

​1. 基础用法（以 QSpinBox 为例）​

python

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

class Demo(QWidget):
    def __init__(self):
        super().__init__()
        layout = QVBoxLayout(self)
        
        # 创建 QSpinBox（QAbstractSpinBox 的子类）
        self.spinbox = QSpinBox()
        self.spinbox.setRange(0, 100)          # 范围 0~100
        self.spinbox.setPrefix("价格: ")        # 前缀
        self.spinbox.setSuffix(" 元")           # 后缀
        self.spinbox.setSingleStep(5)          # 步长 5
        self.spinbox.valueChanged.connect(self.on_value_changed)
        
        layout.addWidget(self.spinbox)
        self.resize(300, 150)

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

app = QApplication([])
window = Demo()
window.show()
app.exec_()

​2. 自定义验证逻辑（继承 QAbstractSpinBox）​

python

from PyQt5.QtWidgets import QAbstractSpinBox
from PyQt5.QtCore import Qt, QRegExp
from PyQt5.QtGui import QRegExpValidator

class HexSpinBox(QAbstractSpinBox):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setRange(0, 255)
        regex = QRegExp(r"[0-9A-Fa-f]{1,2}")  # 匹配1~2位十六进制数
        self.validator = QRegExpValidator(regex)
        self.lineEdit().setValidator(self.validator)

    def validate(self, text, pos):
        return self.validator.validate(text, pos)

    def value(self):
        text = self.text()
        return int(text, 16) if text else 0

    def setValue(self, value):
        self.lineEdit().setText(f"{value:02X}")  # 显示为两位大写十六进制

    def stepBy(self, steps):
        # 实现步进逻辑
        current = self.value()
        new_val = max(0, min(255, current + steps))
        self.setValue(new_val)

    def stepEnabled(self):
        # 始终允许上下调整
        return QAbstractSpinBox.StepUpEnabled | QAbstractSpinBox.StepDownEnabled

---

​四、注意事项

1. ​抽象基类：
   QAbstractSpinBox 不能直接实例化，必须通过子类（如 QSpinBox）或自定义继承类使用。

2. ​输入验证：
   自定义子类时需重写 validate() 和 fixup() 方法，确保输入合法性。

3. ​本地化支持：
   数值格式（如千位分隔符）需结合 QLocale 处理不同地区的显示。

4. ​性能优化：
   若数值范围较大且频繁更新，建议禁用 keyboardTracking 以减少信号触发次数。

---

​五、子类对比

​子类	​数据类型	​典型场景
QSpinBox	整数	年龄、数量等整数值输入
QDoubleSpinBox	浮点数	价格、温度等小数输入
QDateTimeEdit	日期时间	日期和时间选择
QTimeEdit	时间	时间选择
QDateEdit	日期	日期选择

---

通过 QAbstractSpinBox，可以快速实现数值输入控件的核心功能，结合子类或自定义继承类，轻松满足复杂场景的需求！