Communitygithub.com

pyside6-ui

一套適用於任何桌面應用程式的通用 PySide6 / Qt for Python UI/UX 架構與設計系統技能。在設計、建構、重構、樣式化或審查 PySide6 視窗、導航外殼、QSS 主題、儀表板、資料表格、搜尋/篩選列、CRUD 表單、對話視窗、非同步響應、RTL/在地化或鍵盤操作流程時,務必使用此技能。

pyside6-ui 是什麼?

此技能「pyside6-ui」定義了一套全面的通用 UI/UX 架構,專為使用 PySide6 (Qt for Python) 開發桌面應用程式而設計。其核心理念是「漸進式揭露路由」,要求 AI 代理在處理不同 UI 層面(如主題設定、視窗導航、資料表格或表單對話窗)時,按需讀取對應的參考文件,以確保最佳實踐與程式碼一致性。技能內容涵蓋了從高階的「通用 UX 法則」(如 Jakob's Law、Fitts's Law)到實務的「非妥協工程規範」(如強制使用 Model/View 架構、語義化 QSS、響應式佈局、解釋禁用狀態原因等),並提供了一套預設的「設計系統記號」,包括顏色、排版、間距和組件尺寸。支援所有主流作業系統,此技能旨在幫助開發者建立乾淨、具響應性且以人為本的桌面介面,避免常見的 UI 陷阱,並顯著提升使用者體驗。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedBoure/skills/tree/main/pyside6-ui

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

通用 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)

  1. Jakob's Law:符合既有的桌面操作慣例(Ctrl+S 儲存、Ctrl+F 搜尋、Esc 取消/清除、F5 重新整理、標準選單/工具列位置),讓使用者能立即流暢操作。
  2. Fitts's Law:保持主要操作按鈕有足夠大的尺寸(高度 >= 36px,觸控/高頻操作 >= 42px),並固定在靠近使用者當前注意力的位置;避免強制使用者為重複動作進行長距離滑鼠移動。
  3. Hick's Law 與漸進式揭露:在任何時刻限制可見的選項數量。將次要選項分組至抽屜、分頁或溢出選單中,而不是將所有控制項塞滿一個畫面。
  4. Miller's Law 與格式塔鄰近原則:將相關控制項分組至清晰的視覺群組(CardFrame)中,使用一致間距(群組內 8px,群組間 16px–24px),讓使用者能毫不費力地掃視結構。
  5. Doherty Threshold(< 400ms 感知回應):絕不凍結 Qt 事件迴圈。在主執行緒之外執行 I/O、網路和大量計算(使用 QThreadPool / QRunnable),並立即顯示載入或進度回饋。
  6. 錯誤預防與安全復原:在提交前進行內聯驗證,禁用不可能的操作並附帶清除的工具提示說明原因,僅對破壞性或不可逆的操作要求明確確認。

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 工程規則

  1. 首先適應現有程式碼庫:在引入新抽象層之前,重用現有的主題常數、基礎元件和輔助工具。
  2. 清晰的空間分組:使用 QFrame 卡片(1px 細線邊框,微妙的表面對比)或 QSplitter 窗格,而不是使用厚重的巢狀 QGroupBox 邊框。
  3. 表格與樹狀資料使用 Model/View:使用 QTableView / QTreeView 搭配 QAbstractItemModel (QAbstractTableModel)、QSortFilterProxyModel 和 QStyledItemDelegate。避免在 QTableWidget 的儲存格中填入厚重的巢狀元件。
  4. 使用語義化 QSS 而非內聯混亂樣式:透過 setObjectName(...) 角色(PrimaryButton、DangerButton、Card、PageTitle)和動態屬性([invalid="true"] 搭配 unpolish()/polish())來設定樣式,而不是散落未經整理的 setStyleSheet(...) 字串。
  5. 響應式佈局(零固定容器尺寸):切勿在視窗、卡片或表格上呼叫 setFixedSize()。依賴佈局管理器、伸縮因子、QSizePolicy 和 QScrollArea,以便 UI 能跨解析度、HiDPI 顯示器和翻譯後的文字長度乾淨地縮放。
  6. 解釋禁用狀態並進行內聯驗證:每次呼叫 setEnabled(False) 都必須附帶 setToolTip(...) 說明為何禁用。使用輔助錯誤標籤進行內聯輸入驗證——絕不要用 QMessageBox 打斷使用者輸入。
  7. 每個操作只有一個規範位置:切勿在頂部工具列和底部頁尾重複相同的操作。將主要頁面的行動呼籲按鈕放在 PageHeader 的右上角,將主要表單/對話視窗的行動呼籲按鈕放在模態底部頁尾的右下角。
  8. 鍵盤優先與非阻塞回饋:在 showEvent() 中設定初始焦點,配置 setTabOrder(),支援 Enter/Esc 鍵,並使用非阻塞的覆疊通知或狀態列來處理常規確認——將對話視窗保留給破壞性確認。
  9. 節制且內容自適應的狀態徽章:切勿將表格狀態膠囊拉伸成寬闊的統一固定寬度,或在每個健康的資料列上塞滿色彩飽和的徽章。根據 QFontMetrics.horizontalAdvance(text) + padding 動態調整膠囊寬度,保持常規健康狀態視覺上低調(例如,微小的 7px 狀態點加上清晰的文字),以便警告/錯誤能立即突出,並在自訂 QStyledItemDelegate.paint() 覆寫中保留行選取狀態和底部細線分隔線。

5. 上線前品質把關

在最終確定任何 PySide6 UI 實作之前,請驗證:

  • 每個視圖是否都有清晰的視覺層級(PageHeader 或結構化的工作區列),且沒有孤立漂浮的控制項?
  • 所有互動控制項是否都具有統一高度(>= 36px)、清晰的懸停/焦點狀態和足夠的色彩對比?
  • 數字/表格欄位是否根據應用程式的區域設定進行了右對齊和格式化?
  • 表格狀態徽章是否根據其文字調整大小,在健康資料列上視覺上平靜,並與行選取狀態和分隔線無縫對齊?
  • 空、無匹配和載入中狀態是否使用專用的 QStackedWidget 狀態而不是空白區域?
  • 每個禁用控制項是否透過 setToolTip() 解釋自己?
  • 長時間執行的任務是否從 UI 執行緒卸載,以免視窗凍結?

相關技能