Skip to main content

PySide6 入門

PySide6 是 Qt 官方的 Python binding（又稱 Qt for Python），用來開發跨平台桌面應用（Windows / macOS / Linux）。語法接近原生 Qt，生態成熟，適合做工具軟體、內部系統、本機工具。

若想快速做出接近 Windows 11 / Fluent Design 的現代化介面，可搭配 QFluentWidgets（PySide6-Fluent-Widgets）。

為什麼選 PySide6？​

項目說明
授權LGPL，商業閉源較友善（相較部分 PyQt 授權情境）
維護Qt Company 官方支援
API與 Qt 6 對齊，文件與範例豐富
跨平台同一套 Python 程式可打包到三大桌面平台

與 PyQt6 的差異：API 幾乎相同，但授權與 import 名稱不同。同一專案不要混用 PySide6 與 PyQt6。

安裝​

建議使用虛擬環境：

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install PySide6

用 uv 時：

uv add PySide6

驗證：

python -c "from PySide6.QtWidgets import QApplication; print('PySide6 OK')"

最小視窗（Hello World）​

import sys

from PySide6.QtWidgets import QApplication, QLabel, QWidget, QVBoxLayout


def main() -> None:
    app = QApplication(sys.argv)

    window = QWidget()
    window.setWindowTitle("Hello PySide6")
    window.resize(360, 200)

    label = QLabel("你好，PySide6！")
    layout = QVBoxLayout(window)
    layout.addWidget(label)

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


if __name__ == "__main__":
    main()

重點：

  1. 必須先建立 QApplication（一個行程通常只有一個）。
  2. 建立視窗與控件，用 layout 排版。
  3. show() 顯示，app.exec() 進入事件迴圈。

常用模組對照​

模組用途
PySide6.QtWidgets視窗、按鈕、輸入框、layout、對話框
PySide6.QtCore訊號槽、QTimer、QThread、Qt 列舉
PySide6.QtGui字型、圖示、快捷鍵、繪圖
PySide6.QtNetworkHTTP / TCP 等網路
PySide6.QtMultimedia音訊／視訊

訊號與槽（Signal / Slot）​

Qt 的核心互動模型：控件發出 signal，你的函式當 slot 接收。

from PySide6.QtWidgets import QPushButton, QWidget, QVBoxLayout, QLabel


class CounterWindow(QWidget):
    def __init__(self) -> None:
        super().__init__()
        self.count = 0
        self.label = QLabel("點擊次數：0")
        self.button = QPushButton("加一")
        self.button.clicked.connect(self.on_clicked)

        layout = QVBoxLayout(self)
        layout.addWidget(self.label)
        layout.addWidget(self.button)

    def on_clicked(self) -> None:
        self.count += 1
        self.label.setText(f"點擊次數：{self.count}")

自訂訊號：

from PySide6.QtCore import QObject, Signal


class Worker(QObject):
    finished = Signal(str)

    def run(self) -> None:
        self.finished.emit("done")

Layout 排版​

少用固定座標 move() / setGeometry()，優先用 layout：

from PySide6.QtWidgets import (
    QHBoxLayout,
    QVBoxLayout,
    QFormLayout,
    QLineEdit,
    QPushButton,
    QWidget,
)


class FormWindow(QWidget):
    def __init__(self) -> None:
        super().__init__()
        form = QFormLayout()
        form.addRow("帳號", QLineEdit())
        form.addRow("密碼", QLineEdit())

        actions = QHBoxLayout()
        actions.addStretch(1)
        actions.addWidget(QPushButton("取消"))
        actions.addWidget(QPushButton("登入"))

        root = QVBoxLayout(self)
        root.addLayout(form)
        root.addLayout(actions)

常見 layout：QVBoxLayout、QHBoxLayout、QGridLayout、QFormLayout、QStackedWidget（多頁切換）。

建議專案結構​

my_app/
├── main.py                 # 進入點：QApplication
├── ui/
│   ├── main_window.py      # 主視窗
│   └── pages/              # 各功能頁
├── services/               # 業務邏輯、API
├── resources/              # 圖示、qss、翻譯
└── pyproject.toml

原則：

  • UI 與業務分離：頁面只負責顯示與觸發；耗時工作放 service / worker。
  • 耗時工作不要卡 UI thread：用 QThread / QObject.moveToThread，或把結果用 signal 回主執行緒更新控件。

打包成可執行檔​

常用工具：

PyInstaller 示意：

pip install pyinstaller
pyinstaller -F -w main.py

-w 隱藏主控台視窗（GUI 應用常用）。實際專案常需額外帶入資料檔、圖示與 hidden imports。

下一步：美化介面​

原生 QPushButton / QLabel 偏「系統預設」外觀。若要快速得到：

  • 圓角按鈕、深淺色主題
  • 側邊導航、設定頁卡片
  • InfoBar、Flyout 等現代化回饋

請看：用 QFluentWidgets 美化 PySide6 介面。

參考資料​