QListWidget 列表选择框

QListWidget 是 PyQt6 里的列表选择框控件，这篇教学会介绍如何在 PyQt6 窗口里加入 QListWidget 列表选择框，并简单介绍与 QListView 的差异，并实作修改样式以及点击选项等基本应用。

快速导览：

• QListWidget 和 QListView 的差异
• 加入 QListWidget 列表选择框
• QListWidget删除选项、添加选项、修改选项
• QListWidget 样式设定
• QListWidget 常用方法
• 显示 QListWidget 选择项目

QListWidget 和 QListView 的差异

QListWidget 是一个更新且更高级的控件，能够更为方便地进行开发，例如 QListWidget 具有 QStantandardItemModel 无法访问的类型，也能更轻松的透过 QListWidgetItem 处理数据，然而如果使用 QListView，许多方法必须要额外定义，属于比较旧的使用方式。

下方列出两个方法所建立简单列表选单的程序，可以看出使用 QListWidget 的程序更容易阅读理解：

 from PyQt6 import QtWidgets, QtCore
 import sys
 app = QtWidgets.QApplication(sys.argv)
 ​
 Form = QtWidgets.QWidget()
 Form.setWindowTitle('千牛编程思维')
 Form.resize(300, 200)
 ​
 # 使用 QListView
 listview = QtWidgets.QListView(Form)
 listview.setGeometry(10,10,120,100)
 model = QtCore.QStringListModel()
 model.setStringList(['A','B','C','D'])  # 使用 QtCore.QStringListModel() 建立选项
 listview.setModel(model)
 ​
 # 使用 QListWidget
 listwidget = QtWidgets.QListWidget(Form)
 listwidget.setGeometry(140,10,120,100)
 listwidget.addItems(['A','B','C','D'])  # 使用 addItems 建立选项
 ​
 Form.show()
 sys.exit(app.exec())

加入 QListWidget 列表选择框

建立 PyQt6 窗口物件后，透过 QtWidgets.QListWidget(widget)方法，就能在指定的控件中建立列表选择框，接著使用 addItems()方法加入列表项目，下方的程序执行后，会在窗口里加入一个有四个项目的列表选择框。

 from PyQt6 import QtWidgets
 import sys
 app = QtWidgets.QApplication(sys.argv)
 ​
 Form = QtWidgets.QWidget()
 Form.setWindowTitle('千牛编程思维')
 Form.resize(300, 200)
 ​
 listwidget = QtWidgets.QListWidget(Form)  # 建立列表選擇框控件
 listwidget.addItems(['A','B','C','D'])    # 建立选项
 listwidget.setGeometry(10,10,120,100)    # 设定位置
 ​
 Form.show()
 sys.exit(app.exec())

class 写法：

 from PyQt6 import QtWidgets
 import sys
 ​
 class MyWidget(QtWidgets.QWidget):
     def __init__(self):
         super().__init__()
         self.setWindowTitle('千牛编程思维')
         self.resize(300, 200)
         self.ui()
 ​
     def ui(self):
         self.listwidget = QtWidgets.QListWidget(self)  # 建立列表選擇框控件
         self.listwidget.addItems(['A','B','C','D'])    # 建立选项
         self.listwidget.setGeometry(10,10,120,100)     # 设定位置
 ​
 if __name__ == '__main__':
     app = QtWidgets.QApplication(sys.argv)
     Form = MyWidget()
     Form.show()
     sys.exit(app.exec())

QListWidget 删除选项

使用使用takeItem(index)取得指定的项目，index 表示该项目的索引值，第一个项目为 0，取得项目后，就能透过removeItemWidge(item)方法移除该项目，下方的程序执行后，会将项目里的 B 移除。

 from PyQt6 import QtWidgets
 import sys
 app = QtWidgets.QApplication(sys.argv)
 ​
 Form = QtWidgets.QWidget()
 Form.setWindowTitle('千牛编程思维')
 Form.resize(300, 200)
 ​
 listwidget = QtWidgets.QListWidget(Form)
 listwidget.addItems(['A','B','C','D'])
 listwidget.setGeometry(10,10,120,100)
 item = listwidget.takeItem(1)       # 取得第二个项目，也就是 B
 listwidget.removeItemWidget(item)   # 移除第二个项目
 ​
 Form.show()
 sys.exit(app.exec())

