张家训
287 lines
14 KiB
Markdown
287 lines
14 KiB
Markdown
# WorkUtils 统一 UI 设计规范
|
||
|
||
日期：2026-08-01
|
||
|
||
## 1. 目标与视觉基准
|
||
|
||
本轮统一 WorkUtils 桌面端的应用外壳、排版、间距、图标、控件和异步状态，使所有功能插件具备一致的视觉语言和交互节奏。设计参考 macOS 与 Codex 桌面端的克制、清晰和高信息密度，但保留 Windows 原生标题栏及窗口按钮，不复制 macOS 红黄绿窗口控制。
|
||
|
||
最终视觉基准：
|
||
|
||
|
||
|
||
基准图用于确定视觉方向和信息层级，不是要求逐像素复制生成图中的系统装饰。实际实现必须服从 JavaFX、Windows 平台和现有业务能力。
|
||
|
||
## 2. 已确认的关键决策
|
||
|
||
1. 采用基准图中的明亮应用外壳、顶部应用栏和侧栏布局。
|
||
2. 侧栏支持展开与折叠；展开态显示图标和文本，折叠态仅显示图标。
|
||
3. “系统设置”只出现在顶部应用栏右侧，侧栏不再显示，避免重复入口。
|
||
4. 所有导航及功能图标使用同一套 16px 线性图标，禁止继续使用 Emoji 或混合字形。
|
||
5. API 接口文档导出采用基准图中的布局：紧凑模式选择、连续表单、独立进度操作区和可调整日志区。
|
||
6. 字体、字重、行高、字距和间距模拟 Codex/macOS 的阅读节奏，但使用 Windows 可稳定获得的字体。
|
||
7. 保持现有业务流程、导出格式、配置格式和插件路由不变。
|
||
|
||
## 3. 范围
|
||
|
||
### 3.1 本轮实施
|
||
|
||
- 重构 `MainWindow` 的顶部应用栏、侧栏、折叠状态和插件标题展示。
|
||
- 将系统设置入口移至顶部应用栏右侧，并从插件导航数据中排除。
|
||
- 建立统一设计令牌：字体、字号、色彩、间距、圆角、控件高度和图标尺寸。
|
||
- 引入单一 JavaFX 图标库并提供语义化图标注册表，替换应用外壳和插件描述中的 Emoji。
|
||
- 统一按钮、输入框、选择框、标签页、表格、树、日志区、卡片、空状态和焦点状态。
|
||
- 统一按钮 loading、进度、取消、成功、失败和禁用状态。
|
||
- 按统一页面骨架迁移 Git 同步、文本对比、MyBatis SQL 导出、MyBatis 逆向工程、扫描和 API 文档导出。
|
||
- 让 Git 分支评审、系统设置及手机 UI 自动化继承全局主题和应用外壳。
|
||
- 重点重排 API 文档导出的“导出配置”页，使其符合已确认基准。
|
||
|
||
### 3.2 明确不做
|
||
|
||
- 不重构 Git 分支评审的业务结构、评审流程或 Diff 引擎。
|
||
- 不拆分手机 UI 自动化窗口，也不重写运行/录制状态机。
|
||
- 不重构系统设置内部的信息架构；本轮只迁移入口并适配统一样式。
|
||
- 不改变导出、扫描、生成、同步等后台任务的业务语义。
|
||
- 不为了模拟 macOS 而创建自绘窗口按钮、无边框窗口或平台专属窗口行为。
|
||
- 不增加深色主题；本规范仅定义统一亮色主题。
|
||
|
||
## 4. 应用外壳
|
||
|
||
### 4.1 顶部应用栏
|
||
|
||
- 高度：48px。
|
||
- 左侧依次为：侧栏折叠按钮、WorkUtils 标识、当前插件标题或面包屑。
|
||
- 右侧依次为：系统设置入口、Windows 原生最小化/最大化/关闭区域之外的应用级操作。
|
||
- “系统设置”使用齿轮图标和文本；可通过鼠标及键盘激活。
|
||
- 插件切换后只更新当前插件标题和内容，不重建整个应用外壳。
|
||
- 顶部栏底部使用 1px 中性色分隔线，不使用阴影或渐变。
|
||
|
||
### 4.2 侧栏
|
||
|
||
- 展开宽度：214px；折叠宽度：56px。
|
||
- 折叠/展开状态在应用会话内保持；若现有设置存储可安全复用，可持久化到下次启动，否则不新增配置格式。
|
||
- 展开态显示图标与名称；图标和文本间距 12px。
|
||
- 折叠态仅显示图标，必须提供 Tooltip 和 accessible text。
|
||
- 选中项使用淡蓝背景、左侧 3px 蓝色指示条和蓝色图标/文字。
|
||
- Hover 使用中性浅灰背景；不得使用发光、涟漪或文字阴影。
|
||
- 底部提供“收起/展开”入口；顶部汉堡按钮与底部入口调用同一状态控制器。
|
||
- 侧栏不包含“系统设置”。
|
||
|
||
### 4.3 插件导航顺序
|
||
|
||
1. Git 仓库同步
|
||
2. Git 分支评审
|
||
3. 文本对比
|
||
4. MyBatis SQL 导出
|
||
5. MyBatis 逆向工程
|
||
6. 扫描功能
|
||
7. API 接口文档导出
|
||
|
||
现有插件启用/排序配置仍可影响可见性和顺序，但系统设置不得以普通插件项重新进入侧栏。
|
||
|
||
## 5. 图标系统
|
||
|
||
- 采用 Ikonli JavaFX 与 Feather 图标包作为唯一图标来源。若没有完全对应的图标，选择 Feather 包内语义最接近的图标；纯装饰图标可省略，不得混入第二套图标库或 Unicode 字形。
|
||
- 默认图标尺寸 16px；应用标识可使用 20px；空状态插图不在本轮创建。
|
||
- 所有图标使用统一视觉盒、笔画粗细、基线和颜色令牌。
|
||
- 建立 `AppIcon` 语义枚举和 `IconFactory`，业务代码引用 `SETTINGS`、`GIT_SYNC`、`EXPORT` 等语义，不直接引用图标库枚举或 Unicode 字符。
|
||
- 图标只辅助含义，关键操作不能只依赖图标；图标按钮必须有 Tooltip、accessible text 和清晰焦点环。
|
||
|
||
## 6. 排版规范
|
||
|
||
### 6.1 字体栈
|
||
|
||
UI 字体按以下顺序选择第一个可用字体：
|
||
|
||
1. `Segoe UI Variable Text`
|
||
2. `Segoe UI`
|
||
3. `Microsoft YaHei UI`
|
||
4. JavaFX 系统默认 Sans Serif
|
||
|
||
中文显示依赖系统字体回退，不打包或伪装 SF Pro/PingFang 字体。等宽内容使用 `JetBrains Mono`（若系统存在），否则回退 `Cascadia Mono`、`Consolas`、JavaFX Monospaced。
|
||
|
||
### 6.2 字号与行高
|
||
|
||
| 语义 | 字号 | 字重 | 行高/控件高度 |
|
||
| --- | ---: | --- | --- |
|
||
| 页面标题 | 20px | Semibold | 28px |
|
||
| 区块标题 | 15px | Semibold | 22px |
|
||
| 标签页/导航 | 14px | Medium | 20px |
|
||
| 正文/表单标签 | 14px | Regular | 20px |
|
||
| 辅助说明 | 12.5–13px | Regular | 19px |
|
||
| 表格/树正文 | 13px | Regular | 40px 行高 |
|
||
| 日志/路径 | 12.5–13px | Regular Mono | 19px |
|
||
|
||
不再允许插件自行传入任意标题字号。`Theme` 提供语义字体方法或 CSS 类，旧 `h1(int)`、`body(int)` 等自由尺寸方法在迁移后逐步废弃。
|
||
|
||
### 6.3 字距
|
||
|
||
- 中文正文保持 0 字距，避免人为拉开汉字。
|
||
- 拉丁正文保持 0–0.1px 的自然字距。
|
||
- 页面和区块标题可使用约 -0.2px 的轻微紧缩；JavaFX/CSS 无法稳定实现时保持 0，不通过插入空格模拟。
|
||
- 图标与文字的视觉间距由布局容器控制，不在标签文本中添加空格。
|
||
|
||
## 7. 色彩、间距与形状
|
||
|
||
### 7.1 色彩令牌
|
||
|
||
| 令牌 | 建议值 | 用途 |
|
||
| --- | --- | --- |
|
||
| `bg.app` | `#F7F7F8` | 应用背景 |
|
||
| `bg.surface` | `#FFFFFF` | 表单、表格、日志表面 |
|
||
| `bg.subtle` | `#F2F3F5` | Hover、次级区域 |
|
||
| `text.primary` | `#202123` | 主文本 |
|
||
| `text.secondary` | `#667085` | 辅助文本 |
|
||
| `text.muted` | `#98A2B3` | 禁用/弱提示 |
|
||
| `border.default` | `#E4E7EC` | 1px 分隔与边框 |
|
||
| `accent` | `#1677FF` | 选中、焦点、进度、主按钮 |
|
||
| `accent.hover` | `#0F6BE5` | 主按钮 Hover |
|
||
| `danger` | `#D92D20` | 错误和危险操作 |
|
||
| `success` | `#079455` | 成功状态 |
|
||
|
||
具体值可在实现时根据 AtlantaFX 实际渲染做小幅对比度校正，但不得重新引入深色侧栏、强阴影或大面积高饱和蓝色。
|
||
|
||
### 7.2 间距和尺寸
|
||
|
||
- 以 4px 为最小单位、8px 为主要节奏。
|
||
- 控件内部：8px；同组控件：8–12px；区块间：16px；主要区域间：24px。
|
||
- 主内容边距：上下 16px、左右 24px；窄窗口可降至 16px。
|
||
- 普通控件高度：34–36px；紧凑工具按钮 30–32px。
|
||
- 圆角：普通控件 6px；大面板 8px；不使用胶囊形按钮。
|
||
- 阴影默认关闭。只有真正浮层可使用轻量阴影。
|
||
|
||
## 8. 统一页面骨架
|
||
|
||
每个插件内容区按以下顺序组合：
|
||
|
||
1. 页面标题与可选的一句说明。
|
||
2. 可选标签页或主要上下文工具栏。
|
||
3. 主工作区。
|
||
4. 与任务直接相关的进度和操作区。
|
||
5. 可选的日志、历史或结果面板。
|
||
|
||
页面不再重复绘制应用级标题栏。内容分组优先使用间距、对齐和分隔线；只有需要独立边界或可折叠/调整大小的区域才使用面板边框，禁止卡片嵌套卡片。
|
||
|
||
## 9. API 接口文档导出布局
|
||
|
||
### 9.1 标签页
|
||
|
||
保留“导出配置 / 导出历史 / 基类配置”。标签页高度、字号、下划线和焦点状态由全局主题控制，不在 `ApiDocWindow` 内硬编码。
|
||
|
||
### 9.2 导出配置
|
||
|
||
- 将三张过大的模式卡片改为单行分段选择器。
|
||
- 每段包含统一图标、标题和一行说明；选择状态使用蓝色描边/单选指示，未选状态保持中性。
|
||
- 模式切换只改变与该模式相关的输入区域，保持现有请求构造和校验规则。
|
||
- 完整类名输入使用全宽字段；标签位于字段上方，说明位于字段下方。
|
||
- “启用接口调试（启动本地代理）”保留为显式复选项，默认状态继续服从既有业务约定；在其下方解释影响。
|
||
|
||
### 9.3 任务状态与操作
|
||
|
||
- 进度区与操作按钮位于同一视觉行：左侧为状态标题、进度条和说明，右侧为主操作与取消。
|
||
- 空闲时显示“导出文档”；运行时由 `LoadingButtonBinder` 显示 spinner 和“导出中…”。
|
||
- 可取消任务显示“取消”；不具备真实取消能力时不显示伪取消按钮。
|
||
- 进度同时使用进度条、百分比和文本，不只依靠颜色。
|
||
- 任务运行时只禁用会改变本次请求的控件，导航、历史查看和无关操作保持可用。
|
||
|
||
### 9.4 日志区
|
||
|
||
- 日志位于主表单下方，使用等宽字体、19px 行高和弱边框。
|
||
- 支持折叠和垂直调整大小；默认高度以 10–14 行为宜。
|
||
- 日志头部显示“执行日志”，底部显示行数或结果摘要。
|
||
- 日志不得显示密码、令牌或带凭据的远程 URL。
|
||
|
||
## 10. Loading 与异步状态
|
||
|
||
所有异步操作遵循同一状态模型：`IDLE -> RUNNING -> SUCCEEDED | FAILED | CANCELLED`。
|
||
|
||
- `IDLE`：按钮显示动词，spinner 不存在。
|
||
- `RUNNING`：主按钮保留宽度，显示 spinner 和进行中文案；禁止重复触发。
|
||
- `SUCCEEDED`：恢复按钮，状态区显示结果和可执行下一步。
|
||
- `FAILED`：恢复按钮，显示可读错误和重试入口；不把异常堆栈直接显示给普通用户。
|
||
- `CANCELLED`：恢复按钮，明确显示“已取消”；已生成的有效结果不得被误删。
|
||
|
||
`LoadingButtonBinder` 是按钮 loading 的唯一绑定入口。窗口不得再次直接拼装 spinner、替换图标或散落调用 `setDisable`。`OperationStatusPane` 负责进度、状态和可选取消；按钮 loading 与任务进度共享同一只读运行状态，避免不同步。
|
||
|
||
## 11. 可访问性与键盘
|
||
|
||
- 所有图标按钮必须有 accessible text 和 Tooltip。
|
||
- 侧栏展开/折叠后保持合理的 Tab 顺序和焦点位置。
|
||
- 焦点环必须清晰可见，不能通过全局 CSS 移除。
|
||
- 文本与背景、禁用状态、选中状态满足可辨识对比度；最终通过实际渲染和对比度工具复核。
|
||
- 任务状态变化同步更新 accessible text；成功、失败和运行状态不只依靠颜色或动画。
|
||
- 动画只用于 120–180ms 的侧栏宽度/透明度过渡和 spinner；若 JavaFX 动画造成布局抖动，则优先稳定布局并取消宽度动画。
|
||
|
||
## 12. 代码边界与可维护性
|
||
|
||
建议拆分为以下独立单元：
|
||
|
||
- `DesignTokens`：语义字体、颜色、间距、尺寸和圆角；不得包含业务状态。
|
||
- `AppIcon` / `IconFactory`：业务语义到图标库的唯一映射。
|
||
- `AppShell`：顶部栏、侧栏、折叠状态和内容插槽。
|
||
- `NavigationModel`：只描述可见插件、顺序、选择和打开动作。
|
||
- `PageHeader` / `SectionHeader`：统一标题结构。
|
||
- 现有 `LoadingButtonBinder` 和 `OperationStatusPane`：继续作为异步展示边界，不引入第二套 loading 组件。
|
||
|
||
插件窗口只组合公共组件和业务控件，不负责设置全局字体、应用背景、侧栏或系统设置入口。禁止新增大段 `setStyle(...)`；动态状态通过伪类或语义 CSS class 表达。
|
||
|
||
## 13. 实施优先级
|
||
|
||
### P0：应用外壳与设计令牌
|
||
|
||
- 字体栈、色彩、间距、控件尺寸和全局 CSS。
|
||
- 统一图标注册表。
|
||
- 新顶部栏、系统设置入口和可折叠侧栏。
|
||
- 基础控件和焦点/禁用/loading 状态。
|
||
|
||
### P1：API 文档导出
|
||
|
||
- 按基准图重排“导出配置”。
|
||
- 复用现有 Tab、请求、代理、历史和异步控制器。
|
||
- 添加可调整日志区及任务状态一致性测试。
|
||
|
||
### P2：其余核心插件迁移
|
||
|
||
- MyBatis 逆向工程、MyBatis SQL 导出、扫描、Git 同步、文本对比。
|
||
- 每个插件只迁移页面骨架与样式，不改变业务流程。
|
||
|
||
### P3：受限适配与收尾
|
||
|
||
- Git 分支评审、手机 UI 自动化、系统设置只做主题和外壳适配。
|
||
- 清理遗留 Emoji、任意字号和内联样式。
|
||
- 全量视觉回归、键盘与可访问性验收。
|
||
|
||
## 14. 测试与验收
|
||
|
||
### 14.1 自动化
|
||
|
||
- 设计令牌、字体回退和图标语义映射单元测试。
|
||
- 侧栏展开/折叠、选择保持、Tooltip 和 accessible text 组件测试。
|
||
- 系统设置只存在一个应用级入口的结构测试。
|
||
- `LoadingButtonBinder` 在五种状态下的文案、spinner、禁用和恢复测试。
|
||
- API 导出三种模式、代理开关、请求构造、运行/取消/失败恢复和历史刷新测试。
|
||
- 架构约束：插件窗口不得新增 Emoji 导航图标、直接 loading 拼装或应用级系统设置入口。
|
||
|
||
### 14.2 视觉验收
|
||
|
||
在相同窗口尺寸和相同业务状态下，将实现截图与视觉基准并排比较，逐项检查：
|
||
|
||
- 顶部栏与侧栏尺寸、折叠行为和唯一系统设置入口。
|
||
- 字体层级、行高、标签与输入字段对齐。
|
||
- 图标风格、尺寸、基线及图文间距。
|
||
- 内容留白、边框、圆角、颜色和无多余嵌套卡片。
|
||
- API 导出模式选择、进度操作行和日志区。
|
||
- loading 时按钮宽度稳定、spinner 不抖动、无关操作可用。
|
||
|
||
视觉稿中的 macOS 红黄绿窗口按钮不属于验收目标；Windows 原生标题栏显示正常即为通过。
|
||
|
||
### 14.3 完成标准
|
||
|
||
- Maven 全量测试和编译通过。
|
||
- `git diff --check` 通过。
|
||
- 主要插件在展开和折叠侧栏下均无裁切、重叠或跳动。
|
||
- 1024px 与 1440px 宽度下核心流程可用；低于最小支持宽度时允许滚动，不允许控件消失。
|
||
- 系统设置只在右上角出现，侧栏无重复项。
|
||
- 全局导航不再使用 Emoji，业务插件无新增任意字号或重复 loading 代码。
|
||
- Git 分支评审和手机 UI 自动化的业务结构保持不变。
|