QScrollBar

定义

QScrollBar是Qt框架QtWidgets模块中的一个控件类，作用是提供一个垂直方向或水平方向的滚动条，让用户访问比用于显示它的部件更大的文档或内容区域^[1]。它同时给出一个视觉指示，说明用户当前处在文档的什么位置，以及可见部分在整体中占多大比例^[3]。

该类在头文件QScrollBar中声明，继承自QAbstractSlider，而QAbstractSlider又继承自QWidget，因此它是标准部件体系中的一员^[1]。QScrollBar本身提供的成员函数很少，取值范围、步长、当前值等核心状态都来自基类，它的主要工作集中在绘制和鼠标交互上^[1]。

在使用场景上，如果只是想把另一个部件放进可滚动视图，通常用QScrollArea更方便，因为它自带视口部件和滚动条；只有在为使用QAbstractScrollArea的专用部件实现类似功能，例如派生QAbstractItemView时，直接使用QScrollBar才有意义^[1]。若需求只是在一个范围内取值，QSlider往往是更合适的选择^[1]。

原理

滚动条在结构上由若干子控件组成，通常包括滑块、两端的滚动箭头和页面控件（即滑块滑动的背景区域）^[1]。滑块用于快速跳到文档的任意位置，但不适合在大文档中做精细定位；滚动箭头是可按按钮，用于精确移动一个“行”，在编辑器和列表框中一行即一行文字，在图像查看器中则可能是20像素；在页面控件区域单击，会把滚动条朝点击方向移动一个“页面”，该值通常与滑块长度相同^[3]。

每个滚动条都持有一个整数值，表示滑块距离滚动条起点有多远，用value()读取、用setValue()设置，取值范围由minimum()到maximum()闭区间限定，可通过setMinimum()和setMaximum()调整^[1]。在最小值时，垂直滚动条滑块的上边缘（水平滚动条的左边缘）位于滚动条顶端（或左端）；在最大值时，滑块的下边缘（或右边缘）位于底端（或右端）^[1]。

步长决定按键或点击时数值变化的幅度：页面步长是按下Page Up、Page Down时值改变的量，由setPageStep()设置；更小的行步长变化由光标键触发，用setSingleStep()设置^[1]。由于滑块长度需要计入，滚动条的取值范围往往与QSlider的确定方式不同：若文档有100行而部件一次只能显示20行，可以构造页面步长为20、最小值0、最大值80的滚动条，相当于分成5个页面，此时存在关系 $文档长度 = maximum() - minimum() + pageStep()$^[1]。

滚动条的取值范围与部件实际像素尺寸相互独立，选择范围和页面步长时不需要考虑部件的物理大小^[3]。数值变化和用户操作通过信号对外通知：valueChanged()在值改变时发出，是否在拖动过程中持续发出取决于tracking()属性；rangeChanged()在范围改变时发出；sliderPressed()、sliderMoved()、sliderReleased()分别对应用户按下、拖动、释放滑块；actionTriggered()则在滚动条因用户交互或triggerAction()调用而变动时发出^[1]。

在滚动区域中，QAbstractScrollArea默认已经提供水平与垂直两个滚动条，自定义时可以替换或调整它们^[2]。典型做法是在视口尺寸或内容尺寸变化时，把页面步长设为视口对应边长，把范围设为内容尺寸与视口尺寸之差，例如垂直滚动条调用setPageStep(areaSize.height())与setRange(0, widgetSize.height() - areaSize.height())，之后在scrollContentsBy()中根据滚动条的值重新定位或重绘内容^[2]。QAbstractScrollArea还允许通过addScrollBarWidget()在滚动条旁边添加附属部件，通过setCornerWidget()设置两个滚动条交角处的部件^[2]。

发展历程

早期Qt中滚动条的实现方式与后来的版本不同。在Qt 3时期的文档中，QScrollBar自身的函数很少，主要依赖QRangeControl提供范围控制能力，常用接口包括setValue()、setSteps()、setRange()以及addPage()、subtractPage()等模拟点击的函数，并提供valueChanged()、nextLine()、prevLine()、nextPage()、prevPage()等信号^[4]。

