TUTORIAL

PyQt5 教程 - 單選按鈕

本教程透過範例介紹 PyQt5 QRadioButton 控制元件:建立單選按鈕、將槽函式連接到 toggled 訊號、預先選取選項,以及讓群組保持獨立。

本頁內容

QRadioButton 可讓使用者從一組選項中恰好選取一項,因此當多個選擇彼此互斥時,它就是合適的控制元件。若需要彼此獨立的開/關選項,請改用 QCheckBox,因為每個核取方塊都會保留自己的狀態。每個 QRadioButton 都結合一個圓形指示器與文字標籤;共用同一個父控制元件的單選按鈕會自動組成一個互斥群組:選取其中一個就會取消選取其他按鈕。

建立 QRadioButton 控制元件

將可見的選項文字傳遞給 QRadioButton 建構子,並像其他控制元件一樣把按鈕加入版面配置。下列指令碼會建立一個視窗,詢問使用者住在哪個城市,提供 New York 和 Houston 兩個選項,並保留第二個 QLabel 用來顯示答案。此範例需要 PyQt5 和圖形化顯示環境;importlib.util.find_spec 檢查可讓檔案在未安裝 PyQt5 的環境中正常結束,而在桌面環境中則會開啟如下所示的視窗。範例中的視窗標題、問題、按鈕文字與結果訊息依原始程式碼保持英文。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

import importlib.util
import sys

if importlib.util.find_spec("PyQt5") is None:
    sys.exit(0)  # PyQt5 is required for the GUI below

from PyQt5.QtWidgets import (
    QApplication,
    QLabel,
    QRadioButton,
    QVBoxLayout,
    QWidget,
)


class basicRadiobuttonExample(QWidget):
    def __init__(self):
        super().__init__()

        self.init_ui()

    def init_ui(self):
        self.label = QLabel("Which city do you live in?")
        self.rbtn1 = QRadioButton("New York")
        self.rbtn2 = QRadioButton("Houston")
        self.label2 = QLabel("")

        self.rbtn1.toggled.connect(self.onClicked)
        self.rbtn2.toggled.connect(self.onClicked)

        layout = QVBoxLayout()
        layout.addWidget(self.label)
        layout.addWidget(self.rbtn1)
        layout.addWidget(self.rbtn2)
        layout.addWidget(self.label2)

        self.setGeometry(200, 200, 300, 150)

        self.setLayout(layout)
        self.setWindowTitle("PyQt5 Radio Button Example")

        self.show()

    def onClicked(self):
        radioBtn = self.sender()
        if radioBtn.isChecked():
            self.label2.setText("You live in " + radioBtn.text())


if __name__ == "__main__":
    app = QApplication(sys.argv)
    ex = basicRadiobuttonExample()
    sys.exit(app.exec_())

呈現後的 PyQt5 視窗,標題為「PyQt5 Radio Button Example」,顯示問題「Which city do you live in?」、未選取的 New York 與 Houston 單選按鈕,以及一條空白結果列

建構子字串("New York"、"Houston")會成為繪製在每個圓形指示器旁的文字。self.label 提出問題;self.label2 一開始是空白的標籤,稍後會回報所選項目;QVBoxLayout 則依照加入順序垂直堆疊控制元件。setGeometry(200, 200, 300, 150) 設定視窗的位置與大小,setWindowTitle() 設定視窗標題。

回應 toggled 訊號

每當 QRadioButton 的選取狀態改變(無論是選取或取消選取),它都會發出 toggled 訊號:按鈕被選取時以已選取狀態發出一次,而失去選取狀態的按鈕也會以未選取狀態發出一次。將兩個按鈕都連接到同一個槽函式——self.rbtn1.toggled.connect(self.onClicked) 和 self.rbtn2.toggled.connect(self.onClicked)——就足以追蹤整個群組。

由於 toggled 也會針對被取消選取的按鈕觸發,因此槽函式會使用 isChecked() 篩選,讓只有新選取的按鈕才會更新結果。在 onClicked 內,self.sender() 會回傳發出訊號的控制元件,text() 會讀取其可見的選項標籤,而 self.label2.setText("You live in " + radioBtn.text()) 則會寫入答案。

toggled 訊號也會以布林值攜帶新的選取狀態,因此宣告為 def onClicked(self, checked) 的槽函式可以使用該值,而不必呼叫 isChecked()。在這裡,對訊號傳送者檢查 isChecked() 是較簡單的模式,因為它能清楚指出是哪個按鈕產生了文字。

基本範例中的互動:選取 Houston 單選按鈕會將其選中、取消選取 New York,並把結果標籤更新為「You live in Houston」

使用 setChecked() 設定預設選取項目

新的 QRadioButton 物件一開始都處於未選取狀態,因此視窗開啟時沒有任何選項被選中。若要在應用程式啟動時預先選取其中一個選項,請對該按鈕呼叫 setChecked():self.rbtn1.setChecked(True)。

變更選取狀態會像使用者點按一樣發出 toggled 訊號。如果希望預先選取也能更新相依的控制元件(例如結果標籤),請在訊號連接完成後呼叫 setChecked(True);如果希望啟動時的選取不要觸發這些更新,請在連接之前呼叫它。

