QScrollBar Class
QScrollBar 控件提供垂直或水平的滚动条。更多内容...
| 标题： | #include <QScrollBar> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承自： | QAbstractSlider |
公共函数
| QScrollBar(QWidget *parent = nullptr) | |
| QScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr) | |
| virtual | ~QScrollBar() |
(since 6.10) QMenu * | createStandardContextMenu(QPoint position) |
重新实现的公共函数
受保护函数
| virtual void | initStyleOption(QStyleOptionSlider *option) const |
重新实现的受保护函数
| virtual void | contextMenuEvent(QContextMenuEvent *event) override |
| virtual void | hideEvent(QHideEvent *) override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | mousePressEvent(QMouseEvent *e) override |
| virtual void | mouseReleaseEvent(QMouseEvent *e) override |
| virtual void | paintEvent(QPaintEvent *) override |
| virtual void | sliderChange(QAbstractSlider::SliderChange change) override |
| virtual void | wheelEvent(QWheelEvent *event) override |
详细说明
滚动条是一种控件，它使用户能够访问超出显示该文档的小部件范围的文档部分。它以可视化方式显示用户在文档中的当前位置以及文档中可见的部分。 滚动条通常配有其他控件，以实现更精确的导航。Qt 会根据各平台的特点以适当的方式显示滚动条。
如果您需要在另一个控件上提供滚动视图，使用QScrollArea 类可能会更方便，因为它提供了视口控件和滚动条。 如果您需要使用QAbstractScrollArea 为专用控件实现类似功能，例如决定继承QAbstractItemView ，那么QScrollBar会非常有用。对于大多数其他使用滑块控件在给定范围内获取值的情况，QSlider 类可能更适合您的需求。
| 滚动条通常包含四个独立的控件：滑块、滚动箭头和分页控件。
|
每个滚动条都有一个值，用于指示滑块距离滚动条起点的距离；该值可通过value()获取，并通过setValue()设置。该值始终位于为滚动条定义的数值范围内，从minimum()到maximum()（包含两端）。 可接受的值范围可通过setMinimum() 和setMaximum() 进行设置。当值为最小值时，滑块的顶部边缘（对于垂直滚动条）或左侧边缘（对于水平滚动条）将位于滚动条的顶端（或左端）。 在最大值处，滑块的底部（或右侧）边缘将位于滚动条的底部（或右侧）末端。
滑块的长度通常与“页面步长”的值相关，通常代表滚动视图中显示的文档区域的比例。 页步长是指用户按下Page Up 和Page Down 键时值的变化量，可通过setPageStep()进行设置。使用光标键可对由行步长定义的值进行更小的调整，该量可通过setSingleStep()进行设置。
请注意，所使用的值范围与滚动条控件的实际大小无关。在选择范围和页步长值时，无需考虑这一点。
为滚动条指定的数值范围通常与QSlider 的设定方式不同，因为需要考虑滑块的长度。 如果有一个包含 100 行文档，而控件中只能显示 20 行，我们可能希望构建一个页步长为 20、最小值为 0、最大值为 80 的滚动条。这样，我们将得到一个包含五个“页”的滚动条。
 | 在许多常见情况下，文档长度、滚动条使用的值范围以及页步长之间的关系非常简单。 滚动条的值范围是通过从表示文档长度的某个值中减去选定的页步长来确定的。在这种情况下，以下公式很有用：文档长度= `maximum()` - `minimum()` + `pageStep()`。 |
