• 老猿Python博文目录
• 专栏：使用PyQt开发图形界面Python应用
• 老猿Python博客地址

一、概述

列表部件（List Widget）对应类QListWidget，是从QListView派生的类，用于显示一些数据的列表，不支持多层级数据的显示。QListWidget显示的数据项都通过QListWidgetItem构建。

QListWidget是一个便利类，它提供了一个类似于QListView提供的列表视图，具有一个用于添加和删除项的接口。QListWidget使用一个内部模型来管理列表中的每个QListWidgetItem项。如果应用需要更灵活的列表视图控件，建议使用标准模型和QListView类而不是QListWidget来开发。

二、QListWidgetItem项

2.1、概述

QListWidgetItem类为QListWidget类提供构成QListWidget列表部件的项，每个列表部件的项都是一个QListWidgetItem对象。每个项可以保存多条信息，如显示文字、图标、toolTip、what’sThis、对齐方式、复选框等，并根据这些信息在列表部件中显示出来。

2.1、QListWidgetItem构造方法

QListWidgetItem对象专门用于作为QListWidget对象的一个项。

QListWidgetItem有四个构造方法，分别如下：

• QListWidgetItem(parent: QListWidget = None, type: int = QListWidgetItem.Type)
  构建一个用于QListWidget对象的项，如果指定了parent（一个QListWidget对象），则该项被插入到该参数对应的QListWidget列表部件中，否则只能在创建后调用QListWidget列表部件的insertItem方法插入。
  参数type类型为枚举类型QListWidgetItem.ItemType，其缺省值为QListWidgetItem.Type（对应值为0），否则为QListWidget派生类中使用的一个大于等于QListWidgetItem.UserType（对应值为1000）的整数值，使用单独的type值用于在派生类中对象进行特殊的处理，如排序。
• QListWidgetItem(str, parent: QListWidget = None, type: int = QListWidgetItem.Type)
  构建一个项，项显示的文本由str字符串参数指定，其余两个参数与第一个构造方法相同。
• QListWidgetItem(QIcon, str, parent: QListWidget = None, type: int = QListWidgetItem.Type)
  构建一个项，项显示的文本由str字符串参数指定，项对应图标由QIcon指定，其余两个参数与第一个构造方法相同。
• QListWidgetItem(QListWidgetItem other)
  构建一个项，项的内容从参数指定项other拷贝，但type 和parent不拷贝。

在使用以上构造方法的前三种时，如果构建列表部件的项时指定了parent参数对应的列表部件对象，则构建的项会自动插入到列表部件中，如果没有指定该参数或者是用第四种构造方法，项创建后需要调用列表部件的addItem(QListWidgetItem item)方法或insertItem(int row, QListWidgetItem item)方法将构建的项插入到列表部件的列表中。

2.2、QListWidgetItem其他重要方法

2.2.1、checkState和setCheckState方法

这两个方法用于访问或设置项的复选状态，调用语法分别如下：

• QListWidgetItem.setCheckState(Qt.CheckState state)
• Qt.CheckState QListWidgetItem.checkState()
  Qt.CheckState取值请参考《PyQt（Python+Qt）学习随笔：复选框状态枚举类Qt.CheckState取值及含义》。

2.2.2、icon和setIcon方法

这两个方法用于访问或设置项的图标，调用语法分别如下：

• QListWidgetItem.setIcon(QIcon icon)
• QIcon QListWidgetItem.icon()。

2.2.3、isHidden和setHidden方法

这两个方法用于访问或设置项的选中状态，调用语法分别如下：

• QListWidgetItem.setSelected(bool select)
• bool QListWidgetItem.isSelected()

2.2.4、text和setText方法

这两个方法用于访问或设置项的显示和编辑文本，调用语法分别如下：

• QListWidgetItem.setText(str)
• str QListWidgetItem.text()

2.2.5、flags和setFlags方法

这两个方法用于访问或设置项的标志，调用语法分别如下：

• QListWidgetItem.setFlags(Qt.ItemFlags flags)
• Qt.ItemFlags QListWidgetItem.flags()
  项的标志用于控制项的显示和操作，项的标记对应枚举类，具体取值及含义请参考《PyQt（Python+Qt）学习随笔：Model中项的标记flags取值及枚举类型Qt.ItemFlag》。

2.2.6、其他方法