class 写法：

 from PyQt6 import QtWidgets
 import sys
 ​
 class MyWidget(QtWidgets.QWidget):
     def __init__(self):
         super().__init__()
         self.setWindowTitle('千牛编程思维')
         self.resize(300, 200)
         self.ui()
 ​
     def ui(self):
         self.listwidget = QtWidgets.QListWidget(self)
         self.listwidget.addItems(['A','B','C','D'])
         self.listwidget.setGeometry(10,10,120,100)
         item = self.listwidget.takeItem(1)       # 取得第二个项目，也就是 B
         self.listwidget.removeItemWidget(item)   # 移除第二个项目
 ​
 if __name__ == '__main__':
     app = QtWidgets.QApplication(sys.argv)
     Form = MyWidget()
     Form.show()
     sys.exit(app.exec())

QListWidget添加选项

有两种方法可以「添加列表项目」，第一种方法使用 addItem(item)方法将项目加在列表最后方，第二种方法使用insertItem(index, item)将项目加入指定的位置，两种方法除了可以单纯加入「文字」项目，也可以使用函数的方法，加入带有 icon 图示的项目。

下面的程序执行后，会先使用第一种方法，在最后方添加一个内容为 X 的项目，并搭配函数在最后加入一个带有 icon 图片的选项，接著会使用第二种方法，将内容为 Y 的项目添加在第一个项目，然后再搭配函数在第一个项目加入带有 icon 图片的选项。

 from PyQt6 import QtWidgets, QtGui
 import sys
 app = QtWidgets.QApplication(sys.argv)
 ​
 Form = QtWidgets.QWidget()
 Form.setWindowTitle('千牛编程思维')
 Form.resize(300, 200)
 ​
 def create_item(text, img):
     item = QtWidgets.QListWidgetItem()      # 建立清单項目
     item.setText(text)                      # 項目文字
     item.setIcon(QtGui.QIcon(img))          # 項目图片
     return item                             # 返回清单項目
 ​
 listwidget = QtWidgets.QListWidget(Form)
 listwidget.addItems(['A','B','C','D'])
 listwidget.setGeometry(10,10,120,120)
 listwidget.addItem('X')                         # 添加純文字項目
 listwidget.addItem(create_item('', 'icon.png')) # 添加使用函数創造的选项
 ​
 listwidget.insertItem(0, 'Y')                          # 添加純文字項目
 listwidget.insertItem(0, create_item('', 'icon2.png'))  # 添加使用函数創造的选项
 ​
 Form.show()
 sys.exit(app.exec())

class 写法：

 from PyQt6 import QtWidgets, QtGui
 import sys
 ​
 class MyWidget(QtWidgets.QWidget):
     def __init__(self):
         super().__init__()
         self.setWindowTitle('千牛编程思维')
         self.resize(300, 200)
         self.ui()
 ​
     def ui(self):
         self.listwidget = QtWidgets.QListWidget(self)
         self.listwidget.addItems(['A','B','C','D'])
         self.listwidget.setGeometry(20,20,320,320)
         self.listwidget.addItem('X')                         # 添加純文字項目
         self.listwidget.addItem(self.create_item('', 'icon.png')) # 添加使用函数創造的选项
 ​
         self.listwidget.insertItem(0, 'Y')                          # 添加純文字項目
         self.listwidget.insertItem(0, self.create_item('', 'icon2.png'))  # 添加使用函数創造的选项
 ​
     def create_item(self, text, img):
         item = QtWidgets.QListWidgetItem()      # 建立清单項目
         item.setText(text)                      # 項目文字
         item.setIcon(QtGui.QIcon(img))          # 項目图片
         return item                             # 返回清单項目
 ​
 if __name__ == '__main__':
     app = QtWidgets.QApplication(sys.argv)
     Form = MyWidget()
     Form.show()
     sys.exit(app.exec())

