QListView Class
QListView 类提供了一个基于模型的列表或图标视图。更多内容...
| 头文件: | #include <QListView> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| 继承自: | QAbstractItemView |
| 继承自: |
公共类型
| enum | Flow { LeftToRight, TopToBottom } |
| enum | LayoutMode { SinglePass, Batched } |
| enum | Movement { Static, Free, Snap } |
| enum | ResizeMode { Fixed, Adjust } |
| enum | ViewMode { ListMode, IconMode } |
属性
|
|
公共函数
| QListView(QWidget *parent = nullptr) | |
| virtual | ~QListView() |
| int | batchSize() const |
| void | clearPropertyFlags() |
| QListView::Flow | flow() const |
| QSize | gridSize() const |
| bool | isRowHidden(int row) const |
| bool | isSelectionRectVisible() const |
| bool | isWrapping() const |
| Qt::Alignment | itemAlignment() const |
| QListView::LayoutMode | layoutMode() const |
| int | modelColumn() const |
| QListView::Movement | movement() const |
| QListView::ResizeMode | resizeMode() const |
| void | setBatchSize(int batchSize) |
| void | setFlow(QListView::Flow flow) |
| void | setGridSize(const QSize &size) |
| void | setItemAlignment(Qt::Alignment alignment) |
| void | setLayoutMode(QListView::LayoutMode mode) |
| void | setModelColumn(int column) |
| void | setMovement(QListView::Movement movement) |
| void | setResizeMode(QListView::ResizeMode mode) |
| void | setRowHidden(int row, bool hide) |
| void | setSelectionRectVisible(bool show) |
| void | setSpacing(int space) |
| void | setUniformItemSizes(bool enable) |
| void | setViewMode(QListView::ViewMode mode) |
| void | setWordWrap(bool on) |
| void | setWrapping(bool enable) |
| int | spacing() const |
| bool | uniformItemSizes() const |
| QListView::ViewMode | viewMode() const |
| bool | wordWrap() const |
重新实现的公共函数
| virtual QModelIndex | indexAt(const QPoint &p) const override |
| virtual void | scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible) override |
| virtual void | setRootIndex(const QModelIndex &index) override |
| virtual QRect | visualRect(const QModelIndex &index) const override |
信号
| void | indexesMoved(const QModelIndexList &indexes) |
受保护函数
| QRect | rectForIndex(const QModelIndex &index) const |
| void | setPositionForIndex(const QPoint &position, const QModelIndex &index) |
重新实现的受保护函数
| virtual void | currentChanged(const QModelIndex ¤t, const QModelIndex &previous) override |
| virtual void | dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>()) override |
| virtual void | dragLeaveEvent(QDragLeaveEvent *e) override |
| virtual void | dragMoveEvent(QDragMoveEvent *e) override |
| virtual void | dropEvent(QDropEvent *event) override |
| virtual bool | event(QEvent *e) override |
| virtual int | horizontalOffset() const override |
| virtual void | initViewItemOption(QStyleOptionViewItem *option) const override |
| virtual bool | isIndexHidden(const QModelIndex &index) const override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | mouseReleaseEvent(QMouseEvent *e) override |
| virtual QModelIndex | moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override |
| virtual void | paintEvent(QPaintEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *e) override |
| virtual void | rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end) override |
| virtual void | rowsInserted(const QModelIndex &parent, int start, int end) override |
| virtual void | scrollContentsBy(int dx, int dy) override |
| virtual QModelIndexList | selectedIndexes() const override |
| virtual void | selectionChanged(const QItemSelection &selected, const QItemSelection &deselected) override |
| virtual void | setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command) override |
| virtual void | startDrag(Qt::DropActions supportedActions) override |
| virtual void | timerEvent(QTimerEvent *e) override |
| virtual void | updateGeometries() override |
| virtual int | verticalOffset() const override |
| virtual QSize | viewportSizeHint() const override |
| virtual QRegion | visualRegionForSelection(const QItemSelection &selection) const override |
| virtual void | wheelEvent(QWheelEvent *e) override |
详细说明

