通用 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)、表单、详情抽屉、验证或 Toast/进度反馈 → 读取./references/forms-dialogs-and-feedback.md - 键盘快捷键、无障碍、i18n/RTL 布局或后台线程 → 读取
./references/accessibility-i18n-and-async.md - 启动一个没有现有主题的全新 PySide6 应用程序 → 可选择参考
./assets/base-theme.qss
2. 通用 UX 法则(应用于桌面 UI)
- Jakob 定律:匹配已建立的桌面约定(
Ctrl+S保存,Ctrl+F搜索,Esc取消/清除,F5刷新,标准菜单/工具栏位置),使用户立即感到流畅。 - Fitts 定律:保持主要操作足够大(高度
>= 36px,触摸/高频工作流为>= 42px),并锚定在用户注意力所在位置附近;避免为重复操作强制长鼠标移动。 - Hick 定律与渐进式披露:限制当前时刻的可见选项。将次要选项分组到抽屉、标签或溢出菜单中,而不是将所有控件拥挤到一个屏幕上。
- Miller 定律与格式塔邻近性:将相关控件分组成清晰的视觉组 (
CardFrame),具有一致的间距(组内8px,组间16px–24px),使用户轻松扫描结构。 - Doherty 阈值(感知响应
< 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(清晰支持拉丁语、阿拉伯语和多语言 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打断打字。 - 每个操作一个规范位置:永远不要将相同操作同时放在顶部栏和底部页脚。将主要页面 CTA 放在
PageHeader的右上角,主要表单/对话框 CTA 放在模态框页脚的右下角。 - 键盘优先与非阻塞反馈:在
showEvent()中设置初始焦点、绑定setTabOrder()、支持Enter/Esc,并使用非阻塞覆盖式 Toast 或状态栏进行常规确认——保留模态对话框用于破坏性确认。 - 克制、内容适配的状态徽章:永远不要将表格状态药丸拉伸到宽的均匀固定宽度,也不要让每个健康行都充斥着沉重的饱和徽章。动态适应药丸宽度
QFontMetrics.horizontalAdvance(text) + padding,保持常规健康状态视觉安静(例如,微妙的7px状态点 + 清晰文本),使警告/错误立即突出,并在自定义QStyledItemDelegate.paint()覆盖中保留行选择和底部细线分隔符。
5. 预发布质量门控
在任何 PySide6 UI 实现最终确定之前,请验证:
- 每个视图是否都有清晰的视觉层级(
PageHeader或结构化工作区栏),没有零散的浮动控件? - 所有交互控件是否共享统一的高度(
>= 36px)、清晰的悬停/焦点状态以及足够的色彩对比度? - 数字/表格列是否右对齐并根据应用的语言环境格式化?
- 表格状态徽章是否根据其文本调整大小,在健康行上视觉平静,并与行选择和分隔线无缝对齐?
- 空、零匹配和加载状态是否使用专用的
QStackedWidget状态而不是空白区域? - 每个禁用的控件是否通过
setToolTip()自我解释? - 长时间运行的任务是否从 UI 线程卸出,以便窗口永不冻结?