QScrollBar 仅提供整数范围。请注意，尽管 QScrollBar 可以处理非常大的数值，但当前屏幕上的滚动条无法有效显示超过约 100,000 像素的范围。超过这个范围后，用户将难以通过键盘或鼠标控制滑块，且滚动箭头的实用性也会受到限制。
ScrollBar 从QAbstractSlider 继承了一套全面的信号：
- valueChanged() 在滚动条的值发生变化时发出。tracking 属性决定了在用户交互期间是否会发出此信号。
- rangeChanged() 在滚动条的数值范围发生变化时触发。
- sliderPressed() 在用户开始拖动滑块时触发。
- sliderMoved() 在用户拖动滑块时触发。
- sliderReleased() 在用户松开滑块时发出。
- actionTriggered() 是在滚动条因用户交互或通过triggerAction() 函数被更改时触发的。
滚动条可通过键盘控制，但其默认的focusPolicy()值为Qt::NoFocus 。使用setFocusPolicy()启用滚动条的键盘交互：
- 左右方向可将水平滚动条移动一个单位。
- 向上/向下键可使垂直滚动条移动一个单位。
- PageUp 向上滚动一页。
- PageDown 向下滚动一页。
- Home 键移动到起始位置（最小值）。
- End 键可移动到末尾（最大值）。
可以通过使用triggerAction()函数来模拟用户与滚动条控件的交互，从而控制滑块本身。如果有多个不同的控件使用相同的值范围，此方法非常有用。
大多数 GUI 样式都使用 `pageStep()` 的值来计算滑块的大小。
另请参阅 QScrollArea 、QSlider 、QDial 、QSpinBox 以及“滑块示例”。
成员函数文档
[explicit] QScrollBar::QScrollBar(QWidget *parent = nullptr)
创建一个垂直滚动条。
parent 参数将传递给QWidget 构造函数。
minimum 的默认值为0，maximum 的默认值为99，singleStep 的大小为1，pageStep 的大小为10，初始value 的值为0。
[explicit] QScrollBar::QScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr)
根据给定的orientation 创建一个滚动条。
parent 参数将传递给QWidget 构造函数。
minimum 的默认值为0，maximum 的默认值为99，singleStep 的大小为1，pageStep 的大小为10，初始value 为0。
[virtual noexcept] QScrollBar::~QScrollBar()
隐藏滚动条。
[override virtual protected] void QScrollBar::contextMenuEvent(QContextMenuEvent *event)
重写：QWidget::contextMenuEvent(QContextMenuEvent *event)。
显示由createStandardContextMenu() 创建的标准上下文菜单。
若不希望滚动条具有上下文菜单，可将其contextMenuPolicy 属性设置为Qt::NoContextMenu 。此外，样式也可通过SH_ScrollBar_ContextMenu提示来控制此行为。
若要自定义右键菜单，请重写此函数。若要扩展标准右键菜单，请重写此函数，调用createStandardContextMenu() 并扩展返回的菜单。可将返回的QMenu 存储起来以备后用，或设置 WA_DeleteOnClose 属性。
有关该事件的信息将通过event 对象传递。
[since 6.10] QMenu *QScrollBar::createStandardContextMenu(QPoint position)
创建标准上下文菜单，当用户用鼠标右键单击滚动条时会显示该菜单。该函数由默认的contextMenuEvent()处理程序调用，并接收position 对象，其中包含鼠标点击位置在该小部件本地坐标系中的坐标。弹出菜单的所有权将转移给调用方。
该函数于 Qt 6.10 版本中引入。
[override virtual] bool QScrollBar::event(QEvent *event)
重写了：QAbstractSlider::event(QEvent *e)。
[override virtual protected] void QScrollBar::hideEvent(QHideEvent *)
重写了：QWidget::hideEvent(QHideEvent *event)。
[virtual protected] void QScrollBar::initStyleOption(QStyleOptionSlider *option) const
使用QScrollBar 中的值初始化 `option `。当子类需要 `QStyleOptionSlider`，但又不想自己填写所有信息时，此方法非常有用。
另请参阅 QStyleOption::initFrom()。
[override virtual protected] void QScrollBar::mouseMoveEvent(QMouseEvent *e)
重写了：QWidget::mouseMoveEvent(QMouseEvent *event)。
[override virtual protected] void QScrollBar::mousePressEvent(QMouseEvent *e)
重写了：QWidget::mousePressEvent(QMouseEvent *event)。
[override virtual protected] void QScrollBar::mouseReleaseEvent(QMouseEvent *e)
重写了：QWidget::mouseReleaseEvent(QMouseEvent *event)。
[override virtual protected] void QScrollBar::paintEvent(QPaintEvent *)
重写了：QWidget::paintEvent(QPaintEvent *event)。
[override virtual] QSize QScrollBar::sizeHint() const
重新实现了属性QWidget::sizeHint 的访问函数。
[override virtual protected] void QScrollBar::sliderChange(QAbstractSlider::SliderChange change)
重写了：QAbstractSlider::sliderChange （QAbstractSlider::SliderChange change）。
[override virtual protected] void QScrollBar::wheelEvent(QWheelEvent *event)
重写了：QAbstractSlider::wheelEvent(QWheelEvent *e)。
© 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.