到Qt 4时期，QScrollBar的继承关系改为QAbstractSlider，该类被设计为QScrollBar、QSlider和QDial等滑块类部件的共同父类。这一版本中，滚动条的整数值范围、单步、页面步长、跟踪、反转外观等属性集中定义在QAbstractSlider中，信号集合也由基类统一提供。

进入Qt 5、Qt 6之后，QScrollBar作为基本部件类的位置保持不变，仍列在Qt Widgets的基本部件列表中，与QCheckBox、QComboBox、QSlider等并列^[5]。Qt 6.10为该类新增了createStandardContextMenu()方法，借鉴QLineEdit的同名设计，使开发者可以取得内置的右键菜单并追加自定义动作，而不必重写整个菜单逻辑^[1][6]。

应用

QScrollBar最常见的存在方式是作为滚动区域的组成部分被间接使用。QTextEdit、QTextBrowser、QPlainTextEdit、QScrollArea、QListView、QTableView、QTreeView、QGraphicsView等大批部件都继承自QAbstractScrollArea，因而默认带有水平和垂直滚动条，可通过horizontalScrollBar()与verticalScrollBar()取得^[7]。

开发者可以取出默认滚动条后直接改属性或连接信号，例如把singleStep设为50以实现每次滚动50像素，或连接valueChanged()以在滚动发生时执行自定义处理^[8]。若需要完全自定义的滚动条，则可以用setHorizontalScrollBar()或setVerticalScrollBar()替换原有滚动条，新滚动条会继承前一滚动条的滑块属性，替换时需注意为新对象设置正确的父对象，以便由滚动区域接管其生命周期^[2]。

外观定制通常通过Qt样式表完成，针对QScrollBar可以分别设置QScrollBar:vertical的宽度、QScrollBar:horizontal的高度、handle滑块的背景与圆角，以及add-line、sub-line等子控件^[9]。需要注意滚动条与QSlider的样式表语法略有差异，把滑块样式误用于滚动条可能导致效果不生效^[10]。

QScrollBar也用于演示和教学场景，Qt自带示例把QSlider、QScrollBar和QDial组合成自定义部件，演示三者因共享QAbstractSlider大部分功能而在理论上可以互相替换，差别只在外观与手感，以及如何用信号与槽同步多个控件的行为^[11]。

局限

QScrollBar只支持整数范围，不提供浮点取值能力^[1]。这意味着需要连续小数值的场景无法直接借它表达。

尽管QScrollBar本身能处理很大的数字，但在当前屏幕上，滚动条无法有效表示大约10万像素以上的范围；超过这个量级后，用户用键盘或鼠标都难以控制滑块，滚动箭头的作用也会变得有限^[1]。

默认情况下滚动条的focusPolicy()为Qt::NoFocus，即不参与键盘焦点链，必须调用setFocusPolicy()才能启用键盘交互^[1]。键盘行为也有其特殊性：对于水平和垂直滚动条，按键绑定默认是反向的，PageDown增加当前值而PageUp减小它^[11]。

此外，反转外观等属性的效果依赖具体样式是否支持。对于滚动条，子控件的视觉表现取决于样式是否理解反转外观，大多数样式会忽略滚动条的这一属性。样式表定制同样存在边界：如果在父部件上设置了样式表，子部件往往无法恢复原生外观，通常需要把样式表直接作用在目标滚动条上，或用对象名选择器限定作用范围^[12]。

参见

• QAbstractSlider —— QScrollBar的直接父类，提供取值范围、步长、当前值等核心属性与信号。

• QScrollArea —— 对任意部件提供滚动视图的高级容器，内部自带视口与滚动条。

• QAbstractScrollArea —— 滚动区域的底层抽象，默认创建并管理水平和垂直两个滚动条。

• QSlider —— 同属QAbstractSlider的滑块部件，用于在给定范围内取值。

• QWidget —— Qt中所有用户界面对象的基类，QScrollBar经QAbstractSlider间接继承自它。

• Qt —— QScrollBar所属的跨平台应用程序开发框架。