一、概述
列表部件（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詳解》。如果有興趣也願意支持老猿的讀者，歡迎購買付費專欄。
老猿Python，跟老猿學Python!
