QSpinBox Class
QSpinBox 类提供了一个旋转框控件。更多内容...
| 头文件： | #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() 处理，也不包含首尾空格）。
通常，除了数值范围之外，还希望为用户提供一个特殊的（通常是默认的）选项。有关如何在 QSpinBox 中实现这一点，请参阅setSpecialValueText()。
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 : 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 时，都会调用此虚拟函数。默认实现返回一个字符串，其中包含value ，该字符串使用QWidget::locale()和toString()以标准格式打印，但除非设置了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()。
© 2026 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.
