QListWidget 列表选择框

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

快速导览：

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

• PyQt6 版本参考：PyQt6 教学 - QListWidget 列表选择框
• 因为 Google Colab 不支援 PyQt5，所以请使用本机环境 ( 参考：使用 Python 虚拟环境 ) 或使用 Anaconda Jupyter 进行实作 ( 参考：使用 Anaconda )。

QListWidget 和 QListView 的差异

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

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

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

Form = QtWidgets.QWidget()
Form.setWindowTitle('oxxo.studio')
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 列表选择框

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

from PyQt5 import QtWidgets
import sys
app = QtWidgets.QApplication(sys.argv)

Form = QtWidgets.QWidget()
Form.setWindowTitle('oxxo.studio')
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_())

QListWidget 删除选项

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

from PyQt5 import QtWidgets
import sys
app = QtWidgets.QApplication(sys.argv)

Form = QtWidgets.QWidget()
Form.setWindowTitle('oxxo.studio')
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_())

QListWidget 添加选项

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

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

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

Form = QtWidgets.QWidget()
Form.setWindowTitle('oxxo.studio')
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('', 'mona.jpg'))  # 添加使用函式創造的選項

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

QListWidget 修改选项

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

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

Form = QtWidgets.QWidget()
Form.setWindowTitle('oxxo.studio')
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_())

QListWidget 样式设定

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

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

Form = QtWidgets.QWidget()
Form.setWindowTitle('oxxo.studio')
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.LeftToRight)  # 改成水平顯示
listwidget.setStyleSheet('''
    QListWidget{
        color:#00f;
    }
    QListWidget::item{
        width:30px;
    }
    QListWidget::item:selected{
        color:#f00;
        background:#000;
    }
''')

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

QListWidget 常用方法

下方列出 QListWidget 的常用方法：

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

显示 QListWidget 选择项目

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

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

Form = QtWidgets.QWidget()
Form.setWindowTitle('oxxo.studio')
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.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 的写法

上方的程序码，亦可改用 class 的写法表示。

from PyQt5 import QtWidgets
import sys

class MyWidget(QtWidgets.QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle('oxxo.studio')
        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.LeftToRight)
        self.listwidget.setStyleSheet('''
            QListWidget::item{
                font-size:20px;
            }
            QListWidget::item:selected{
                color:#f00;
                background:#000;
            }
        ''')
        self.listwidget.clicked.connect(self.showMsg)         # 點擊項目時執行函式

    def showMsg(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_())

意见反馈