其他方法包括用于访问状态提示的setStatusTip、statusTip方法，用于访问工具栏提示的 setToolTip、toolTip方法，用于访问WhatsThis提示的setWhatsThis、whatsThis方法，用于设置项对齐方式的setTextAlignment、textAlignment方法（关于对齐标记取值的含义请参考《PyQt(Python+Qt)学习随笔：formLayout的layoutLabelAlignment 属性》）以及访问项类型的type方法。

三、QListWidget类

3.1、QListWidget类的属性

3.1.1、属性概述

QListWidget类的属性除了从父类QListView、QAbstractItemView、QAbstractScrollArea、QFrame、QWidget、QObject继承的属性外，自身的属性有三个，分别是：count、currentRow和sortingEnabled，这三个属性中，currentRow和sortingEnabled是可以在Qt Designer中进行设置的属性。

3.1.2、count属性

count属性保存QListWidget列表部件对象中项的个数，这个个数包含了隐藏未显示的项。可以通过方法count（）获取该属性的值。

3.1.3、currentRow属性

QListWidget的currentRow属性保存当前项的位置，为整型，从0开始计数，在某些选择模式下，当前项可能也是选中项。

currentRow属性可以通过方法currentRow()、setCurrentRow(int row)、setCurrentRow(int row, QItemSelectionModel.SelectionFlags command)进行访问和设置。

关于QItemSelectionModel.SelectionFlags的取值请参考《PyQt（Python+Qt）学习随笔：Mode/View中的枚举类 QItemSelectionModel.SelectionFlag取值及含义》。

当当前项发生变化时，QListWidget会发射信号currentRowChanged(int currentRow)。

3.1.4、sortingEnabled属性

QListWidget的sortingEnabled属性用于控制列表部件中的项是否可以排序，如果为True则可以排序，否则不能排序。

可以通过方法isSortingEnabled() 和setSortingEnabled(bool enable)访问或设置该属性。

3.2、QListWidget类的重要方法

3.2.1、构造方法

QListWidget类的构造方法很简单，语法如下：

QListWidget(QWidget parent = None)
1

parent一般是谁创建QListWidget对象就指定为谁，实际上在Python中，使用上述方式定义一个对象时，真正执行的构造方法是__init__。

3.2.2、增加单个项的方法addItem

在QListWidget对象中，增加一个项的方法是调用addItem方法，addItem方法有2种重载方式，分别语法如下：

• addItem(str )
  该方法直接在列表部件QListWidget对象的列表尾部增加一个文本内容为参数指定值的对象，不用单独构建QListWidgetItem对象。
• addItem(QListWidgetItem )
  该方法需要先构建一个QListWidgetItem项，再将该项追加到列表部件QListWidget对象的列表尾部。

3.2.3、增加多个项的方法addItems

除了上面的方法addItem能增加项外，QListWidget支持一次增加多个项，对应的方法就是addItems方法，对应语法如下：

addItems(Iterable[str])
1

其参数为一个可迭代的类型，其中的元素为字符串。

案例：

 items = ['item1','item2','item3']
 self.listWidget.addItems(items)
1
2

这样一次就可以增加三个项，不用先构建项，使用起来方便。

3.2.4、访问当前项的currentItem和setCurrentItem方法

currentItem方法返回列表部件当前选择的项，setCurrentItem方法用于设置当前项。语法如下：

• QListWidgetItem currentItem()
• setCurrentItem(QListWidgetItem item)
• setCurrentItem(QListWidgetItem item, QItemSelectionModel.SelectionFlags command)

关于SelectionFlags 请参考《PyQt（Python+Qt）学习随笔：Mode/View中的枚举类 QItemSelectionModel.SelectionFlag取值及含义》，带SelectionFlags 参数时除了设置当前项外，还会影响对列表部件的项的选中数据变化，具体变化由参数command指定。

setCurrentItem使用时注意2点：

• 除非选择模式设置为NoSelection，否则setCurrentItem设置项当前项后，对应项也会被选中
• setCurrentItem没有返回值，无法判断是否成功识别，如果对应item在列表部件中不存在也不会有异常出现

3.2.5、查找项的findItems方法

findItems方法用于查找列表部件是否有满足条件的项，调用语法如下：

list findItems( str label, Qt.MatchFlags flag)
1

findItems用于列表部件中查找文本内容与label参数匹配的项，查找过程的匹配模式由flag参数指定，返回值为一个满足条件的Qt.MatchExactly项的列表。枚举类Qt.MatchFlags的取值及含义请参考《PyQt（Python+Qt）学习随笔：Model/View中的枚举类 Qt.MatchFlag的取值及含义》。