QListWidget 修改选项

如果要修改项目内容，可以先透过item(index)方法可以取得该项目，接著就能使用setText()方法修改文字，使用setIcon()方法设定图示。

 from PyQt6 import QtWidgets, QtGui
 import sys
 app = QtWidgets.QApplication(sys.argv)
 ​
 Form = QtWidgets.QWidget()
 Form.setWindowTitle('千牛编程思维')
 Form.resize(300, 200)
 ​
 listwidget = QtWidgets.QListWidget(Form)
 listwidget.addItems(['A','B','C','D'])
 listwidget.setGeometry(10,10,120,100)
 item = listwidget.item(1)                # 取得第二个项目 ( 第一個为 0 )
 item.setText('ok')                       # 设定文字为 ok
 item.setIcon(QtGui.QIcon('icon.png'))    # 设定 icon
 ​
 Form.show()
 sys.exit(app.exec())

class 写法：

from PyQt6 import QtWidgets, QtGui
import sys

class MyWidget(QtWidgets.QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle('千牛编程思维')
        self.resize(300, 200)
        self.ui()

    def ui(self):
        self.listwidget = QtWidgets.QListWidget(self)
        self.listwidget.addItems(['A','B','C','D'])
        self.listwidget.setGeometry(10,10,120,100)
        item = self.listwidget.item(1)           # 取得第二个项目 ( 第一個为 0 )
        item.setText('ok')                       # 设定文字为 ok
        item.setIcon(QtGui.QIcon('icon.png'))    # 设定 icon

if __name__ == '__main__':
    app = QtWidgets.QApplication(sys.argv)
    Form = MyWidget()
    Form.show()
    sys.exit(app.exec())

QListWidget 样式设定

透过setStyleSheet()，可以使用类似网页的 CSS 语法设定 QPushButton 样式，搭配 setFlow()方法，也可以设定列表为水平显示或垂直显示 ( QtWidgets.QListView.Flow.LeftToRight为 PyQt6 的用法 )，下方的程序执行后，会将原本垂直显示列表换成水平显示，并在选择项目时，将项目变成黑底红字。

from PyQt6 import QtWidgets, QtGui
import sys
app = QtWidgets.QApplication(sys.argv)

Form = QtWidgets.QWidget()
Form.setWindowTitle('千牛编程思维')
Form.resize(300, 200)

def show():
    print(listwidget.currentItem().text(), listwidget.currentIndex().row())

def create_item(text):
    item = QtWidgets.QListWidgetItem(listwidget)
    item.setText(text)
    item.setIcon(QtGui.QIcon('icon.png'))
    return item

listwidget = QtWidgets.QListWidget(Form)
listwidget.addItems(['A','B','C','D'])
listwidget.setGeometry(10,10,200,50)
listwidget.addItem(create_item(''))
listwidget.setFlow(QtWidgets.QListView.Flow.LeftToRight)  # 改成水平显示
listwidget.setStyleSheet('''
    QListWidget{
        color:#00f;
    }
    QListWidget::item{
        width:30px;
    }
    QListWidget::item:selected{
        color:#f00;
        background:#000;
    }
''')

Form.show()
sys.exit(app.exec())

class 写法：

from PyQt6 import QtWidgets, QtGui
import sys

class MyWidget(QtWidgets.QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle('千牛编程思维')
        self.resize(300, 200)
        self.ui()

    def ui(self):
        self.listwidget = QtWidgets.QListWidget(self)
        self.listwidget.addItems(['A','B','C','D'])
        self.listwidget.setGeometry(10,10,200,50)
        self.listwidget.addItem(self.create_item(''))
        self.listwidget.setFlow(QtWidgets.QListView.Flow.LeftToRight)  # 改成水平显示
        self.listwidget.setStyleSheet('''
            QListWidget{
                color:#00f;
            }
            QListWidget::item{
                width:30px;
            }
            QListWidget::item:selected{
                color:#f00;
                background:#000;
            }
        ''')

    def create_item(self, text):
        item = QtWidgets.QListWidgetItem(self.listwidget)
        item.setText(text)
        item.setIcon(QtGui.QIcon('icon.png'))
        return item

if __name__ == '__main__':
    app = QtWidgets.QApplication(sys.argv)
    Form = MyWidget()
    Form.show()
    sys.exit(app.exec())

QListWidget 常用方法

下方列出 QListWidget 的常用方法：

方法	参数	说明
item()	index	取得指定的项目。
addItem()	str	增加单一个项目。
addItems()	list	以串列方式增加多个项目。
takeItem()	index	取得並移除指定項目
removeItemWidget()	item	移除指定項目。
clear()		清空所有项目。
setFlow()	type	设定排列方式，预设QtWidgets.QListView.Flow.TopToBottom从上而下，QtWidgets.QListView.Flow.LeftToRight从左到右 ( 和 PyQt5 不同 )。
setDisabled()	bool	设定是否禁用，预设 False。
clicked.connect()	fn	点击项目时时要执行的函数。
text()		取得输入框内容。
currentItem().text()		点击项目的文字。
currentIndex().row()		点击项目的列数 ( 垂直 )。
currentIndex().column()		点击项目的栏数 ( 水平 )。

下方列出 QListWidget 里 item 的常用方法：

方法	参数	说明
setText()	str	设定项目的文字内容。
setIcon()	QtGui.QIcon(path)	设定项目的图片。
setSelected()	bool	设定是否选取，预设 False。
text()		项目的文字内容。

显示 QListWidget 选择项目

运用clicked.connect(fn)方法，就能在点击项目时，执行特定的函数，下方的程序执行后，会透过 QLabel 显示点击的项目内容。

from PyQt6 import QtWidgets, QtCore, QtGui
import sys
app = QtWidgets.QApplication(sys.argv)

Form = QtWidgets.QWidget()
Form.setWindowTitle('千牛编程思维')
Form.resize(300, 200)

label = QtWidgets.QLabel(Form)
label.setGeometry(10,10,120,30)

def show():
    text = listwidget.currentItem().text()  # 取得項目文字
    num = listwidget.currentIndex().row()   # 取得項目编号
    label.setText(f'{num}:{text}')          # 显示文字

listwidget = QtWidgets.QListWidget(Form)
listwidget.addItems(['A','B','C','D'])
listwidget.setGeometry(10,50,120,50)
listwidget.setFlow(QtWidgets.QListView.Flow.LeftToRight)
listwidget.setStyleSheet('''
    QListWidget::item{
        font-size:20px;
    }
    QListWidget::item:selected{
        color:#f00;
        background:#000;
    }
''')
listwidget.clicked.connect(show)         # 点击项目时执行函数

Form.show()
sys.exit(app.exec())

class 写法 ( 注意不能使用 show 作为方法名称，会覆写基类的 show 方法造成无法显示 )：

from PyQt6 import QtWidgets, QtGui
import sys

class MyWidget(QtWidgets.QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle('千牛编程思维')
        self.resize(300, 200)
        self.ui()

    def ui(self):
        self.label = QtWidgets.QLabel(self)
        self.label.setGeometry(10,10,120,30)
        self.listwidget = QtWidgets.QListWidget(self)
        self.listwidget.addItems(['A','B','C','D'])
        self.listwidget.setGeometry(10,50,120,50)
        self.listwidget.setFlow(QtWidgets.QListView.Flow.LeftToRight)
        self.listwidget.setStyleSheet('''
            QListWidget::item{
                font-size:20px;
            }
            QListWidget::item:selected{
                color:#f00;
                background:#000;
            }
        ''')
        self.listwidget.clicked.connect(self.showText)  # 点击项目时执行函数

    def showText(self):
        text = self.listwidget.currentItem().text()  # 取得項目文字
        num = self.listwidget.currentIndex().row()   # 取得項目编号
        self.label.setText(f'{num}:{text}')          # 显示文字

if __name__ == '__main__':
    app = QtWidgets.QApplication(sys.argv)
    Form = MyWidget()
    Form.show()
    sys.exit(app.exec())