通用 PySide6 UI/UX 架構技能
為任何應用程式領域使用 PySide6 設計和建構乾淨、響應式、以人為本的桌面介面。始終優先檢查目標專案現有的主題、元件和慣例——自然地與它們整合,而不是覆蓋現有的抽象層。僅載入目前任務所需的特定參考文件。
1. 漸進式揭露路由(按需讀取)
- 主題設定、QSS 樣式表、淺色/深色模式、HiDPI 或佈局基本元素 → 讀取
./references/design-system-and-qss.md - 主視窗架構、側邊欄、分頁標籤、可停靠面板、分割器或儀表板 → 讀取
./references/navigation-and-shell.md - 資料表格、列表、樹狀圖、搜尋列、篩選器或空/載入中狀態 → 讀取
./references/data-tables-and-filters.md - 對話視窗 (
QDialog)、表單、詳細資料抽屜、驗證或通知/進度回饋 → 讀取./references/forms-dialogs-and-feedback.md - 鍵盤快速鍵、無障礙存取、i18n/RTL 佈局或背景執行緒 → 讀取
./references/accessibility-i18n-and-async.md - 引導全新且無現有主題的 PySide6 應用程式 → 可選地參考
./assets/base-theme.qss
2. 通用 UX 法則(應用於桌面 UI)
- Jakob's Law:符合既有的桌面操作慣例(
Ctrl+S儲存、Ctrl+F搜尋、Esc取消/清除、F5重新整理、標準選單/工具列位置),讓使用者能立即流暢操作。 - Fitts's Law:保持主要操作按鈕有足夠大的尺寸(高度
>= 36px,觸控/高頻操作>= 42px),並固定在靠近使用者當前注意力的位置;避免強制使用者為重複動作進行長距離滑鼠移動。 - Hick's Law 與漸進式揭露:在任何時刻限制可見的選項數量。將次要選項分組至抽屜、分頁或溢出選單中,而不是將所有控制項塞滿一個畫面。
- Miller's Law 與格式塔鄰近原則:將相關控制項分組至清晰的視覺群組(
CardFrame)中,使用一致間距(群組內8px,群組間16px–24px),讓使用者能毫不費力地掃視結構。 - Doherty Threshold(< 400ms 感知回應):絕不凍結 Qt 事件迴圈。在主執行緒之外執行 I/O、網路和大量計算(使用
QThreadPool/QRunnable),並立即顯示載入或進度回饋。 - 錯誤預防與安全復原:在提交前進行內聯驗證,禁用不可能的操作並附帶清除的工具提示說明原因,僅對破壞性或不可逆的操作要求明確確認。
3. 預設設計系統記號(可調整)
如果專案已定義色板、排版或間距系統,請遵循專案的記號。否則,使用以下乾淨、高對比度的預設值:
- 強調色與焦點:
- 主要強調色:
#0F766E(懸停:#0D5F59,按下:#0A4A45,柔和色調:#CCFBF1/#F0FDFA)— 或根據應用程式的品牌色調調整。 - 焦點環:在所有互動輸入框和按鈕上使用
2px solid的主要強調色。
- 主要強調色:
- 中性表面層級(淺色 / 深色):
- 應用程式畫布:
#F8FAFC(淺色)/#0F172A(深色) - 浮升表面 / 卡片:
#FFFFFF(淺色)/#1E293B(深色) - 次要表面(頁首、頁尾、條紋):
#F1F5F9(淺色)/#334155(深色) - 細線邊框 / 分隔線:
#E2E8F0(淺色)/#334155(深色) - 預設輸入框邊框:
#CBD5E1(淺色)/#475569(深色)
- 應用程式畫布:
- 排版與文字層級:
- 主要文字:
#0F172A(淺色)/#F8FAFC(深色) - 次要 / 標籤文字:
#475569(淺色)/#CBD5E1(深色) - 靜態 / 禁用文字:
#94A3B8(淺色)/#64748B(深色) - 字型堆疊:
"Segoe UI", "Inter", "Cairo", system-ui, sans-serif(良好支援拉丁文、阿拉伯文和 multilingual UI)。 - 字型級別:頁面標題
20px粗體,章節標題15px半粗體,內文/儲存格13px常規,標籤/說明12px中粗體,重點指標22px–26px粗體。
- 主要文字:
- 語意狀態記號:
- 成功:文字
#15803D,填充#DCFCE7(深色:#4ADE80/#14532D) - 警告:文字
#B45309,填充#FEF3C7(深色:#FBBF24/#451A03) - 危險:文字
#B91C1C,填充#FEE2E2(深色:#F87171/#450A0A) - 資訊:文字
#0369A1,填充#E0F2FE(深色:#38BDF8/#0C4A6E)
- 成功:文字
- 間距與幾何:
- 間距級別:
4px(緊密),8px(相關元素),12px(工具列/表單間距),16px(卡片內距),20px–24px(頁面邊距)。 - 控制項高度:標準輸入框/按鈕
36px,高頻/觸控控制項42px+,表格標題38px,表格行>= 42px。 - 邊框圓角:控制項
6px,卡片/面板10px,對話視窗12px,狀態膠囊11px。
- 間距級別:
4. 不可妥協的 PySide6 工程規則
- 首先適應現有程式碼庫:在引入新抽象層之前,重用現有的主題常數、基礎元件和輔助工具。
- 清晰的空間分組:使用
QFrame卡片(1px細線邊框,微妙的表面對比)或QSplitter窗格,而不是使用厚重的巢狀QGroupBox邊框。 - 表格與樹狀資料使用 Model/View:使用
QTableView/QTreeView搭配QAbstractItemModel(QAbstractTableModel)、QSortFilterProxyModel和QStyledItemDelegate。避免在QTableWidget的儲存格中填入厚重的巢狀元件。 - 使用語義化 QSS 而非內聯混亂樣式:透過
setObjectName(...)角色(PrimaryButton、DangerButton、Card、PageTitle)和動態屬性([invalid="true"]搭配unpolish()/polish())來設定樣式,而不是散落未經整理的setStyleSheet(...)字串。 - 響應式佈局(零固定容器尺寸):切勿在視窗、卡片或表格上呼叫
setFixedSize()。依賴佈局管理器、伸縮因子、QSizePolicy和QScrollArea,以便 UI 能跨解析度、HiDPI 顯示器和翻譯後的文字長度乾淨地縮放。 - 解釋禁用狀態並進行內聯驗證:每次呼叫
setEnabled(False)都必須附帶setToolTip(...)說明為何禁用。使用輔助錯誤標籤進行內聯輸入驗證——絕不要用QMessageBox打斷使用者輸入。 - 每個操作只有一個規範位置:切勿在頂部工具列和底部頁尾重複相同的操作。將主要頁面的行動呼籲按鈕放在
PageHeader的右上角,將主要表單/對話視窗的行動呼籲按鈕放在模態底部頁尾的右下角。 - 鍵盤優先與非阻塞回饋:在
showEvent()中設定初始焦點,配置setTabOrder(),支援Enter/Esc鍵,並使用非阻塞的覆疊通知或狀態列來處理常規確認——將對話視窗保留給破壞性確認。 - 節制且內容自適應的狀態徽章:切勿將表格狀態膠囊拉伸成寬闊的統一固定寬度,或在每個健康的資料列上塞滿色彩飽和的徽章。根據
QFontMetrics.horizontalAdvance(text) + padding動態調整膠囊寬度,保持常規健康狀態視覺上低調(例如,微小的7px狀態點加上清晰的文字),以便警告/錯誤能立即突出,並在自訂QStyledItemDelegate.paint()覆寫中保留行選取狀態和底部細線分隔線。
5. 上線前品質把關
在最終確定任何 PySide6 UI 實作之前,請驗證:
- 每個視圖是否都有清晰的視覺層級(
PageHeader或結構化的工作區列),且沒有孤立漂浮的控制項? - 所有互動控制項是否都具有統一高度(
>= 36px)、清晰的懸停/焦點狀態和足夠的色彩對比? - 數字/表格欄位是否根據應用程式的區域設定進行了右對齊和格式化?
- 表格狀態徽章是否根據其文字調整大小,在健康資料列上視覺上平靜,並與行選取狀態和分隔線無縫對齊?
- 空、無匹配和載入中狀態是否使用專用的
QStackedWidget狀態而不是空白區域? - 每個禁用控制項是否透過
setToolTip()解釋自己? - 長時間執行的任務是否從 UI 執行緒卸載,以免視窗凍結?