Qt QSpinBox 总结

Qt5 QSpinBox 总结

1. 基本特性

• 用途：用于输入和调整整数值，支持通过上下箭头、键盘输入或编程方式修改值。

• 默认范围：0 到 99，可通过 setRange(min, max) 自定义。

• 步长控制：setSingleStep(step) 设置单步增减值（默认为1）。

• 前缀/后缀：支持通过 setPrefix() 和 setSuffix() 添加文本（如 $ 或 px），仅用于显示，不影响实际值。

• 进制显示：支持十进制（默认）、十六进制（setDisplayIntegerBase(16)）、二进制等。

2. 核心方法

方法	说明
value() / setValue(int)	获取或设置当前值。
minimum() / maximum()	获取最小/最大值。
setRange(int min, int max)	同时设置最小值和最大值。
setSingleStep(int step)	设置单步增减步长。
setPrefix(const QString&)	设置数值前显示的前缀（如 $）。
setSuffix(const QString&)	设置数值后显示的后缀（如 px）。
setWrapping(bool enable)	启用/禁用循环（达到极值后绕回）。
setAccelerated(bool enable)	启用加速（长按箭头时快速增减值）。

---

3. 关键信号

---

信号	说明
valueChanged(int)	值变化时触发，传递新整数值。
textChanged(const QString&)	文本（含前缀/后缀）变化时触发。

---

4. 样式定制

• QSS 示例：

QSpinBox {
    border: 2px solid #3498db;
    border-radius: 5px;
    padding: 5px;
}
QSpinBox::up-button { /* 上箭头样式 */ }
QSpinBox::down-button { /* 下箭头样式 */ }

---

5. 子类化与自定义

• 输入验证：覆盖 validate() 和 valueFromText() 实现自定义格式（如带单位的输入）。

• 事件处理：重写 keyPressEvent() 或 wheelEvent() 修改默认交互逻辑。

6. 注意事项

• 输入过滤：自动过滤非数字字符，用户无需手动处理。

• 键盘交互：

  上下箭头键：按步长调整值。

  PageUp/PageDown：按步长×10调整值。

• 值与显示分离：value() 始终返回整数，前缀/后缀仅用于显示。

• 信号选择：优先用 valueChanged(int) 避免处理文本解析。

7. 典型应用场景

• 数值输入（如年龄、数量、尺寸）。

• 与 QSlider 联动，实现双向数据绑定。

• 参数配置界面（如字体大小、颜色通道值）。

8. 示例代码

// 创建 QSpinBox 并设置属性
QSpinBox *spinBox = new QSpinBox;
spinBox->setRange(0, 100);          // 范围 0~100
spinBox->setSingleStep(5);          // 步长5
spinBox->setPrefix("$ ");           // 显示 "$ 数值"
spinBox->setValue(50);              // 初始值

// 连接信号
connect(spinBox, QOverload<int>::of(&QSpinBox::valueChanged), 
        [](int val) { qDebug() << "Value:" << val; });