3.2.5、插入单个项的insertItem方法

在QListWidget对象中，插入一个项的方法是调用insertItem方法，insertItem方法有2种重载方式，分别语法如下：

• insertItem(int row，str label )
  该方法直接在列表部件QListWidget对象的列表指定位置插入一个文本内容为参数指定值的项，不用单独构建QListWidgetItem对象。
• insertItem(int row，QListWidgetItem item)
  该方法需要先构建一个QListWidgetItem项，再将该项插入到列表部件指定位置。

3.2.6、插入多个项的insertItems方法

除了上面的方法insertItem能插入项外，QListWidget支持一次插入多个项，对应的方法就是insertItems方法，对应语法如下：

insertItems(int row,Iterable[str])
1

row指定插入项的开始位置，另一个参数为一个可迭代的类型，其中的元素为字符串。

3.2.7、获取指定行对应项的item方法

在列表部件中，可以通过item方法获取指定行对应的项，语法如下：

QListWidgetItem item(int row)
1

注意：
row从0开始计数，如果对应位置不存在项，则返回None。

3.2.8、获取指定位置对应项的itemAt方法

itemAt方法根据参数给定位置返回列表部件中的项。对应语法如下：

QListWidgetItem itemAt(QPoint p)
QListWidgetItem itemAt(int x, int y)
1
2

注意：位置对应坐标是相对列表部件的视口的，关于视口请参考《PyQt(Python+Qt)学习随笔：QAbstractScrollArea的viewPort(视口）理解》。

3.2.9、获取指定项对应行的row方法

QListWidget的row方法通过项作为参数，获取到对应项所在行的行号，语法如下：

int row(QListWidgetItem item)
1

如果对应项在列表部件中不存在，则返回-1。

3.2.10、获取当前选中项的selectedItems方法

QListWidget的selectedItems方法返回列表部件中所有选中项的一个列表，调用语法如下：

list selectedItems() 
1

返回列表中的每个元素就是一个QListWidgetItem对象，如果没有选中项，则返回空列表。

3.2.11、当前选择模式selectionMode操作方法

列表部件的selectionMode决定了列表中有多少项可以同时选择，以及是否可以使用复杂的项选择操作。selectionMode可以通过selectionMode（）获取，通过setSelectionMode（QItemSelectionModel ）函数设置。
关于QItemSelectionModel 请参考
《PyQt（Python+Qt）学习随笔：Mode/View中的枚举类 QItemSelectionModel.SelectionFlag取值及含义》。

3.2.12、对项进行排序的sortItems方法

QListWidget的sortItems方法用于对列表部件中所有项按参数进行排序，相关调用语法如下：

sortItems(Qt.SortOrder order = Qt.AscendingOrder)
1

枚举类型Qt.SortOrder用于指定排序是按升序排序还是降序排序，取值及含义如下：

• AscendingOrder：值为0，表示升序排序
• DescendingOrder：值为1，表示降序排序

3.2.13、删除项的takeItem方法

takeItem方法从QListWidget列表部件的项中删除指定项，并返回对应项对象。调用语法如下：

QListWidgetItem takeItem(int row)
1

如果对应row没有项，则返回None。

在此介绍了一些QListWidget的常用方法，还有些其他方法老猿在此就不再详细介绍了，感兴趣的同学可以自己查阅资料。

四、小结

QListWidget便利类是在QListView的基础上提供的一个便利类，可以在界面上展示一个只有一列的列表，适合快速开发一个简单的列表视图，但如果涉及大数据量及复杂的视图，还是需要使用QListView。本节详细介绍了 Model/View便利类列表部件QListWidget的主要属性、方法，但怎么使用和应用密切相关。

广告

老猿关于PyQt的付费专栏《使用PyQt开发图形界面Python应用》只需要9.9元，该部分与第十五章的内容基本对应，但同样内容在付费专栏上总体来说更详细、案例更多。本节内容对应付费专栏的《第二十一章、 Model/View便利类列表部件QListWidget详解》。如果有兴趣也愿意支持老猿的读者，欢迎购买付费专栏。

老猿Python，跟老猿学Python!

• 老猿Python博文目录
• 专栏：使用PyQt开发图形界面Python应用
• 老猿Python博客地址