QScrollBar Class
QScrollBar widget 提供垂直或水平滚动条。更多
| 标题 | #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() |
重新实现的公共函数
保护函数
| 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 |
详细说明
滚动条是一种控件，可让用户访问比用于显示的 widget 更大的文档部分。它可以直观地显示用户在文档中的当前位置以及文档的可视面积。滚动条通常还配有其他控件，以实现更精确的导航。Qt 以适合每个平台的方式显示滚动条。
如果您需要在其他部件上提供滚动视图，使用QScrollArea 类可能更方便，因为该类提供了视口部件和滚动条。如果您需要使用QAbstractScrollArea 为专门的 widget 实现类似功能，例如，如果您决定子类化QAbstractItemView ，那么 QScrollBar 将非常有用。对于使用滑块控件获取给定范围内数值的大多数其他情况，QSlider 类可能更适合您的需要。
| 滚动条通常包括四个独立控件：滑块、滚动箭头和页面控件。
|
每个滚动条都有一个值，表示滑块距离滚动条起点的距离；该值可通过value() 获得，也可通过setValue() 设置。该值始终位于为滚动条定义的值范围内，即从minimum() 到maximum() （包括 () 和 () ）。可接受的数值范围可通过setMinimum() 和setMaximum() 设置。在最小值时，滑块的顶部边缘（垂直滚动条）或左侧边缘（水平滚动条）将位于滚动条的顶部（或左侧）。在最大值时，滑块的底部（或右侧）边缘将位于滚动条的底部（或右侧）。
滑块的长度通常与页面步长的值有关，通常代表滚动视图中显示的文档区域的比例。页面步长是用户按下Page Up 和Page Down 键时数值的变化量，用setPageStep() 设置。使用光标键可以对行步长定义的值进行较小的更改，这个量通过setSingleStep() 进行设置。
请注意，使用的数值范围与滚动条 widget 的实际大小无关。在选择范围和页面步长值时，无需考虑这一点。
为滚动条指定的数值范围通常与QSlider 的数值范围不同，因为需要考虑滑块的长度。如果文档有 100 行，而我们只能在 widget 中显示 20 行，那么我们可能希望构建一个页面步长为 20、最小值为 0、最大值为 80 的滚动条。这样，我们就可以得到一个有五个 "页面 "的滚动条。
 | 在许多常见情况下，文档长度、滚动条的取值范围和页面步长之间的关系都很简单。从某个代表文档长度的值中减去选定的页面步长，就可以确定滚动条的取值范围。在这种情况下，以下等式非常有用：文档长度=maximum() -minimum() +pageStep() 。 |
QScrollBar 只提供整数范围。需要注意的是，虽然 QScrollBar 可以处理非常大的数字，但在当前屏幕上，滚动条无法有效表示超过约 100,000 像素的范围。超过这个范围后，用户就很难使用键盘或鼠标控制滑块，滚动箭头的作用也很有限。
ScrollBar 从QAbstractSlider 继承了一整套信号：
- valueChanged(当滚动条的值发生变化时，（）就会发出信号。跟踪（）决定是否在用户交互时发出该信号。
- rangeChanged() 在滚动条的值范围发生变化时发出。
- sliderPressed(当用户开始拖动滑块时，（）将被触发。
- sliderMoved() 在用户拖动滑块时发出。
- sliderReleased(当用户释放滑块时，将发出（）。
- actionTriggered(当用户交互或通过triggerAction() 函数改变滚动条时，会发出（）。
滚动条可由键盘控制，但其默认focusPolicy() 为Qt::NoFocus 。使用setFocusPolicy() 可启用键盘与滚动条的交互：
- 向左/向右移动水平滚动条一步。
- 上/下移动垂直滚动条一步。
- PageUp 上移一页。
- 下一页向下移动一页。
- 首页移动到起点（最小值）。
- 终点移动到终点（最大值）。
滑块本身可以通过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).
[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)。
© 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.