使用 QButtonGroup 建立獨立群組

具有相同父控制元件的所有 QRadioButton 控制元件都屬於同一個隱含群組,因此即使它們的 toggled 訊號連接到不同的槽函式,一次也只能選中其中一個。當一個視窗要詢問多個彼此獨立的問題時,請將每組選項包進來自 QtWidgets 的 QButtonGroup,並用 addButton() 註冊各按鈕;這樣每個群組都能獨立保有一個已選取的按鈕。下列範例會同時詢問城市和州,且需要與第一個指令碼相同的 PyQt5 桌面環境。本節範例中的介面文字與文字輸出依原始程式碼保持英文:

本節中的程式碼以及顯示的標籤或輸出仍為英文。

import importlib.util
import sys

if importlib.util.find_spec("PyQt5") is None:
    sys.exit(0)  # PyQt5 is required for the GUI below

from PyQt5.QtWidgets import (
    QApplication,
    QButtonGroup,
    QLabel,
    QRadioButton,
    QVBoxLayout,
    QWidget,
)


class basicRadiobuttonExample(QWidget):
    def __init__(self):
        super().__init__()

        self.init_ui()

    def init_ui(self):
        self.label = QLabel("Which city do you live in?")
        self.rbtn1 = QRadioButton("New York")
        self.rbtn2 = QRadioButton("Houston")
        self.label2 = QLabel("")

        self.label3 = QLabel("Which state do you live in?")
        self.rbtn3 = QRadioButton("New York")
        self.rbtn4 = QRadioButton("Texas")
        self.label4 = QLabel("")

        self.btngroup1 = QButtonGroup()
        self.btngroup2 = QButtonGroup()

        self.btngroup1.addButton(self.rbtn1)
        self.btngroup1.addButton(self.rbtn2)
        self.btngroup2.addButton(self.rbtn3)
        self.btngroup2.addButton(self.rbtn4)

        self.rbtn1.toggled.connect(self.onClickedCity)
        self.rbtn2.toggled.connect(self.onClickedCity)

        self.rbtn3.toggled.connect(self.onClickedState)
        self.rbtn4.toggled.connect(self.onClickedState)

        layout = QVBoxLayout()
        layout.addWidget(self.label)
        layout.addWidget(self.rbtn1)
        layout.addWidget(self.rbtn2)
        layout.addWidget(self.label2)

        layout.addWidget(self.label3)
        layout.addWidget(self.rbtn3)
        layout.addWidget(self.rbtn4)
        layout.addWidget(self.label4)

        self.setGeometry(200, 200, 300, 300)

        self.setLayout(layout)
        self.setWindowTitle("PyQt5 Radio Button Example")

        self.show()

    def onClickedCity(self):
        radioBtn = self.sender()
        if radioBtn.isChecked():
            self.label2.setText("You live in " + radioBtn.text())

    def onClickedState(self):
        radioBtn = self.sender()
        if radioBtn.isChecked():
            self.label4.setText("You live in " + radioBtn.text())


if __name__ == "__main__":
    app = QApplication(sys.argv)
    ex = basicRadiobuttonExample()
    sys.exit(app.exec_())

呈現後的 PyQt5 視窗,內含兩組彼此獨立的選項:在「Which city do you live in?」下方有一個已選取的城市單選按鈕,在「Which state do you live in?」下方則有一個已選取的州單選按鈕

程式會建立兩個 QButtonGroup 物件:self.btngroup1 用於城市按鈕,self.btngroup2 用於州按鈕。addButton() 會將每個單選按鈕註冊到所屬群組——城市組使用 self.btngroup1.addButton(self.rbtn1) 和 self.btngroup1.addButton(self.rbtn2),州組使用 self.btngroup2.addButton(self.rbtn3) 和 self.btngroup2.addButton(self.rbtn4)。如果沒有這些群組,選取 Texas 會因為四個按鈕共用同一個父控制元件而取消城市的選取;加入群組後,每個問題都會保有自己的已選取按鈕,而且各結果標籤也會獨立更新。

視窗本身無法以文字形式展示這項規則,因此下列純 Python 模型重現了相同的互斥行為:每個群組只能有一個選取項目,而且第二個群組不受第一個群組影響。請執行此範例;其程式碼與文字輸出依原始內容保持英文:

class RadioGroup:
    def __init__(self):
        self.buttons = []
        self.checked = None

    def add(self, label):
        self.buttons.append(label)

    def select(self, label):
        self.checked = label
        return "Selected: " + label


city = RadioGroup()
city.add("New York")
city.add("Houston")

state = RadioGroup()
state.add("New York")
state.add("Texas")

print(city.select("New York"))
print(state.select("Texas"))
print(city.select("Houston"))
print("State group still holds:", state.checked)
Selected: New York
Selected: Texas
Selected: Houston
State group still holds: Texas

QButtonGroup 對應模型中的 RadioGroup 角色:新的選取項目會取代同一群組內先前的選取,而另一個群組則會保留自己的答案。