Back to Qt.io
Contact Us Blog Download Qt

QScrollArea Class

QScrollArea 类可在另一个 widget 上提供滚动视图。更多

Header： #include <QScrollArea>
CMake： find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake： QT += widgets
继承： QAbstractScrollArea

属性

公共函数

QScrollArea(QWidget *parent = nullptr)
virtual ~QScrollArea()
Qt::Alignment alignment() const
void ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50)
void ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50)
void setAlignment(Qt::Alignment)
void setWidget(QWidget *widget)
void setWidgetResizable(bool resizable)
QWidget *takeWidget()
QWidget *widget() const
bool widgetResizable() const

重新实现的公共函数

virtual bool focusNextPrevChild(bool next) override
virtual QSize sizeHint() const override

重新实现的受保护函数

virtual bool event(QEvent *e) override
virtual bool eventFilter(QObject *o, QEvent *e) override
virtual void resizeEvent(QResizeEvent *) override
virtual void scrollContentsBy(int dx, int dy) override
virtual QSize viewportSizeHint() const override

详细说明

滚动区域用于显示框架内子窗口部件的内容。如果 widget 超过了框架的大小，视图可以提供滚动条，以便查看子 widget 的整个区域。必须使用setWidget() 指定子 widget。例如

QLabel *imageLabel = new QLabel;
QImage image("happyguy.png");
imageLabel->setPixmap(QPixmap::fromImage(image));

scrollArea = new QScrollArea;
scrollArea->setBackgroundRole(QPalette::Dark);
scrollArea->setWidget(imageLabel);

上面的代码创建了一个包含图片标签的滚动区域（如下图所示）。当缩放图片时，滚动区域可以提供必要的滚动条：

滚动条的外观取决于当前设置的scroll bar policies 。您可以使用从QAbstractScrollArea 继承的功能来控制滚动条的外观。

例如，可以设置QAbstractScrollArea::horizontalScrollBarPolicy 和QAbstractScrollArea::verticalScrollBarPolicy 属性。或者，如果希望滚动条在滚动区域的内容发生变化时进行动态调整，可以使用horizontalScrollBar() 和verticalScrollBar() 函数（可以访问滚动条），并在滚动区域的内容发生变化时使用QScrollBar::setValue() 函数设置滚动条的值。

您可以使用widget() 函数检索子窗口部件。使用setWidgetResizable() 函数可以调整视图的大小。可以使用setAlignment() 指定部件的对齐方式。

两个方便的函数ensureVisible() 和ensureWidgetVisible() 可以确保在视口中看到一定区域的内容，必要时还可以滚动内容。

尺寸提示和布局

使用滚动区域显示自定义 widget 的内容时，必须确保子 widget 的size hint 设置为合适的值。如果子 widget 使用的是标准QWidget ，则可能需要调用QWidget::setMinimumSize() 以确保在滚动区域内正确显示 widget 的内容。

如果滚动区域用于显示包含在布局中排列的子窗口部件的窗口部件的内容，则必须认识到布局的大小策略也将决定窗口部件的大小。如果打算动态更改布局的内容，了解这一点尤其有用。在这种情况下，如果将布局的size constraint 属性设置为对布局的最小和/或最大尺寸有限制的属性（如QLayout::SetMinAndMaxSize ），那么每当布局的内容发生变化时，滚动区域的尺寸就会随之更新。

另请参阅 QAbstractScrollArea 和QScrollBar 。

属性文档

alignment : Qt::Alignment

该属性用于保存滚动区域窗口部件的对齐方式。

有效的对齐方式是以下标志的组合：

  • Qt::AlignLeft
  • Qt::AlignHCenter
  • Qt::AlignRight
  • Qt::AlignTop
  • Qt::AlignVCenter
  • Qt::AlignBottom

默认情况下，窗口小部件扎根于滚动区域的左上角。

访问功能：

Qt::Alignment alignment() const
void setAlignment(Qt::Alignment)

widgetResizable : bool

此属性表示滚动区域是否应调整视图窗口部件的大小。

如果该属性设置为 false（默认值），滚动区域将保持其窗口部件的大小。无论该属性如何，您都可以使用widget()->resize() 以编程方式调整窗口部件的大小，滚动区域会自动调整到新的大小。

如果该属性设置为 true，滚动区域将自动调整 widget 的大小，以避免出现滚动条，或利用额外空间。

访问函数

bool widgetResizable() const
void setWidgetResizable(bool resizable)

成员函数文档

[explicit] QScrollArea::QScrollArea(QWidget *parent = nullptr)

用给定的parent 构建一个空的滚动区域。

另请参阅 setWidget() 。

[virtual noexcept] QScrollArea::~QScrollArea()

销毁滚动区域及其子 widget。

另请参见 setWidget()。

void QScrollArea::ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50)

滚动滚动区域的内容，使点（x,y ）在视口区域内可见，边距由xmargin 和ymargin 以像素为单位指定。如果无法到达指定的点，则将内容滚动到最近的有效位置。两个边距的默认值都是 50 像素。

void QScrollArea::ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50)

QScrollArea::widget滚动滚动区域的内容，使childWidget () 在视口中可见，边距由xmargin 和ymargin 以像素为单位指定。如果无法到达指定点，则将内容滚动到最近的有效位置。两个边距的默认值都是 50 像素。

[override virtual protected] bool QScrollArea::event(QEvent *e)

重实现：QAbstractScrollArea::event(QEvent *event).

[override virtual protected] bool QScrollArea::eventFilter(QObject *o, QEvent *e)

重实现：QObject::eventFilter(QObject *watched, QEvent *event).

[override virtual] bool QScrollArea::focusNextPrevChild(bool next)

重实现：QWidget::focusNextPrevChild(bool next）。

[override virtual protected] void QScrollArea::resizeEvent(QResizeEvent *)

重实现：QAbstractScrollArea::resizeEvent(QResizeEvent *event).

[override virtual protected] void QScrollArea::scrollContentsBy(int dx, int dy)

重实现：QAbstractScrollArea::scrollContentsBy(int dx, int dy）。

void QScrollArea::setWidget(QWidget *widget)

设置滚动区域的widget 。

widget 将成为滚动区域的子区域，并在删除滚动区域或设置新 widget 时销毁。

Widget 的autoFillBackground 属性将设置为true 。

如果在添加widget 时滚动区域是可见的，则必须明确地show() 它。

请注意，必须在调用此函数之前添加widget 的布局；如果稍后才添加，则无论何时show() 滚动区域，widget 都将不可见。在这种情况下，您也可以在之后不show()widget 。

另请参见 widget()。

[override virtual] QSize QScrollArea::sizeHint() const

重实现：QAbstractScrollArea::sizeHint() const.

QWidget *QScrollArea::takeWidget()

删除滚动区域的 widget，并将该 widget 的所有权传递给调用者。

另请参见 widget()。

[override virtual protected] QSize QScrollArea::viewportSizeHint() const

重实现：QAbstractScrollArea::viewportSizeHint() const.

QWidget *QScrollArea::widget() const

返回滚动区域的 widget，如果没有，则返回nullptr 。

另请参阅 setWidget().

© 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.