QSpinBox Class
QSpinBox 类提供了一个自旋框 widget。更多
| 头文件： | #include <QSpinBox> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承： | QAbstractSpinBox |
属性
|
|
公共功能
| QSpinBox(QWidget *parent = nullptr) | |
| virtual | ~QSpinBox() |
| QString | cleanText() const |
| int | displayIntegerBase() const |
| int | maximum() const |
| int | minimum() const |
| QString | prefix() const |
| void | setDisplayIntegerBase(int base) |
| void | setMaximum(int max) |
| void | setMinimum(int min) |
| void | setPrefix(const QString &prefix) |
| void | setRange(int minimum, int maximum) |
| void | setSingleStep(int val) |
| void | setStepType(QAbstractSpinBox::StepType stepType) |
| void | setSuffix(const QString &suffix) |
| int | singleStep() const |
| QAbstractSpinBox::StepType | stepType() const |
| QString | suffix() const |
| int | value() const |
公共插槽
| void | setValue(int val) |
信号
| void | textChanged(const QString &text) |
| void | valueChanged(int i) |
受保护函数
| virtual QString | textFromValue(int value) const |
| virtual int | valueFromText(const QString &text) const |
重新实现的受保护函数
| virtual bool | event(QEvent *event) override |
| virtual void | fixup(QString &input) const override |
| virtual QValidator::State | validate(QString &text, int &pos) const override |
详细说明
QSpinBox 设计用于处理整数和离散值集（如月份名称）；对于浮点数值，请使用QDoubleSpinBox 。
QSpinBox 允许用户通过单击向上/向下按钮或按键盘上的向上/向下键来选择一个值，以增加/减少当前显示的值。用户也可以手动输入数值。自旋框支持整数值，但可通过validate(),textFromValue() 和valueFromText() 扩展使用不同的字符串。
每当值发生变化时，QSpinBox 都会发出valueChanged() 和textChanged() 信号，前者提供一个 int 值，后者提供一个QString 值。textChanged() 信号提供prefix() 和suffix() 值。当前值可通过value() 获取，也可通过setValue() 设置。
单击向上/向下按钮或使用键盘加速器的向上和向下箭头将以singleStep() 为单位增加或减少当前值。如果想改变这种行为，可以重新实现虚拟函数stepBy() 。可以使用其中一个构造函数设置最小值、最大值和步长，之后还可以使用setMinimum(),setMaximum() 和setSingleStep() 进行更改。
大多数自旋框都是定向的，但 QSpinBox 也可以作为圆形自旋框运行，例如，如果范围是 0-99，当前值是 99，那么如果wrapping() 设置为 true，点击 "向上 "将得到 0。如果需要循环行为，请使用setWrapping() 。
显示的数值可以用任意字符串作为前缀或后缀，例如表示货币或度量单位。请参阅setPrefix() 和setSuffix()。自旋框中的文本可通过text() （包括任何prefix() 和suffix() ）或cleanText() （没有prefix() 和suffix() ，也没有前导或尾部空白）获取。
除了数值范围外，通常还需要给用户一个特殊的（通常是默认的）选择。请参阅setSpecialValueText() 了解如何使用 QSpinBox 实现这一点。
子类化 QSpinBox
如果使用prefix()、suffix() 和specialValueText() 无法提供足够的控制，您可以子类化 QSpinBox 并重新实现valueFromText() 和textFromValue()。例如，下面是允许用户输入图标大小（如 "32 x 32"）的自定义旋转框的代码：
int IconSizeSpinBox::valueFromText(const QString &text) const { static const QRegularExpression regExp(tr("(\\d+)(\\s*[xx]\\s*\\d+)?")); Q_ASSERT(regExp.isValid()); const QRegularExpressionMatch match = regExp.match(text); if (match.isValid()) return match.captured(1).toInt(); return 0; } QString IconSizeSpinBox::textFromValue(int value) const { return tr("%1 x %1").arg(value); }
另请参阅 QDoubleSpinBox,QDateTimeEdit,QSlider 和旋转框示例。
属性文档
[read-only] cleanText : const QString
该属性保存自旋框的文本，不包括任何前缀、后缀、前导或尾部空白。
访问功能：
| QString | cleanText() const |
另请参阅 text,QSpinBox::prefix, 和QSpinBox::suffix 。
displayIntegerBase : int
该属性用于保存显示旋转框值的基数
默认 displayIntegerBase 值为 10。
访问函数：
| int | displayIntegerBase() const |
| void | setDisplayIntegerBase(int base) |
另请参阅 textFromValue() 和valueFromText()。
maximum : int
该属性保存旋转框的最大值。
设置该属性时，如有必要，会调整最小值，以确保范围保持有效。
默认最大值为 99。
访问功能：
| int | maximum() const |
| void | setMaximum(int max) |
另请参见 setRange() 和specialValueText 。
minimum : int
该属性用于保存自旋框的最小值。
设置该属性时，如有必要，maximum ，以确保范围保持有效。
默认最小值为 0。
访问函数：
| int | minimum() const |
| void | setMinimum(int min) |
另请参阅 setRange() 和specialValueText 。
prefix : QString
此属性保存自旋框的前缀
前缀会被添加到显示值的开头。典型用途是显示计量单位或货币符号。例如
sb->setPrefix("$");
要关闭前缀显示，请将此属性设置为空字符串。默认为无前缀。当设置value() ==minimum() 和specialValueText() 时，不显示前缀。
如果未设置前缀，prefix() 将返回空字符串。
访问函数：
| QString | prefix() const |
| void | setPrefix(const QString &prefix) |
另请参阅 suffix()、setSuffix()、specialValueText() 和setSpecialValueText()。
singleStep : int
该属性保存步长值
当用户使用箭头更改旋转框的值时，该值将按 singleStep 的值递增或递减。默认值为 1。设置的 singleStep 值小于 0 时，将不起任何作用。
访问功能：
| int | singleStep() const |
| void | setSingleStep(int val) |
stepType : StepType
该属性包含步长类型。
步长类型可以是单步长或自适应十进制步长。
访问函数：
| QAbstractSpinBox::StepType | stepType() const |
| void | setStepType(QAbstractSpinBox::StepType stepType) |
suffix : QString
该属性保存自旋框的后缀
后缀会附加到显示值的末尾。典型用途是显示计量单位或货币符号。例如
sb->setSuffix(" km");
要关闭后缀显示，请将此属性设置为空字符串。默认为无后缀。如果设置了specialValueText() ，则不显示minimum() 的后缀。
如果未设置后缀，则 suffix() 返回空字符串。
访问函数：
| QString | suffix() const |
| void | setSuffix(const QString &suffix) |
另请参阅 prefix()、setPrefix()、specialValueText() 和setSpecialValueText()。
value : int
此属性保存自旋框的值
如果新值与旧值不同，setValue() 将发出valueChanged() 信号。value 属性有第二个通知信号，其中包括自旋框的前缀和后缀。
访问函数：
| int | value() const |
| void | setValue(int val) |
通知信号：
| void | valueChanged(int i) |
成员函数文档
[explicit] QSpinBox::QSpinBox(QWidget *parent = nullptr)
构造一个以 0 为最小值、99 为最大值、步长值为 1 的自旋框。初始值设置为 0。它的父对象是parent 。
另请参阅 setMinimum()、setMaximum() 和setSingleStep()。
[virtual noexcept] QSpinBox::~QSpinBox()
毁灭者
[override virtual protected] bool QSpinBox::event(QEvent *event)
重实现：QAbstractSpinBox::event(QEvent *event).
[override virtual protected] void QSpinBox::fixup(QString &input) const
重实现：QAbstractSpinBox::fixup(QString &input) const.
void QSpinBox::setRange(int minimum, int maximum)
方便函数，通过一次函数调用设置minimum, 和maximum 值。
setRange(minimum, maximum);
等价于：
setMinimum(minimum); setMaximum(maximum);
void QSpinBox::setStepType(QAbstractSpinBox::StepType stepType)
将自旋框的步长类型设置为stepType ，即单步或自适应十进制步长。
自适应十进制步长是指步长将持续调整为低于当前value 的十次幂。因此，当数值为 1100 时，步长设置为 100，所以上调一次步长就会增加到 1200。如果数值为 1200，则步长为 1300。对于负值，从 -1100 向下步进到 -1200。
在处理边缘情况时会考虑步进方向，因此从 100 开始向下步进时，数值会变为 99，而不是 90。因此，上一步后再下一步，或反之亦然，都会落在起始值上；99 -> 100 -> 99。
设置该值将导致旋转方框忽略singleStep 的值，不过该值会被保留，因此如果后来关闭了自适应十进制步长，singleStep 也会生效。
注： 属性stepType 的设置函数。
另请参阅 stepType() 。
[signal] void QSpinBox::textChanged(const QString &text)
每当旋转框的文本发生变化时，就会发出该信号。新文本通过prefix() 和suffix() 传入text 。
[virtual protected] QString QSpinBox::textFromValue(int value) const
只要自旋框需要显示给定的value ，就会使用该虚拟函数。默认实现将返回一个字符串，其中包含以QWidget::locale().toString() 的标准方式打印的value ，但除非设置了setGroupSeparatorShown()，否则千位分隔符将被移除。重新实现可以返回任何内容。(请参阅详细说明中的示例）。
注意：QSpinBox 不会调用specialValueText() 的函数，返回值中不应包含prefix() 或suffix()。
如果重新实现该函数，可能还需要重新实现valueFromText() 和validate()
另请参阅 valueFromText()、validate() 和QLocale::groupSeparator()。
[override virtual protected] QValidator::State QSpinBox::validate(QString &text, int &pos) const
重实现：QAbstractSpinBox::validate(QString &input, int &pos) const.
[signal] void QSpinBox::valueChanged(int i)
每当自旋框的值发生变化时，就会发出该信号。新值的整数值在i 中传递。
注： 属性value 的通知信号。
[virtual protected] int QSpinBox::valueFromText(const QString &text) const
当旋转框需要将用户输入的text 解释为数值时，就会使用这个虚拟函数。
需要以非数字方式显示自旋框数值的子类需要重新实现此函数。
注意：QSpinBox 会单独处理specialValueText() ；本函数只涉及其他值。
另请参阅 textFromValue() 和validate()。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
