一、概述
列表部件（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)
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])
其参数为一个可迭代的类型，其中的元素为字符串。
案例：
items = ['item1','item2','item3']
self.listWidget.addItems(items)
这样一次就可以增加三个项，不用先构建项，使用起来方便。
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)
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])
row指定插入项的开始位置，另一个参数为一个可迭代的类型，其中的元素为字符串。
3.2.7、获取指定行对应项的item方法
在列表部件中，可以通过item方法获取指定行对应的项，语法如下：
QListWidgetItem item(int row)
注意：
row从0开始计数，如果对应位置不存在项，则返回None。
3.2.8、获取指定位置对应项的itemAt方法
itemAt方法根据参数给定位置返回列表部件中的项。对应语法如下：
QListWidgetItem itemAt(QPoint p)
QListWidgetItem itemAt(int x, int y)
注意：位置对应坐标是相对列表部件的视口的，关于视口请参考《PyQt(Python+Qt)学习随笔：QAbstractScrollArea的viewPort(视口）理解》。
3.2.9、获取指定项对应行的row方法
QListWidget的row方法通过项作为参数，获取到对应项所在行的行号，语法如下：
int row(QListWidgetItem item)
如果对应项在列表部件中不存在，则返回-1。
3.2.10、获取当前选中项的selectedItems方法
QListWidget的selectedItems方法返回列表部件中所有选中项的一个列表，调用语法如下：
list selectedItems()
返回列表中的每个元素就是一个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)
枚举类型Qt.SortOrder用于指定排序是按升序排序还是降序排序，取值及含义如下：
- AscendingOrder：值为0，表示升序排序
- DescendingOrder：值为1，表示降序排序
3.2.13、删除项的takeItem方法
takeItem方法从QListWidget列表部件的项中删除指定项，并返回对应项对象。调用语法如下：
QListWidgetItem takeItem(int row)
如果对应row没有项，则返回None。
在此介绍了一些QListWidget的常用方法，还有些其他方法老猿在此就不再详细介绍了，感兴趣的同学可以自己查阅资料。
四、小结
QListWidget便利类是在QListView的基础上提供的一个便利类，可以在界面上展示一个只有一列的列表，适合快速开发一个简单的列表视图，但如果涉及大数据量及复杂的视图，还是需要使用QListView。本节详细介绍了 Model/View便利类列表部件QListWidget的主要属性、方法，但怎么使用和应用密切相关。
广告
老猿关于PyQt的付费专栏《使用PyQt开发图形界面Python应用》只需要9.9元，该部分与第十五章的内容基本对应，但同样内容在付费专栏上总体来说更详细、案例更多。本节内容对应付费专栏的《第二十一章、 Model/View便利类列表部件QListWidget详解》。如果有兴趣也愿意支持老猿的读者，欢迎购买付费专栏。