QListView 将存储在模型中的项目呈现为简单的非层次化列表,或作为图标集合。该类用于提供此前由 `QListBox ` 和 `QIconView ` 类提供的列表和图标视图,但采用了 Qt 模型/视图架构提供的更灵活的方法。
QListView 类是模型/视图类之一,属于 Qt的模型/视图框架。
该视图不显示水平或垂直标题行;若要显示带有水平标题行的项目列表,请改用QTreeView 。
QListView 实现了由QAbstractItemView 类定义的接口,从而能够显示由继承自QAbstractItemModel 类的模型提供的数据。
列表视图中的项目可以通过两种视图模式之一进行显示:在ListMode 中,项目以简单列表的形式显示;在IconMode 中,列表视图采用图标视图的形式,项目像文件管理器中的文件一样以图标形式显示。 默认情况下,列表视图处于ListMode 状态。要更改视图模式,请使用setViewMode()函数;要确定当前视图模式,请使用viewMode()函数。
这些视图中的项目会按照列表视图的flow()所指定的方向进行布局。项目可以固定在原地,也可以允许移动,这取决于视图的movement()状态。
如果模型中的项目无法完全沿流向布局,则可在视图控件的边界处进行换行;这取决于isWrapping()。当项目由图标视图表示时,此属性非常有用。
resizeMode() 和layoutMode() 控制项目布局的方式和时机。项目间距根据其spacing() 确定,并可存在于由gridSize() 指定尺寸的虚拟网格中。项目可根据其iconSize() 渲染为大图标或小图标。
提升性能
为了在显示大量项目时提高性能,可以向视图提供有关其所处理数据的提示。对于旨在显示等大小项目的视图,一种可采用的方法是将uniformItemSizes 属性设置为 true。
另请参阅 “视图类”、“QTreeView ”、“QTableView ”和“QListWidget ”。
成员类型文档
enum QListView::Flow
| 常数 | 值 | 描述 |
|---|---|---|
QListView::LeftToRight | 0 | 视图中,项目从左到右排列。 |
QListView::TopToBottom | 1 | 项目在视图中从上到下排列。 |
enum QListView::LayoutMode
| 常数 | 值 | 描述 |
|---|---|---|
QListView::SinglePass | 0 | 项目将一次性全部排列。 |
QListView::Batched | 1 | 项目以batchSize 个项目为一组进行布局。 |
另请参阅 batchSize 。
enum QListView::Movement
| 常数 | 值 | 描述 |
|---|---|---|
QListView::Static | 0 | 用户无法移动这些项目。 |
QListView::Free | 1 | 用户可以自由移动这些项目。 |
QListView::Snap | 2 | 移动时,这些项目会吸附到指定的网格上;参见setGridSize()。 |
enum QListView::ResizeMode
| 常数 | 值 | 描述 |
|---|---|---|
QListView::Fixed | 0 | 这些项目仅在视图首次显示时进行布局。 |
QListView::Adjust | 1 | 每次调整视图大小时,都会重新布局这些项目。 |
enum QListView::ViewMode
| 常数 | 值 | 描述 |
|---|---|---|
QListView::ListMode | 0 | 项目采用TopToBottom 布局,大小为“小”,定位方式为“静态” |
QListView::IconMode | 1 | 这些项目采用LeftToRight 布局流,大小为“大”,移动方式为“自由” |
属性文档
batchSize : int
如果将layoutMode 设置为Batched ,则该属性存储每批中排列的项目数量。
默认值为 100。
访问函数:
| int | batchSize() const |
| void | setBatchSize(int batchSize) |
flow : Flow
该属性用于指定项目布局的流向。
如果该属性设置为LeftToRight ,项目将从左向右排列。如果isWrapping 属性设置为true ,当布局到达可见区域右侧时将自动换行。如果该属性设置为TopToBottom ,项目将从可见区域顶部开始排列,到达底部时自动换行。
在视图可见时设置此属性将导致项目重新布局。
默认情况下,该属性设置为TopToBottom 。
访问函数:
| QListView::Flow | flow() const |
| void | setFlow(QListView::Flow flow) |
另请参阅 viewMode 。
gridSize : QSize
该属性用于指定布局网格的大小
该属性表示用于布局项的网格大小。默认值为空,这意味着不存在网格,且布局不会在网格中进行。将该属性设置为非空值将启用网格布局。(当网格布局生效时,spacing 属性将被忽略。)
在视图可见时设置此属性将导致项目重新布局。
访问函数:
| QSize | gridSize() const |
| void | setGridSize(const QSize &size) |
另请参阅 viewMode 。
isWrapping : bool
该属性控制项目布局是否应进行换行。
该属性控制当可见区域内不再有空间时,布局是否应进行换行。布局换行的位置取决于flow 属性。
在视图可见时设置此属性将导致项目重新布局。
默认情况下,此属性的值为false 。
访问函数:
| bool | isWrapping() const |
| void | setWrapping(bool enable) |
另请参阅 ` viewMode`。
itemAlignment : Qt::Alignment
该属性控制每个项目在其单元格中的对齐方式
此功能仅在ListMode 中支持,且需采用TopToBottom 布局并启用换行功能。默认对齐值为0,表示项目将完全填满其单元格。
访问函数:
| Qt::Alignment | itemAlignment() const |
| void | setItemAlignment(Qt::Alignment alignment) |
layoutMode : LayoutMode
确定项目的布局应立即进行还是延迟进行。
该属性用于指定项的布局模式。当模式为SinglePass (默认值)时,所有项将一次性完成布局。当模式为Batched 时,在处理事件的过程中,项将以batchSize 个为一批进行分批布局。这样便可以在其余项正在布局时,立即查看可见项并与之交互。
访问函数:
| QListView::LayoutMode | layoutMode() const |
| void | setLayoutMode(QListView::LayoutMode mode) |
另请参阅 viewMode 。
modelColumn : int
该属性指定模型中可见的列
默认情况下,该属性值为 0,表示将显示模型中的第一列。
访问函数:
| int | modelColumn() const |
| void | setModelColumn(int column) |
movement : Movement
该属性用于确定项目是否可以自由移动、是否会吸附到网格上,还是完全无法移动。
该属性决定了用户如何在视图中移动项目。Static 表示用户无法移动项目。Free 表示用户可以将项目拖放至视图中的任意位置。Snap 表示用户可以拖放项目,但仅限于由gridSize 属性所标识的虚拟网格中的位置。
在视图可见时设置此属性将导致项目重新布局。
默认情况下,此属性设置为Static 。
访问函数:
| QListView::Movement | movement() const |
| void | setMovement(QListView::Movement movement) |
另请参阅 gridSize 、resizeMode 和viewMode 。
resizeMode : ResizeMode
该属性控制在视图调整大小时是否重新布局项目。
如果该属性值为Adjust ,则在视图调整大小时,项目将重新布局。如果值为Fixed ,则在视图调整大小时,项目不会重新布局。
默认情况下,此属性设置为Fixed 。
访问函数:
| QListView::ResizeMode | resizeMode() const |
| void | setResizeMode(QListView::ResizeMode mode) |
另请参阅 movement 、gridSize 和viewMode 。
selectionRectVisible : bool
是否应显示选择矩形
如果此属性值为true ,则选择矩形可见;否则将被隐藏。
注意: 只有当选择模式处于允许选择多个项目的模式时,选择矩形才会显示;也就是说,如果选择模式为QAbstractItemView::SingleSelection ,则不会绘制选择矩形。
默认情况下,此属性为false 。
访问函数:
| bool | isSelectionRectVisible() const |
| void | setSelectionRectVisible(bool show) |
spacing : int
该属性表示布局中项目周围的间距
该属性表示在布局中项目周围填充的空白区域的大小。
在视图可见时设置此属性将导致项目重新布局。
默认情况下,该属性的值为 0。
访问函数:
| int | spacing() const |
| void | setSpacing(int space) |
另请参阅 viewMode 。
uniformItemSizes : bool
该属性表示列表视图中的所有项目是否具有相同大小
只有在能保证视图中的所有项目大小均相同时,才应将此属性设置为 true。这样可使视图进行一些性能优化。
默认情况下,此属性的值为false 。
访问函数:
| bool | uniformItemSizes() const |
| void | setUniformItemSizes(bool enable) |
viewMode : ViewMode
该属性存储QListView 的视图模式。
该属性会将其他未设置的属性调整为与所设视图模式一致。已设置的QListView 专属属性将保持不变,除非已调用clearPropertyFlags()方法。
设置视图模式将根据所选的移动方式启用或禁用拖放功能。对于ListMode ,默认移动方式为Static (禁用拖放);对于IconMode ,默认移动方式为Free (启用拖放)。
访问函数:
| QListView::ViewMode | viewMode() const |
| void | setViewMode(QListView::ViewMode mode) |
另请参阅 isWrapping 、spacing 、gridSize 、flow 、movement 以及resizeMode 。
wordWrap : bool
此属性用于指定项目文本的换行策略
如果该属性设置为true ,则项目文本会在必要时按单词分隔点进行换行;否则,文本将完全不换行。该属性的默认值为false 。
请注意,即使启用了换行,单元格也不会自动扩展以容纳文本。对于无法显示的文本,系统将根据视图的textElideMode 设置打印省略号。
Access 函数:
| bool | wordWrap() const |
| void | setWordWrap(bool on) |
成员函数文档
[explicit] QListView::QListView(QWidget *parent = nullptr)
创建一个新的QListView,并使用给定的parent 来显示模型。请使用setModel()来设置模型。
[virtual noexcept] QListView::~QListView()
破坏了视觉效果。
void QListView::clearPropertyFlags()
清除QListView 特有的属性标志。参见viewMode 。
从QAbstractItemView 继承的属性不受属性标志的影响。具体来说,dragEnabled 和acceptsDrops 是在调用setMovement()或setViewMode()时,由QListView 计算得出的。
[override virtual protected] void QListView::currentChanged(const QModelIndex ¤t, const QModelIndex &previous)
重写了:QAbstractItemView::currentChanged (const QModelIndex ¤t, const QModelIndex &previous)。
[override virtual protected] void QListView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())
重写了:QAbstractItemView::dataChanged (const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles)。
[override virtual protected] void QListView::dragLeaveEvent(QDragLeaveEvent *e)
重写了:QAbstractItemView::dragLeaveEvent(QDragLeaveEvent *event)。
[override virtual protected] void QListView::dragMoveEvent(QDragMoveEvent *e)
重写:QAbstractItemView::dragMoveEvent(QDragMoveEvent *event)。
[override virtual protected] void QListView::dropEvent(QDropEvent *event)
重写了:QAbstractItemView::dropEvent(QDropEvent *event)。
[override virtual protected] bool QListView::event(QEvent *e)
重写了:QAbstractItemView::event(QEvent *event)。
[override virtual protected] int QListView::horizontalOffset() const
重新实现了:QAbstractItemView::horizontalOffset() const。
[override virtual] QModelIndex QListView::indexAt(const QPoint &p) const
重写了:QAbstractItemView::indexAt(const QPoint &point) const。
[signal] void QListView::indexesMoved(const QModelIndexList &indexes)
当视图中指定的indexes 发生移动时,会发出此信号。
[override virtual protected] void QListView::initViewItemOption(QStyleOptionViewItem *option) const
重写了:QAbstractItemView::initViewItemOption(QStyleOptionViewItem *option) const。
[override virtual protected] bool QListView::isIndexHidden(const QModelIndex &index) const
重写了:QAbstractItemView::isIndexHidden(const QModelIndex &index) const。
bool QListView::isRowHidden(int row) const
如果row 被隐藏,则返回true ;否则返回false 。
[override virtual protected] void QListView::mouseMoveEvent(QMouseEvent *e)
重写了:QAbstractItemView::mouseMoveEvent(QMouseEvent *event)。
[override virtual protected] void QListView::mouseReleaseEvent(QMouseEvent *e)
重写了:QAbstractItemView::mouseReleaseEvent(QMouseEvent *event)。
[override virtual protected] QModelIndex QListView::moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers)
重写了:QAbstractItemView::moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers)。
[override virtual protected] void QListView::paintEvent(QPaintEvent *e)
重写了:QAbstractScrollArea::paintEvent(QPaintEvent *event)。
[protected] QRect QListView::rectForIndex(const QModelIndex &index) const
返回模型中位于坐标index 处该项的矩形。该矩形采用内容坐标系。
另请参阅 visualRect()。
[override virtual protected] void QListView::resizeEvent(QResizeEvent *e)
重写了:QAbstractItemView::resizeEvent(QResizeEvent *event)。
[override virtual protected] void QListView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)
重写了:QAbstractItemView::rowsAboutToBeRemoved (const QModelIndex &parent, int start, int end)。
[override virtual protected] void QListView::rowsInserted(const QModelIndex &parent, int start, int end)
重写了:QAbstractItemView::rowsInserted(const QModelIndex &parent, int start, int end)。
[override virtual protected] void QListView::scrollContentsBy(int dx, int dy)
重写了:QAbstractScrollArea::scrollContentsBy(int dx, int dy)。
通过dx 和dy 滚动视图内容。
[override virtual] void QListView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible)
重写了:QAbstractItemView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint)。
[override virtual protected] QModelIndexList QListView::selectedIndexes() const
重新实现了:QAbstractItemView::selectedIndexes() const。
[override virtual protected] void QListView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected)
重写了:QAbstractItemView::selectionChanged (const QItemSelection &selected, const QItemSelection &deselected)。
[protected] void QListView::setPositionForIndex(const QPoint &position, const QModelIndex &index)
将模型中位于index 处的项的内容位置设置为给定的position 。如果列表视图的移动模式为“静态”(Static),或者其视图模式为“仅内容”(ListView ),则此函数将不起作用。
[override virtual] void QListView::setRootIndex(const QModelIndex &index)
重写了:QAbstractItemView::setRootIndex(const QModelIndex &index)。
void QListView::setRowHidden(int row, bool hide)
如果hide 为真,则指定的row 将被隐藏;否则,row 将被显示。
另请参阅 isRowHidden()。
[override virtual protected] void QListView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command)
重写了:QAbstractItemView::setSelection (const QRect &rect, QItemSelectionModel::SelectionFlags flags)。
[override virtual protected] void QListView::startDrag(Qt::DropActions supportedActions)
重写了:QAbstractItemView::startDrag (Qt::DropActions 的 supportedActions)。
[override virtual protected] void QListView::timerEvent(QTimerEvent *e)
重写了:QAbstractItemView::timerEvent(QTimerEvent *event)。
[override virtual protected] void QListView::updateGeometries()
重写了:QAbstractItemView::updateGeometries()。
[override virtual protected] int QListView::verticalOffset() const
重新实现了:QAbstractItemView::verticalOffset() const。
[override virtual protected] QSize QListView::viewportSizeHint() const
重新实现了:QAbstractItemView::viewportSizeHint() const。
[override virtual] QRect QListView::visualRect(const QModelIndex &index) const
重写了:QAbstractItemView::visualRect(const QModelIndex &index) const。
[override virtual protected] QRegion QListView::visualRegionForSelection(const QItemSelection &selection) const
重写:QAbstractItemView::visualRegionForSelection(const QItemSelection &selection) const。
自 4.7 版本起,返回的区域仅包含与视口相交(或包含在视口内)的矩形。
[override virtual protected] void QListView::wheelEvent(QWheelEvent *e)
重写了:QAbstractScrollArea::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.