42 KiB

Raw Blame History

Geopro 3.0 桌面客户端 — 视觉设计规范（Design System）

版本 v1.0 · 适用范围：Geopro 3.0 桌面客户端全部界面 技术载体：Qt 6（QtWidgets）+ Fusion QStyle + QSS + QPalette + QtAwesome + VTK 模式：Light（依据原型还原）/ Dark（同一设计语言派生）

本规范是客户端视觉的单一事实来源。Claude Code 在实现任何界面时，颜色、间距、字号、圆角、控件尺寸、状态表达一律引用本文档的 token，禁止在各 widget 中即兴硬编色值。所有 token 应集中定义在一个主题模块（见 §13），全局通过主题对象访问。

0. 设计原则

数据为主，UI 退后：中间的 2D/3D 视图与剖面图是视觉焦点，外围面板（树、列表、属性）使用克制的中性色，不与数据争夺注意力。
浅色为默认，深色为派生：原型为浅色界面，Light 为基准模式；Dark 按相同色相、相同层级关系派生，保证两套是「同一语言的明暗版本」。
信息密度优先：勘探软件信息密集，控件紧凑、间距节制、对齐严谨，而非消费级 App 的宽松留白。
强调色克制：主强调色（科技蓝）只用于可交互的主操作、选中态、链接、聚焦；状态色只用于状态表达，不作装饰。
视图区永远深色：无论 Light/Dark 模式，中间的 2D 地图 / 3D 视图 / 剖面图画布始终是深色衬底（原型即如此），让色阶数据更突出。这意味着「模式切换」主要影响外围 UI，视图画布的深色基调保持稳定。
双模式同构：同一组件在两种模式下结构、间距、字号完全一致，仅颜色 token 取值不同。

1. 色彩系统（Color Tokens）

色彩采用语义化分层：原始色板（Primitives）→ 语义 token（Semantic）。组件只引用语义 token，不直接引用原始色板，便于换肤。

1.1 原始色板 · 主强调色（Brand / Primary）

科技蓝，取自原型导航高亮、主按钮、链接、选中态。

Token	色值	用途
`--primary-50`	`#EFF5FF`	最浅，选中行背景、hover 底
`--primary-100`	`#DBE8FE`	浅强调背景
`--primary-200`	`#BFD4FD`
`--primary-300`	`#93B4FA`
`--primary-400`	`#5E8DF5`
`--primary-500`	`#3B73EC`	主强调色（Light 主按钮、链接）
`--primary-600`	`#2B5FD9`	主按钮 hover
`--primary-700`	`#2450B8`	主按钮 pressed
`--primary-800`	`#21478F`
`--primary-900`	`#1B3A6E`

Dark 模式主强调略微提亮以保证深底对比度：Dark 主强调用 --primary-400 (#5E8DF5)，hover 用 --primary-300。

1.2 原始色板 · 中性灰阶（Neutral）

界面骨架色，决定整体气质。

Token	色值	说明
`--neutral-0`	`#FFFFFF`	纯白
`--neutral-25`	`#FCFCFD`	面板底
`--neutral-50`	`#F7F8FA`	应用背景（Light 工作区底）
`--neutral-100`	`#EFF1F4`	次级背景、表头底、斑马纹
`--neutral-200`	`#E3E6EB`	边框、分隔线
`--neutral-300`	`#CDD2DA`	输入框边框、禁用边框
`--neutral-400`	`#A8AFBC`	占位文字、禁用文字
`--neutral-500`	`#7C8493`	次要文字、图标默认
`--neutral-600`	`#5A626F`	正文次级
`--neutral-700`	`#3E4551`	正文
`--neutral-800`	`#272C35`	标题文字
`--neutral-900`	`#161A20`	最深文字、Dark 面板底
`--neutral-950`	`#0E1116`	Dark 应用背景

1.3 原始色板 · 视图画布专用深色（Canvas）

2D/3D/剖面画布的衬底，两种模式通用。

Token	色值	说明
`--canvas-bg`	`#0B1320`	视图画布主背景（原型深蓝黑）
`--canvas-bg-soft`	`#111B2D`	画布内浮层（如「列表显示栏」浮窗）底
`--canvas-grid`	`#1E2A3D`	画布网格线、坐标轴
`--canvas-overlay`	`rgba(10,17,28,0.82)`	画布上的标签底（如 ERT1 标注牌）
`--canvas-text`	`#E6ECF5`	画布上文字
`--canvas-text-dim`	`#8A97AC`	画布上次要文字（坐标、比例尺）

1.4 语义色 · 状态色（Status）

来自原型异常分级（红=高/低阻异常、橙=中等、蓝=边界/信息）与通用反馈。每个状态含 主色 / 浅底 / 边框 三档。

语义	主色(Light)	主色(Dark)	浅底(Light)	浅底(Dark)	用途
Danger / 高（红）	`#E5484D`	`#FF6166`	`#FDECEC`	`#3A1D1F`	高等级异常、错误、删除
Warning / 中（橙）	`#E08A1E`	`#F5A623`	`#FBF0DD`	`#3A2C12`	中等异常、警告
Success（绿）	`#2E9E5B`	`#46C07A`	`#E7F6ED`	`#16301F`	成功、在线、就绪
Info / 低（蓝）	`#3B73EC`	`#5E8DF5`	`#EFF5FF`	`#16243F`	信息、低等级、边界过渡
Neutral / 离线（灰）	`#7C8493`	`#8A93A3`	`#F0F1F4`	`#23282F`	离线、停用、未知

异常分级专用（原型异常列表左侧圆点 + 标签「高/中/低」）：高=Danger、中=Warning、低=Info，停用/隐藏=Neutral。三维视图与剖面图中的异常标注牌也用同一组色。

1.5 语义 token 映射表（组件取此层）

语义 token	Light 取值	Dark 取值
`bg/app`	`neutral-50`	`neutral-950`
`bg/panel`	`neutral-0`	`neutral-900`
`bg/panel-subtle`	`neutral-25`	`#161B22`
`bg/header`	`neutral-0`	`#12161C`
`bg/hover`	`neutral-100`	`#1B2129`
`bg/selected`	`primary-50`	`#16243F`
`bg/canvas`	`canvas-bg`	`canvas-bg`
`border/default`	`neutral-200`	`#262C35`
`border/strong`	`neutral-300`	`#333B45`
`border/focus`	`primary-500`	`primary-400`
`text/primary`	`neutral-800`	`#E6E9EF`
`text/secondary`	`neutral-600`	`#A4ADBB`
`text/tertiary`	`neutral-500`	`#7A8494`
`text/disabled`	`neutral-400`	`#5A626F`
`text/link`	`primary-500`	`primary-400`
`text/on-primary`	`neutral-0`	`neutral-0`
`accent/primary`	`primary-500`	`primary-400`
`accent/primary-hover`	`primary-600`	`primary-300`
`accent/primary-pressed`	`primary-700`	`primary-500`
`divider`	`neutral-200`	`#22272F`
`scrollbar/thumb`	`neutral-300`	`#3A424D`
`scrollbar/thumb-hover`	`neutral-400`	`#4A535F`

2. 字体与排版（Typography）

2.1 字族

用途	字体栈
中文 UI	`"Microsoft YaHei UI", "PingFang SC", "Source Han Sans SC", "Noto Sans CJK SC", sans-serif`
西文/数字	`"Segoe UI", "Inter", "Helvetica Neue", Arial, sans-serif`
等宽（坐标/数值/编号/日志）	`"Cascadia Code", "JetBrains Mono", "Consolas", monospace`

macOS 优先 PingFang SC + SF Pro。数值、坐标（如 103.85°E · 36.72°N · z=1.0x）、批次号、深度刻度一律用等宽字体，保证对齐。

2.2 字号阶梯（pt，桌面端基准）

Token	字号	字重	行高	用途
`text/display`	18	600	26	空状态大标题（少用）
`text/title`	14	600	22	对话框标题、首选项分组标题
`text/heading`	12.5	600	20	面板标题栏（「对象显示栏」「属性」等）
`text/body`	11.5	400	18	正文、列表项、表单值
`text/body-strong`	11.5	600	18	强调正文、选中项
`text/label`	11	400	16	表单标签、次要说明
`text/caption`	10	400	14	辅助信息（日期、计数、单位）
`text/mono`	11	400	16	数值/坐标/编号

桌面端字号偏小（信息密度优先）。如需适配高 DPI，按系统缩放因子整体放大，不单独改 token。

3. 间距、圆角、阴影、边框（Spacing / Radius / Elevation）

3.1 间距阶梯（px，4 的倍数节奏）

Token	值	典型用途
`space/3xs`	2	图标与文字微距
`space/2xs`	4	紧凑控件内边距
`space/xs`	6	列表项上下内边距
`space/sm`	8	控件内边距、小间隔
`space/md`	12	面板内边距、表单行距
`space/lg`	16	分组间距
`space/xl`	24	对话框内边距
`space/2xl`	32	大区块分隔

3.2 圆角

Token	值	用途
`radius/none`	0	表格、树（贴合密集布局）
`radius/sm`	4	按钮、输入框、标签
`radius/md`	6	卡片、列表项、浮层
`radius/lg`	8	对话框、画布浮窗
`radius/pill`	999	胶囊标签、开关、计数徽标

3.3 边框

默认边框宽度 1px，颜色 border/default。
聚焦态边框 1px border/focus + 外发光 0 0 0 2px primary-100（Light）/ primary-900 透明度 描边（Dark）。
分隔线用 divider，1px。

3.4 阴影（仅浮层使用，界面整体扁平）

Token	Light	Dark
`shadow/popover`	`0 4px 16px rgba(20,30,50,0.12)`	`0 4px 16px rgba(0,0,0,0.5)`
`shadow/dialog`	`0 12px 40px rgba(20,30,50,0.18)`	`0 12px 40px rgba(0,0,0,0.6)`
`shadow/dropdown`	`0 2px 10px rgba(20,30,50,0.10)`	`0 2px 10px rgba(0,0,0,0.45)`

树、列表、表格、面板不使用阴影（扁平、紧凑）。仅菜单、下拉、tooltip、对话框、画布浮窗使用。

4. 布局框架（依据原型还原）

原型即客户端「项目分析视图」工作台，整体为 顶栏 + 三栏主体 + 中列上下分割 的多面板结构（用 ADS 实现停靠）。

4.1 整体栅格

┌──────────────────────────────────────────────────────────────┐
│  顶栏 TopBar (高 48px)                                          │
├────────────┬───────────────────────────────┬─────────────────┤
│ 左栏        │ 中列上：2D/3D 视图画布          │ 右栏上：异常列表  │
│ 对象显示栏   │ (深色 canvas，含浮窗/工具)      │ /对象属性 (Tab)  │
│ (树)        ├───────────────────────────────┤                 │
│            │ 中列下：数据详情                 ├─────────────────┤
│ 数据集显示栏 │ (Tab + 工具条 + 剖面图)         │ 右栏下：属性      │
│ (列表)      │                               │ (键值表)         │
└────────────┴───────────────────────────────┴─────────────────┘

4.2 各区尺寸建议

区域	尺寸	说明
顶栏 TopBar	高 `48px`	固定
左栏	默认宽 `280px`，可拖拽 `220–400px`	上下两段：对象树 + 数据集列表
右栏	默认宽 `340px`，可拖拽 `280–460px`	上下两段：异常/属性 Tab + 属性键值表
中列	自适应填充	上下分割：视图画布（占比大）+ 数据详情
面板标题栏	高 `36px`	含图标 + 标题 + 右侧动作按钮
面板间分隔条（splitter）	`4px` 命中区，视觉 `1px`	hover 显示 `accent/primary`

4.3 面板标题栏规范（所有可停靠面板统一）

左：14px 图标（QtAwesome）+ text/heading 标题，可带计数（如「异常列表 2/3」）。
右：动作按钮区（如筛选漏斗、+、展开/折叠、全屏），图标按钮 24×24px，hover 显示 bg/hover 底。
底部 1px divider。
背景 bg/panel。

5. 顶栏 TopBar（依据原型）

从左到右的元素与规范：

元素	规范
Logo	左起，高 `24px`，含下拉箭头（切换工作空间/企业）
项目名 + 区域	图标 + 项目名（`text/body-strong`）+ 区域下拉胶囊（`primary` 文字 + 浅底）
主导航（视图分析/项目管理/业务工具）	文字 tab，含图标；当前项 `accent/primary` + 底部 `2px` 高亮条；业务工具带下拉箭头
右侧工具组	设备（主按钮样式，`accent/primary` 填充）、帮助(?)、通知(铃铛，含红点徽标)、设置(齿轮)、用户头像+姓名+角色
背景	`bg/header`，底部 `1px` `divider`
图标按钮尺寸	`32×32px`，hover `bg/hover`
通知红点	`8px` 圆点，`Danger` 色，右上角

6. 核心组件规范

6.1 对象树（左栏上 · 对象显示栏）

原型特征：多级树，每行含「复选框 + 状态圆点 + 类型图标 + 名称 + 右侧计数」。

元素	规范
行高	`28px`
缩进	每级 `16px`，展开箭头 `12px`
复选框	`14px`，选中 `accent/primary` 填充 + 白勾；三态（半选）用横线
状态圆点	`8px` 实心圆，颜色映射对象状态/数据集色（蓝/绿/橙/红，与右侧异常色一致）
类型图标	`14px` QtAwesome，`text/secondary` 色
名称	`text/body`；选中行 `text/body-strong`
计数徽标	右对齐，`text/caption`，`text/tertiary` 色；可加 `pill` 浅底
选中行	底 `bg/selected`，左侧 `2px` `accent/primary` 竖条
hover 行	底 `bg/hover`
分组节点（GS）	名称略强，可加定位图标

6.2 数据集列表（左栏下 · 数据集显示栏）

原型特征：顶部 Tab（数据 / 文件，带计数）+ 列表项（含状态点、标题、日期·通道数）。

元素	规范
段 Tab	「数据 2 / 文件 3」，胶囊式分段控件（见 6.9）
列表项高	`52px`（双行：标题 + 元信息）
标题	`text/body`，含前置状态圆点
元信息行	`text/caption` `text/tertiary`，如「2026-03-15 09:21 · 64 道」
选中项	`bg/selected` + 左 `2px` 竖条 + `radius/md`
右上工具	筛选漏斗、导出图标

6.3 异常列表（右栏上 Tab1）

原型特征：每条含左侧状态竖条 + 圆点 + 名称 + 等级标签 + 多行属性 + 右侧眼睛(显隐)。

元素	规范
卡片项	`radius/md`，左 `3px` 状态色竖条，内距 `space/sm`
卡片底	对应状态浅底（高=Danger 浅底、中=Warning 浅底、低=Info 浅底）
名称	`text/body-strong` + 圆点
等级标签	胶囊标签，状态色（见 6.8）
属性行	`text/caption`，如「140m · 18m / 32 Ω·m」，数值用等宽
显隐开关	右侧眼睛图标，开=`text/secondary`，关=`text/disabled` + 斜杠眼
标题计数	「异常列表 2/3」=可见/总数

6.4 属性键值表（右栏下 · 属性）

原型特征：两列键值，左键右值，多组。

元素	规范
行高	`28px`
键	左列，`text/label` `text/secondary`，定宽约 `72px`
值	右列，`text/body` `text/primary`，数值/日期用等宽；可右对齐
分组标题	`text/heading`，上留 `space/md`
可编辑值	hover 显示编辑图标；进入编辑变为内联输入框
链接值	指向其他数据集的属性显示为 `text/link`，点击跳转新建详情页

6.5 视图画布（中列上 · 2D/3D）

始终深色（bg/canvas），不随模式切换变浅。

元素	规范
视图切换	左上「二维地图 / 三维视图」分段 tab，深色版分段控件
画布浮窗（列表显示栏）	左上浮层，底 `canvas-bg-soft` + `radius/lg` + `shadow/popover`，半透明
画布内文字	`canvas-text` / `canvas-text-dim`
标注牌（ERT1 等）	底 `canvas-overlay`，白字，`radius/sm`
右上控件	底图切换下拉（天地图等）、缩放 +/-，深色按钮
右下状态条	坐标/比例尺，`canvas-text-dim`，等宽字体
缩放按钮	`28×28px`，深色半透明底，hover 提亮
顶部状态徽标	如「3/4 测线可见」，圆点 + `text/caption`

6.6 数据详情区（中列下 · 剖面图）

原型特征：Tab（采集批次）+ 二级 Tab（原数据/网格数据）+ 工具条 + 剖面图 + 色阶条。

元素	规范
标题栏	图标 +「数据详情」+ 右侧设置/下载图标
批次 Tab	可关闭的多 Tab（数据集详情以 Tab 呈现，见 6.10）
二级 Tab	「原数据 / 网格数据」文字 tab
工具条	一排工具按钮（异常标注/色阶配置/白化/滤波处理）= 次按钮(描边)样式，带图标；右侧为复选框组（显示异常/等值线等）+ 滑块（简化容差）+ 右端图标按钮（网格/另存为）
复选框组	行内排列，`14px` 复选框 + `text/label`
滑块	见 6.13
剖面图画布	深色衬底；色阶填充用数据色阶（见 §8）
色阶条（legend）	底部水平色带 + 刻度（等宽数字）+ 单位标签
深度/距离轴	轴标题 `text/caption`，刻度等宽

6.7 按钮（Button）

类型	Light	Dark	用途
Primary（主）	底 `accent/primary` 白字，hover `accent/primary-hover`	同（用 Dark 强调取值）	设备、确定、主操作；每个区域≤1个
Secondary（次/描边）	描边 `border/strong` + `text/primary`，hover `bg/hover`	同	工具条按钮、取消
Tertiary（文字/幽灵）	无边无底 `text/secondary`，hover `bg/hover`	同	次要动作、图标按钮
Danger	底/描边 `Danger`	同	删除等破坏性操作
Link	`text/link` 无底	同	内联跳转

高度：标准 28px，紧凑（工具条）26px，大（对话框主操作）32px。
内距：水平 space/md，图标与文字间距 space/xs。
圆角 radius/sm。禁用态：text/disabled + 不变底色 + 光标禁用。

6.8 标签 / 徽标（Tag / Badge）

类型	规范
状态标签（高/中/低）	胶囊 `radius/pill`，状态浅底 + 状态主色文字，`text/caption`，内距 `space/2xs space/sm`
计数徽标	圆形/胶囊，`text/tertiary` + `neutral-100` 底；通知红点为纯 `Danger` 圆点
类型徽标	中性，`neutral-100` 底 + `text/secondary`

6.9 分段控件（Segmented / 视图切换、数据/文件 Tab）

容器：neutral-100 底（Dark #1B2129）+ radius/md，内距 2px。
选中段：bg/panel 底 + text/primary + 轻阴影（浮起感）。
未选段：透明 + text/secondary，hover text/primary。
深色画布上的分段控件（视图切换）用深色版：容器半透明深底，选中段 accent/primary 文字。

6.10 标签页（Tabs · 数据集详情多 Tab）

标签：text/body，当前项 text/primary + 底部 2px accent/primary；非当前 text/secondary。
可关闭：每个 Tab 右侧 ×（hover 显示），底色 hover bg/hover。
新建详情页 = 新增 Tab；列表选中与 Tab 双向联动（选中 Tab 高亮）。
溢出：超出宽度显示左右滚动箭头或下拉列出全部 Tab。

6.11 大视图模式（剖面/属性页全屏）

触发后该详情页覆盖「标题菜单以下区域」，其余面板隐藏。
右上角显示「按 Esc 退出大视图」提示条（canvas-overlay 底，text/caption，2 秒后淡出）。

6.12 复选框 / 单选 / 开关

控件	规范
复选框	`14px`，未选描边 `border/strong`；选中 `accent/primary` 填充 + 白勾；半选横线；禁用降透明
单选框	`14px` 圆，选中 `accent/primary` 圆环 + 实心点
开关 Switch	宽 `36px` 高 `20px` 胶囊，关=`neutral-300` 底，开=`accent/primary` 底，滑块白色 `16px`

6.13 滑块（Slider · 如简化容差）

轨道 4px neutral-200（Dark #2A313B），已填充段 accent/primary。
滑块手柄 14px 白圆 + 1px border/strong + 轻阴影；hover 放大到 16px。
当前值标签：右侧等宽数字。

7. 表单、表格、对话框等通用组件（补充 · 原型未全部出现但客户端必备）

7.0 表单布局（编辑态 / 只读态）— 总则

本节是「编辑/只读表单」的单一事实来源，统一约束四类表单：①弹出编辑/新建对话框、②属性子视图（对象属性 / 数据集属性）、③动态表单（getDynamicForm 驱动）、④首选项设置。控件本身的样式仍引用 §7.1–7.3、§6.12–6.13；本节只定义「把这些控件组织成一张表单」的布局、分组、状态、校验与配色规则。

设计取向（参考主流优秀客户端）：macOS 系统设置 / Windows 11 设置（分组卡片 + 左标签）、JetBrains IDE 设置（密集左标签）、Figma 右侧属性面板（紧凑内联编辑）、Linear / Stripe（清晰节奏与即时校验）。在「信息密度优先」（§0.3）前提下取其密集左标签 + 清晰分组 + 即时校验 + 克制留白。

7.0.1 两种表单形态（先定形态，再排布局）

形态	用途	实现
只读表单（展示）	纯查看的属性详情	用 §6.4 属性键值表（键值两列，数值等宽，不可编辑）
可编辑表单（编辑/新建）	编辑、新建、设置	用本节「标签 + 控件」行式表单

铁律：一张表单只要存在任一可编辑字段，整张表即用「可编辑表单」形态；其中的只读字段以禁用态控件（§7.1 禁用）呈现，不得在同一张表单里一半键值表、一半输入框——保证可编辑与只读字段在同一栅格中对齐一致。

7.0.2 表单栅格与行结构

元素	规范
标签位置	左侧标签列（默认，密集专业风），标签文字右对齐贴近字段；字段名过长或窄单列对话框可改顶部标签
标签列宽	可编辑表单固定 `100px`（`space::kFormLabelCol`，右对齐，跨表单等宽）；纯只读键值表固定 `72px`（`space::kDetailKeyCol`，§6.4）。不取区间——区间会让不同实现各选一值而漂移
标签 ↔ 字段间距	`space/md`(12)
字段控件高	`28px`（§7.1）；行与行垂直间距 `space/sm`(8)
字段宽度	宽面板/对话框中不要拉满，单字段最大宽约 `360px`（多行/长文本可更宽）；窄属性面板中填充可用宽度
表单内边距	对话框内 `space/xl`(24)；面板内 `space/lg`(12–16)
列数	单列优先；信息多用分组而非多列。仅「短字段（数值+单位）」可两列并排

7.0.3 分组（Section）

分组标题：text/heading，上方留 space/lg，标题下可加 1px divider 贯通。
组内字段紧凑（行距 space/sm），组间留 space/lg–space/xl。
对话框内多组（对齐原版 getDynamicForm 的基本信息 / 测线布设 / 数据质量等）：组数多时用锚点分组或分页签，避免一屏堆叠过长。

7.0.4 字段状态与标记

标记/态	规范
必填	标签后红色 `*`（`status/danger`），紧贴标签
可选	默认不标记（保持干净）；确需时标签后加 `text/tertiary` 的「（可选）」
只读/禁用	§7.1 禁用态（底 `neutral-50`/Dark `#1A1F26`、文字 `text/disabled`、禁用光标）——明确不可编辑，其值仍随表单提交
错误	§7.1 错误态：描边 `status/danger` + 字段下方 `text/caption` `status/danger` 说明
帮助/说明	字段下方 `text/caption` `text/tertiary` 一行（与错误说明互斥位置）
单位/前后缀	框内右端 `text/tertiary`（§7.1 前后缀）

7.0.5 校验与提交反馈

即时校验：失焦/输入时校验单字段，错误就地显示（§7.1 错误态），不打断输入。
提交校验：点「保存/确定」校验全表 → 有错则滚动并聚焦第一个错误字段 + 就地显示错误；可同时在表单顶部用行内提示（§7.7 inline alert）汇总「请完善 N 项」。不要只弹一个模糊 toast。
脏标记：表单无用户修改时「保存」按钮置灰不可点；任一字段改动后启用（与已落地的对象属性面板一致）。
提交中：主按钮 loading（spinner/禁用）防重复提交；成功后 Toast（§7.7）+ 关闭或刷新。

7.0.6 弹出编辑 / 新建对话框（body）

外壳遵 §7.5（容器 radius/lg + 标题栏 + 底部操作栏）。body 即本节表单：内距 space/xl、单列左标签、分组按 7.0.3。
底部操作栏：取消（次按钮，左）+ 主操作（确定/保存，Primary，右）；破坏性确认用 Danger（§7.5/§7.6）。
新建 vs 编辑：编辑态预填现值；不可改字段（如类型、按 API 只读的名称）用禁用控件而非省略；标题区分「新建 XX / 编辑 XX」。

7.0.7 四类表单的归口（落地映射）

表单	形态	要点
对象属性面板（对象属性 Tab）	可编辑表单	名称仅顶部显示一处且按 API 只读；只读字段禁用灰显；脏标记控制保存
数据集属性面板	上半 §6.4 只读键值表 + 下半可编辑描述（单字段可编辑表单）	两段职责分明
动态表单（`getDynamicForm`）	可编辑表单	分组 = `formList` 组；控件按 `displayComponentType` 映射（§7.1/7.2/7.3/6.12）；必填/只读由 `requiredType`/`fieldUseType` 决定（7.0.4）
首选项设置（§7.10）	设置型表单变体	主从布局 + 设置行（左：标题+说明，右：控件）

7.0.8 配色与排版令牌（汇总 · 禁硬编码）

角色	token
标签文字	`text/secondary`（必填 `*` 用 `status/danger`）
字段值 / 输入文字	`text/primary`；数值/坐标/编号用等宽 `type::kMonoFamily`
分组标题	`text/heading`
分隔线	`divider`
错误（描边+说明）	`status/danger`
只读字段底/文字	`neutral-50`（Dark `#1A1F26`）/ `text/disabled`
字段背景/边框/focus	见 §7.1（`bg/panel`、`border/default`→`border/strong`→`border/focus`）

7.0.9 可访问性

标签与控件关联（点击标签聚焦其控件 / buddy）。
Tab 焦点顺序自上而下、左到右；焦点环可见（§10、§12）。
不以颜色为唯一信息：必填除 * 外，校验失败有文字说明；错误态有文字。
可点控件最小命中区 ≥ 24×24px（§12）。

7.0.10 实现纪律（单一实现 · 禁止手搭）

本节是 §7.0 能落地的关键。 文档约束管不住代码——同类表单分散在各文件里手搭 QFormLayout/QLabel、各填各的边距与列宽，必然漂移（曾出现：三维体/切片/异常详情用裸 QFormLayout，与属性面板天差地别；同为下拉框，设置页无箭头、对象属性偏矮带箭头）。一致性只能由代码复用强制。

唯一实现（必须经此产出，不得另起炉灶）：
- 只读键值详情 → DynamicFormView（§6.4 渲染器）。对话框用 formkit::DetailForm（链式 group()/row()）构模型，formkit::buildDetailDialog() 铺骨架。
- 可编辑表单 → formkit::makeEditForm() + formkit::editLabel() + formkit::capField() + formkit::addSection()。DynamicFormEditor 与各参数对话框（如「生成三维体」）都走同一组，确保标签列宽/行距/分组/字段上限逐像素一致。
禁止：业务表单/对话框直接 new QFormLayout + new QLabel("名"，值) 手搭键值；禁止在表单里逐处写死边距/列宽/字号（用 space::*/type::* 令牌）。
精确常量（单一来源 Theme.hpp，禁止区间/魔数）：可编辑标签列 space::kFormLabelCol=100；只读键列 space::kDetailKeyCol=72；字段最大宽 space::kFormFieldMax=360；行距 space::kMd；分组上间距 space::kLg。
控件构造一致性：下拉框统一用不可编辑 QComboBox（无候选项的「选择」字段退化为 QLineEdit 自由文本，不得用「可编辑下拉框」——其几何/高度与不可编辑款不一致）。全局 QSS 不覆写 QComboBox::drop-down/::down-arrow，保留 Fusion 原生箭头随调色板自适应（覆写却不提供箭头图会致箭头消失）。QComboBox 的 min-height/padding 与 QLineEdit 完全对齐 → 同高。
新增表单的验收：截图与既有「对象属性 / 数据详情」并排，标签列、行高、分组标题、下拉框外观应无法区分；做不到即说明绕开了上述唯一实现。

7.1 输入框（Text Input）

状态	规范
默认	高 `28px`，底 `bg/panel`，描边 `1px border/default`，`radius/sm`，内距 `space/sm`，`text/body`
hover	描边 `border/strong`
focus	描边 `border/focus` + 外发光
禁用	底 `neutral-50`（Dark `#1A1F26`）+ `text/disabled`
错误	描边 `Danger` + 下方 `text/caption` `Danger` 错误说明
占位符	`text/disabled`
前/后缀	单位、图标置于框内两端，`text/tertiary`

7.2 下拉选择（ComboBox / Select）

外观同输入框 + 右侧 12px 下拉箭头。
展开菜单：bg/panel + radius/md + shadow/dropdown；项高 28px，hover bg/hover，选中项 bg/selected + 勾。
可搜索下拉：顶部带搜索输入框。
多选下拉：选中项以 6.8 标签形式回填到框内。

7.3 数字输入 / 步进器（SpinBox）

输入框 + 右侧上下步进按钮（各 14px 高）；数值等宽右对齐；支持单位后缀。

7.4 表格（Table / DataGrid）

元素	规范
表头	底 `neutral-100`（Dark `#161B22`），`text/label` `text/secondary`，高 `32px`，可排序列带箭头
行高	标准 `32px`，紧凑 `28px`
斑马纹	偶数行 `bg/panel-subtle`（可关闭）
行 hover	`bg/hover`
行选中	`bg/selected` + 左 `2px` 竖条（多选用复选框列）
单元格	内距 `space/sm`，文本 `text/body`，数值等宽右对齐
边框	仅横向 `1px divider`（无竖线，保持轻盈）；密集模式可加竖线
固定列/表头	横向滚动时首列与表头固定
空状态	居中插画/图标 + `text/secondary` 说明 + 可选操作按钮
分页/加载	底部分页器或无限滚动；加载中显示骨架行

元素	规范
遮罩	全屏 `rgba(10,16,26,0.45)`（Dark `rgba(0,0,0,0.6)`）
容器	`bg/panel` + `radius/lg` + `shadow/dialog`；宽按内容（小 `420px` / 中 `560px` / 大 `720px`）
标题栏	`text/title` + 右上 `×`；底 `1px divider`；内距 `space/xl`
内容区	内距 `space/xl`，可滚动
底部操作栏	右对齐：次按钮（取消）+ 主按钮（确定）；破坏性操作主按钮用 Danger；内距 `space/lg space/xl`
进入动画	淡入 + 轻微上移（120ms）

7.6 确认 / 警示框（Confirm / Alert）

小对话框，左侧状态图标（Danger/Warning/Info 圆形图标）+ 标题 + 说明文 + 操作按钮。
删除类：图标 Danger，主按钮 Danger，文案明确后果。

7.7 提示框（Toast / Notification）

类型	规范
Toast（瞬时）	右上或底部居中浮出，`bg/panel` + 状态色左竖条 + 图标 + 文案；`radius/md` + `shadow/popover`；3–4s 自动消失；可手动关闭
行内提示（Inline alert）	块状，状态浅底 + 状态色左竖条 + 图标 + 文案；用于表单顶部、面板内提示
通知中心（铃铛）	顶栏铃铛下拉面板，列表项含图标/标题/时间/已读态；未读左侧圆点

Tooltip：深色小气泡（Light 也用深色 neutral-800 底 + 白字），text/caption，radius/sm，延迟 400ms 显示。
Popover：bg/panel + radius/md + shadow/popover，可含富内容（如对象快速属性 tip）。

7.9 菜单（右键菜单 / 下拉菜单）

元素	规范
容器	`bg/panel` + `radius/md` + `shadow/dropdown`，内距 `space/2xs`
项	高 `28px`，左图标 `14px` + 文字 + 右侧快捷键（`text/tertiary` 等宽）
hover	`bg/hover`
分隔	`1px divider`，上下 `space/2xs`
危险项	`Danger` 文字（如删除）
子菜单	右侧箭头，hover 展开
禁用项	`text/disabled`

对象树/数据集右键菜单按规约功能：显示/隐藏、定位、属性、异常详情、编辑、新建 GS/TM、导入数据集、删除等。

7.10 首选项 / 设置（Preferences）

原型顶栏齿轮入口，客户端必备完整设置界面。

元素	规范
结构	左侧分类导航（垂直列表）+ 右侧设置项面板（主从布局）
分类项	高 `32px`，图标 + 名称，选中 `bg/selected` + 左竖条
设置项行	左：标题（`text/body`）+ 说明（`text/caption text/tertiary`）；右：控件（开关/下拉/输入）
分组	分组标题 `text/heading` + `divider`
建议分类	外观（主题：跟随系统/浅色/深色、字体、字号缩放）、启动画面与停留时间、默认大屏、语言（中/英）、坐标系默认、底图与缓存、更新（检查/通道）、账户、关于（版本/许可/Qt 源码声明）

7.11 空状态 / 加载 / 骨架屏

空状态：居中 48px 灰度图标 + text/body secondary 主文案 + text/caption 辅助 + 可选主操作按钮。
加载：局部用旋转 spinner（accent/primary）；区块用骨架屏（neutral-100/#1B2129 矩形微动画）。
进度：长任务（如在线更新、VTK 大数据加载）用进度条 accent/primary + 百分比等宽数字。

7.12 滚动条

细滚动条：宽 8px，thumb scrollbar/thumb + radius/pill，hover scrollbar/thumb-hover，轨道透明；overlay 模式（悬停才显）。

7.13 树/列表筛选器（漏斗）

面板标题栏漏斗图标 → 弹出 Popover：含搜索框 + 多选类型复选组 + 日期范围 + 「应用/重置」。
激活筛选时漏斗图标显示 accent/primary + 角标计数。

8. VTK 视图配色（与 UI 对齐）

关键约束：QSS/QPalette 不作用于 VTK 渲染窗口。VTK 画布配色须通过 VTK API 单独设置，并与 §1.3 画布 token 手动对齐，避免「UI 深色、视图另一种灰」的割裂。VTK 画布在两种模式下都用深色。

8.1 渲染窗口基础

VTK 元素	取值（对齐 token）
渲染器背景（renderer background）	`canvas-bg` `#0B1320`；可用上下渐变到 `#0E1626`
三维网格/地面网格	`canvas-grid` `#1E2A3D`
坐标轴（axes actor）	X/Y/Z 用低饱和红/绿/蓝，标签 `canvas-text-dim`
文字标注（vtkTextActor）	`canvas-text` `#E6ECF5`，等宽字体
比例尺/方位	`canvas-text-dim`
拾取高亮	`accent/primary` `#5E8DF5` 描边
选中对象包围盒	`accent/primary` 虚线框

8.2 数据色阶（Colormap / Lookup Table）

原型剖面图色阶为电阻率经典彩虹色阶（紫蓝→青绿→黄→橙红→深红，对数刻度 5–1000 Ω·m）。规范：

色阶用途	推荐 colormap	说明
电阻率/极化率（默认）	彩虹/Jet 类（紫→蓝→青→绿→黄→橙→红）	与原型一致；对数刻度；端点可标注异常
连续物理量（通用）	Viridis / Turbo	感知均匀，科学制图推荐
发散量（正负、相对基线）	Coolwarm（蓝-白-红）	如电位差、变化量
地层/分类（离散）	离散调色板（命名色板）	类别明确，高区分度
单色强度	单色渐变（如蓝系）	单一属性强度

色阶须可配置、可命名保存（规约「色阶定义工具」），用户调整后视图实时刷新。
色阶条（legend）渲染在 UI 侧或画布侧均可，但刻度数字用等宽字体，单位明确。
等值线（contour）：默认 canvas-text-dim 细线；标注牌用 canvas-overlay 底。

8.3 异常标注（三维视图 + 剖面图）

异常圈/标注牌颜色 = §1.4 异常分级色（高=Danger、中=Warning、低=Info），与右栏异常列表严格一致。
三维视图中的测线：可见用亮色（红/绿区分极性或测线编号），不可见降透明。

9. 图标系统（QtAwesome）

统一用 QtAwesome（图标字体），全局禁止混用位图图标，保证矢量、可染色、随主题变色。
图标字体集：优先 Material Design Icons (mdi) 或 Font Awesome，全项目统一一套。
标准尺寸：行内 14px，按钮内 16px，面板标题 14px，空状态 48px。
默认色 text/secondary；激活/选中 accent/primary；禁用 text/disabled。
图标语义映射（建议固定，供 Claude Code 一致引用）：

语义	图标（mdi 名参考）
对象树/层级	`file-tree` / `sitemap`
GS 分组/定位	`map-marker`
数据集	`database` / `chart-line`
文件	`file-document`
二维地图	`map`
三维视图	`cube-outline`
异常	`alert-circle`
属性	`information-outline`
筛选	`filter-variant`
新增	`plus`
导出/下载	`download` / `export`
显隐	`eye` / `eye-off`
全屏	`fullscreen` / `fullscreen-exit`
设置	`cog`
通知	`bell`
帮助	`help-circle`
设备	`access-point` / `chip`
色阶配置	`palette`
白化/滤波	`blur` / `wave`
网格	`grid`
缩放	`magnify-plus` / `magnify-minus`

10. 状态与交互反馈

交互态	表现
hover	背景 `bg/hover` 或控件提亮，`120ms` 过渡
pressed	加深一档
focus（键盘）	`border/focus` + 外发光，键盘可达性必须保留
selected	`bg/selected` + 左竖条
disabled	`text/disabled` + 降透明 + 禁用光标
loading	spinner / 骨架 / 进度条
drag（异常合并、图层排序）	拖拽项半透明跟随 + 目标位置 `accent/primary` 插入线
实时刷新（色阶/图例调整）	视图即时重绘，无整页闪烁

动效克制：仅用 120–200ms 的 hover/展开/淡入过渡，专业工具避免花哨动画。

11. 双模式切换规范

三种选项：跟随系统 / 浅色 / 深色（首选项 §7.10 + 顶栏快捷切换可选）。
切换时：外围 UI（顶栏、面板、树、列表、表单、对话框）整体换肤；视图画布与剖面图保持深色基调不变（仅 UI 边框等微调）。
切换应即时、无重启；通过统一主题对象广播刷新所有 widget 的 QSS + QPalette。
VTK 渲染器背景在两模式下均深色，不参与切换（仅当用户在首选项单独设置画布背景时才改）。

12. 可访问性与适配

对比度：正文文字与背景对比度 ≥ 4.5:1，大字 ≥ 3:1（两种模式都须校验，Dark 模式尤其注意状态浅底上的文字）。
不以颜色为唯一信息：异常分级除颜色外必须带文字标签（高/中/低）或图标，照顾色觉障碍。
高 DPI：所有尺寸用逻辑像素，随系统缩放因子整体放大；图标用矢量字体。
键盘导航：Tab 焦点环必须可见；树/列表/表格支持方向键。
最小命中区：可点击图标按钮命中区 ≥ 24×24px。

13. 实现约定（给 Claude Code）

集中定义 token：建一个主题模块（如 src/ui/theme/），包含 Theme 对象，集中持有所有颜色/间距/字号 token 的两套取值（light/dark）。所有 widget 通过 theme.color("bg/panel") 一类接口取值，禁止散落硬编色值。
QSS 模板化：QSS 写成带占位符的模板，运行时用当前 token 填充生成最终 QSS 字符串并 qApp->setStyleSheet()；切换模式时重新生成并应用。
QPalette 同步：除 QSS 外必须同步设置 QPalette（Window/Base/Text/Highlight/ButtonText 等角色），否则原生绘制控件（菜单、tooltip、部分原生项）颜色不统一。两者取值来自同一 token。
Fusion 为底座：QApplication::setStyle("Fusion")，在其上叠加 QSS + QPalette，不替换为第三方 QStyle。
VTK 配色独立设置：VTK 渲染器背景、坐标轴、文字、色阶用 VTK API 设置，取值引用 §8 / §1.3，与 UI token 对齐；模式切换时画布保持深色。
图标统一走 QtAwesome：封装一个图标工具函数 icon(name, role)，role 决定染色（默认/激活/禁用/状态色），全局复用 §9 映射。
主题切换广播：主题切换时通过信号通知所有顶层窗口重应用 QSS/QPalette 并刷新 QtAwesome 图标颜色。
可视化校验：实现后用 light/dark 各截图核对本规范（对比度、状态色一致性、视图画布与 UI 的衔接）。

附录 A：核心语义色速查（开发对照）

Light

用途	色值
应用背景	`#F7F8FA`
面板背景	`#FFFFFF`
hover	`#EFF1F4`
选中	`#EFF5FF`
边框	`#E3E6EB`
主文字	`#272C35`
次文字	`#5A626F`
主强调	`#3B73EC`
视图画布	`#0B1320`
高/Danger	`#E5484D`
中/Warning	`#E08A1E`
低/Info	`#3B73EC`
成功	`#2E9E5B`

Dark

用途	色值
应用背景	`#0E1116`
面板背景	`#161A20`
hover	`#1B2129`
选中	`#16243F`
边框	`#262C35`
主文字	`#E6E9EF`
次文字	`#A4ADBB`
主强调	`#5E8DF5`
视图画布	`#0B1320`（同 Light）
高/Danger	`#FF6166`
中/Warning	`#F5A623`
低/Info	`#5E8DF5`
成功	`#46C07A`

本规范依据客户提供的 Web 原型（浅色）提取并派生深色模式，覆盖项目分析视图工作台及客户端通用组件。色值为初始建议值，落地后应结合实机截图微调对比度与一致性，并随设计迭代维护版本。

42 KiB Raw Blame History Unescape Escape