Files
2026-08-17 13:40:53 +08:00

253 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 系统设置类页面(5 屏)— 视觉边界手册 DESIGN_SPEC
- **模块**:系统设置类页面(语言设置 / 选择版型 / 版本信息 / Logo 授权管理 / 数据上传)
- **日期**:2026-08-16
- **最高约束**:`../BEAUTIFY_BASELINE_20260816.md`(全局美化公约) + `../UI_DEV_GUIDE.md`(Token 宪法)
- **视觉基准**:同目录 `baseline_ui.html`(单文件,双击可开)
- **原始截图**(不复制文件,相对路径引用):
| 屏 | 截图 |
| --- | --- |
| 语言设置 | `../ui_baseline/EAPManageUI/Screenshot_20260812_143341.png` |
| 选择版型 | `../ui_baseline/EAPManageUI/Screenshot_20260812_143347.png` |
| 版本信息 | `../ui_baseline/EAPManageUI/Screenshot_20260812_143456.png` |
| Logo 授权管理 | `../ui_baseline/EAPManageUI/Screenshot_20260812_143502.png` |
| 数据上传 | `../ui_baseline/EAPManageUI/Screenshot_20260812_143450.png` |
> **铁律复述**:本次只做美化。五屏的信息字段、按钮文案、区块顺序、交互范式全部原样保留。
> 下文所有条目都属于「间距 / 对齐 / 描边 / 颜色语义 / 响应式收敛」范畴,不含信息架构改动。
---
## 1. ★ 宽屏内容容器(本模块要沉淀给全 App 的通用栅格规范)
### 1.1 问题
五张截图全部在平板横屏(2944×1840,约 1280dp 宽)下拍摄,**内容一律顶在左上角、右侧留出 40%~60% 空白**。
数据上传页最严重:三个输入框从左标签一直横跨到屏幕最右侧,单行长度超过 1000dp,眼睛需要横扫整块屏幕才能读完一行,
且长 URL 在超宽单行里既读不出结构也无法快速比对。这是全 App 平板体验「廉价感」的头号来源。
### 1.2 规范(**全 App 通用,不限本模块**)
| 项 | 值 | 说明 |
| --- | --- | --- |
| 内容容器最大宽度 | **840px / 840dp** | `--content-max-width`。超过即左右自动留白 |
| 水平对齐 | **居中**(`margin: 0 auto`) | 不是左对齐后加右 padding |
| 左右安全边距 | **24px / 24dp**(`--content-gutter`) | 窗口宽度 < 容器最大宽度时生效 |
| 窄屏断点 | **600dp** | < 600dp 时安全边距降为 16dp,表单标签列由「左列」改为「上置」 |
| 垂直起始留白 | 24dp(页面根 padding-top) | 列表型页面例外,见 1.4 |
| AppBar | **全宽通栏,不进容器** | 对齐 Android `MaterialToolbar` 的物理行为;仅其内部标题遵守 §2 的 inset |
### 1.3 为什么是 840
- 840dp 是 Material 3 Window Size Class 中 **Expanded 的下界**,天然与「平板横屏」这一档对齐;
- 单行正文 15sp 时,840dp 约 60~70 个西文字符 / 40 个汉字,落在最佳阅读行宽区间;
- 与项目已有但仍为空的 `res/values-w600dp/`、`res/layout-w600dp/` 资源目录方向一致,可直接落资源限定符。
### 1.4 三种页面的容器落法
| 页型 | 屏 | 落法 |
| --- | --- | --- |
| **卡片/表单型** | 选择版型、版本信息、Logo 管理、数据上传 | 滚动容器内包一层 `maxWidth=840dp + layout_gravity=center_horizontal` 的内容 LinearLayout,左右 padding 24dp |
| **通栏列表型** | 语言设置 | **列表本体保持 match_parent**(触摸高亮/涟漪必须通栏,否则宽屏下点击右半屏无反馈),但**每一行的内部内容再收进 840dp 居中盒**,分割线同宽。视觉是居中的,可点区域是通栏的 |
| **AppBar** | 全部 5 屏 | 通栏,不收敛 |
### 1.5 红线
- **禁止**用「左对齐 + 右侧硬塞 padding」冒充居中,窗口再变宽就又偏了。
- **禁止**给 840 容器加背景色或描边把它做成一张「大卡片」——它是不可见的排版栅格,不是视觉元素。
- 容器最大宽度必须走 `@dimen` Token(`content_max_width`),**禁止在 XML 里写死 840dp**。
---
## 2. AppBar 统一规范(5 屏共用,对齐公约 §3)
| 项 | 值 |
| --- | --- |
| 高度 | 56dp(`--appbar-height`) |
| 背景 | `--color-surface`,底部 `1px --divider` |
| 返回箭头 | 图标 24dp,触控槽 48dp,**图标视觉左边界落在距屏幕左 16dp** |
| 箭头与标题间距 | **8dp**(标题文本起点固定在 72dp = 16 + 48 + 8) |
| 标题 | **20sp / 600 / `--text-primary`**,单行,超长 `ellipsize=end` |
| 副标题(若有) | 12sp / `--text-secondary` |
> 截图现状:五屏标题字号目测在 22~24sp 之间浮动,箭头到标题的间距各屏不一(语言设置约 48dp、Logo 管理约 44dp)。统一收口到上表。
---
## 3. 分屏视觉规范
### 3.1 语言设置(`Screenshot_20260812_143341.png`)
| 问题(现状) | 规范(目标) |
| --- | --- |
| 行高偏矮、上下气口不足 | **行高 56dp**(公约 §5.5 的 48dp 是下限,设置类整屏列表提到 56dp 更从容),整行可点,最小点击区 48dp |
| 分割线通栏顶到屏幕最左最右 | 分割线**左端缩进到文字起点**(与 840 容器左边界同轴),右端同样留 24dp 安全边距;**最后一行下方不画线** |
| 选中项只有一个蓝圆点,无背景反馈 | 选中行 `--color-primary-container` 整行底 + 文字 `--color-on-primary-container` + 字重 500;圆点 `--color-primary` |
| 分割线颜色用了 `colorSurfaceVariant`(面色当线色,偏重偏灰) | 统一 `--divider`(12% 黑),1dp |
| 无 hover / pressed 反馈 | hover:primary 4% 透明;pressed:primary 8% 透明(Android 用 `?attr/selectableItemBackground` 的涟漪即可) |
- 文字:语言名 15sp / 400 / `--text-primary`;不缩写、不截断(9 个语种名最长 `Ελληνικά` 也很短,宽屏下永不溢出)。
- 单选圆点:未选中 2dp `--outline` 空心圈;选中 2dp `--color-primary` 圈 + 内实心点。
### 3.2 选择版型(`Screenshot_20260812_143347.png`)
**核心 Bug:两张卡的描边逻辑颠倒。** 现状是「专业版(未选中)=蓝框、自定义功能版(已选中)=绿框」,
描边颜色被写死成卡片身份色,跟选中状态毫无关系,用户第一眼会把蓝框读成「已选中」。
| 状态 | 描边 | 底色 | 圆点 | 投影 |
| --- | --- | --- | --- | --- |
| **未选中** | `1dp --divider` | `--color-surface` | `--outline` 空心 | Level 1 |
| **选中** | `2dp --color-primary` | `--color-primary-container` | `--color-primary` 实心 | Level 2 |
| hover(未选中) | `1dp --outline` | 不变 | 不变 | Level 1 |
- 选中态描边从 1dp 变 2dp 时,**内边距同步 -1dp**(16 → 15dp),保证文字不发生 1px 位移抖动。
- 圆点 tint **两张卡必须一致**,都用 `--color-primary`;现状自定义卡用了 `colorSecondary`(绿),必须去掉。
- 卡片圆角 `--corner-md` 12dp;卡内 padding 16dp;卡间距 16dp。
- 「确定」按钮:确认类 → `--color-secondary-container` 底 + `--color-secondary` 字(保留截图的浅绿视觉),
高度 44dp,圆角 12dp,宽度 `match_parent`(保持截图的通栏形态),但**受 840 容器约束**,不再横跨全屏。
- 顶部图标 72dp、标题 20sp/600、副标题 13sp/`--text-secondary`,整组居中。
### 3.3 版本信息(`Screenshot_20260812_143456.png`)
| 问题 | 规范 |
| --- | --- |
| 三张卡的标签/值没有对齐成列(「硬件 ID:」「设备型号:」「Android 版本:」宽度各不同,值参差) | **左标签列固定 140dp**(`--label-col-width`),值列 `weight=1`;跨卡片共用同一列宽,三张卡的值形成一条通列 |
| 「Debug」红字直接砸在白底上,过于刺眼 | 降级为**徽章**:`--color-error-container` 底 + `--color-error` 字,12sp/600,高 22dp,圆角 `--corner-sm`。Release 走 `--color-secondary-container` + `--color-secondary` |
| 「下载更新」按钮孤悬卡片右下角,与上方文字无任何关联 | 独立成**动作行**:上方加 `1dp --divider` 分割线,行内 `justify-content: flex-end`,与分割线间距 16dp。按钮仍在右侧(不搬家),但被分割线「锚」住,不再漂浮 |
| 卡片同时有描边和阴影 | §4 红线:**只留投影 Level 1**,去掉描边 |
| 卡片间距 / 卡片内边距不一 | 卡片内边距 16dp,卡片之间 16dp |
- 标签 13sp / `--text-secondary`;值 15sp / `--text-primary`。
- 硬件 ID 用等宽字体(`monospace`),并 `word-break: break-all`,超长时**换行而不是截断**(ID 不能被 `…` 吃掉)。
- 版本号:`版本号` 13sp `--text-secondary` + 数值 `--color-primary` 500 字重。
- 「升级来源」是 layout 中真实存在的槽位(`tv_version_info_upgrade_source`),检查阶段显示、无更新时隐藏,**不要在重构时删掉**。
- 底部版权 13sp / `--text-secondary` / 居中。
**系统更新卡状态机**
| 状态 | 表现 |
| --- | --- |
| 检查中 | 状态文案「正在检查更新…」,按钮文案「检查更新」+ `disabled`(opacity .38) |
| 已是最新 | 状态文案「已是最新版本」,按钮「检查更新」可点 |
| 有新版本 | 显示「有新版本可用:x.xx.xxxx」,按钮「下载更新」(confirm 绿) |
| 下载中 | 显示 4dp 高进度条(`--color-primary` / 轨道 `--color-surface-variant`,圆角 999),按钮 disabled |
| 失败 | 状态文案 `--color-error`,按钮恢复为「重试」 |
### 3.4 Logo 授权管理(`Screenshot_20260812_143502.png`)
| 问题 | 规范 |
| --- | --- |
| 分段控件是两个拼在一起的 Outlined 按钮,选中的一个是浅绿底绿字,未选中是白底 + 深描边 | **公约 §5.6**:外层胶囊(999dp)`--color-surface-variant` 底 + 2dp 内衬;选中段 `--color-primary-container` 底 + `--color-on-primary-container` 字 + 前置 ✓ + Level 1 投影;未选中段透明底 + `--text-secondary` 字。段高 36dp,段最小宽 132dp |
| 预览条底色 `colorSurfaceVariant`(灰紫色块),与浅色页面割裂,像贴了一张异物 | 预览条改为 `--color-surface` 底 + `1dp --divider` 描边 + `--corner-md`,高度 56dp(= 真实 AppBar 高度)。**它是「顶部栏的样子」,就该长得像顶部栏,不该是一块深色底板** |
| 计数器「10/15」孤零零悬在输入框右下方外侧,位置突兀 | 计数器归位到**输入框正下方 4dp 的 field-footer 行**内,右对齐,13sp / `--text-secondary`;左侧同一行留给错误提示文案。超限时计数器与提示同时变 `--color-error` |
| 输入框描边偏重 | 默认 `1dp --divider`,聚焦 `2dp --color-primary`(同步 -1dp padding 防抖),圆角 `--corner-sm` |
- 预览条内:返回箭头 24dp `--text-primary`,与标题间距 8dp;标题 20sp/600,`maxLines=1` + `ellipsize=end`(超 15 字符本就被计数器拦住,截断只是兜底)。
- 按钮:「保存文本配置」= confirm 绿(`--color-secondary-container` + `--color-secondary`);「恢复默认名称」= 次按钮(透明底 + `1dp --outline` + `--color-primary` 字)。两按钮固定宽 240dp、居中、纵向间距 16dp(保持截图的上下堆叠形态)。
- **图片 Logo 模式**(截图未拍到,但 layout 中真实存在):预览区无图时走公约 §5.7 三段式空态 —— 56dp `--text-disabled` 图标 → 「暂无 Logo 图片」16sp/500 → 「点击『添加 Logo』上传,建议 PNG 透明底」13sp/`--text-secondary`;图标与主文案间距 16dp,主辅 8dp。加载中显示 `ProgressBar`(`pb_cl900_loading`)。
### 3.5 数据上传(`Screenshot_20260812_143450.png`)
**核心 Bug:三个输入框实际发生了重叠错位。**
- **现象**:「表单上传地址」框的下沿压住「原始数据上传地址」框的上沿;「原始数据上传地址」框整体向右偏移了约一个标签的宽度,
左边界与另外两个框对不齐;三个标签与各自输入框在垂直方向也没对准(标签偏上/偏下不一)。
- **根因**(已核对 `activity_data_upload.xml`):每个 `TextInputLayout` 同时把 `Top_toTopOf` 和 `Bottom_toBottomOf` 约束到了自己那个
`wrap_content` 的标签 `TextView` 上。标签实际只有约 24dp 高,而 OutlinedBox 输入框有 56dp 高——ConstraintLayout 只好把 56dp 的框
**以 24dp 的标签为中心上下各溢出 16dp**。溢出部分不计入下一个控件的排版基准(下一个标签是 `Top_toBottomOf` 上一个 TIL),
于是相邻两组之间就出现了物理重叠。此外三个 TIL 都写了 `layout_weight="1"`,在 ConstraintLayout 里是无效属性,纯噪音。
**规范版式:左标签 + 右输入框 两列对齐**(保留截图原有的「标签在左」信息架构,用户肌肉记忆不变)
```
├── 24dp ──┬──── 140dp 标签列 ────┬── 16dp ──┬───────── 输入框(占满剩余)─────────┬── 24dp ──┤
自动上传数据 [ M3 Switch ]
表单上传地址 [ 56dp 输入框 ]
原始数据上传地址 [ 56dp 输入框 ]
数据传输端口 [ 56dp 输入框 ]
```
| 项 | 值 |
| --- | --- |
| 整块表单容器 | 840dp 居中(§1),左右安全边距 24dp |
| 标签列宽 | **固定 140dp**(`--label-col-width`),四行共用,形成硬左对齐列 |
| 标签 ↔ 输入框水平间距 | 16dp |
| 每行垂直对齐 | `center_vertical` —— 标签在 56dp 输入框的**垂直正中**,不再是「顶对齐 + 溢出」 |
| 行与行的垂直间距 | **16dp**(`--spacing-md` 级),由外层容器统一给,不再靠约束互推 |
| 输入框高度 | 56dp,圆角 `--corner-sm`,描边 `1dp --divider`,左内边距 16dp |
| 开关 | **M3 MaterialSwitch**(52×32dp,轨道 `--color-surface-variant` / 选中 `--color-primary`),替换截图中的黑色胶囊开关(公约 §5.5 明确点名的旧版残留) |
| 三按钮 | 与表单之间加 `1dp --divider` 分割线 + 16dp 间距;按钮横向排列、gap 16dp、高 44dp。「保存」= confirm 绿;「重置」「测试数据上传」= 次按钮(透明底 + `1dp --outline` + primary 字)。**顺序与文案完全不变** |
| 窄屏(< 600dp) | 标签自动上移到输入框正上方(`--label-col-width: 100%`),字号降到 13sp / `--text-secondary`,行内间距 4dp |
**Android 侧的修法(细节见 `implementation_plan.md`)**:
把 `ConstraintLayout` 换成**竖向 `LinearLayout` + 每行一个横向 `LinearLayout(gravity=center_vertical)`**。
四行同构,标签列宽由 `@dimen` 统一给。所有跨控件的顶/底互相约束全部删除——这类错位在约束式布局里极易复发,
线性布局在这个「四行等宽两列表单」的场景下更稳,也更符合「不改结构、只修错位」的目标。
**状态机**
| 状态 | 表现 |
| --- | --- |
| 默认 | 空框 + `--text-hint` placeholder(`http://xxx.xxx.xxx.xxx:xxxx/upload/form` / `.../upload/json` / 端口示例) |
| 聚焦 | `2dp --color-primary` 描边,去掉底色 |
| 校验失败 | `--color-error` 描边 + 框下 13sp `--color-error` 行内提示(如「请填写完整的 http(s):// 地址」) |
| 自动上传关闭 | 三个地址/端口输入框整体 `opacity 0.38` 且不可编辑;**开关本体保持 1.0 且必须可交互**(沿用 `用户管理界面/DESIGN_SPEC.md` 的既有红线,否则用户无法重新开启) |
| 测试中 | 「测试数据上传」按钮 disabled + 文案保持不变,通过 Snackbar 反馈结果,不新增 UI 槽位 |
---
## 4. 全模块通用状态与边界
### 4.1 状态机
| 状态 | 通用表现 |
| --- | --- |
| 默认 | 见各屏规范 |
| 按下 / hover | 列表行 primary 8% / 4% 透明;按钮 `filter: brightness(0.96 / 0.92)` |
| 禁用 | **统一 `opacity: 0.38`**,禁止另造一套灰色值 |
| 加载 | 4dp 高线性进度条(`--color-primary`),或 24dp 圆形 `ProgressBar` |
| 空 | 公约 §5.7 三段式(仅 Logo 图片模式会遇到) |
| 错误 | `--color-error` 描边 + 13sp 行内提示;不用 Toast 顶替行内提示 |
### 4.2 截断规则
| 内容 | 规则 |
| --- | --- |
| AppBar 标题 | 单行 `ellipsize=end` |
| 语言名 | 不截断(内容极短,宽屏下永不溢出) |
| Logo 预览标题 | 单行 `ellipsize=end`(兜底;正常路径由 15 字符上限拦住) |
| 硬件 ID / 版本号 | **换行不截断**(`break-all`),完整 ID 必须可读可复制 |
| 上传地址 | 单行横向滚动(输入框原生行为),不换行 |
| 版型卡描述 | 最多 2 行,超出 `ellipsize=end`;840 容器下现有文案 1 行即可容纳 |
### 4.3 最小点击区域
- **全部可点元素 ≥ 48×48dp**。
- 语言行:整行 56dp 高 × 通栏可点。
- 单选圆点视觉 20dp,但外套 48dp 触控槽(`--touch-min`)。
- AppBar 返回箭头:图标 24dp,触控槽 48dp。
- 分段控件单段 36dp 高:**这是唯一低于 48dp 的例外**,M3 分段控件规范如此;靠段最小宽 132dp 保证横向易点。
### 4.4 数字排版
所有版本号、端口、ID、计数器统一 `font-variant-numeric: tabular-nums`(Android 侧对应等宽数字字体或 monospace),
避免刷新时数值宽度跳动。
---
## 5. 与全局公约的差异点声明(必读)
| # | 差异 | 公约原文 | 本模块取值 | 理由 |
| --- | --- | --- | --- | --- |
| 1 | 列表行高 | §5.5「选项行整行可点,行高 48px」 | **56dp** | 语言设置是整屏只有一个列表的设置页,48dp 在 1840px 高的平板上过于局促。48dp 仍作为**最小点击区**下限被满足 |
| 2 | 卡片描边 | §5.3「卡片 = surface 底 + corner-md + Level 1 投影」 | 版型卡在**选中态**额外加 `2dp --color-primary` 描边 | 单选卡必须有强选中信号;此时投影降为 Level 2 承担层级、描边承担状态,不构成 §4 红线所指的「深灰 1px 描边 + 重投影」双重包边 |
| 3 | 新增 Token | 公约未定义 | 新增 `--content-max-width: 840px`、`--content-gutter: 24px`、`--label-col-width: 140px` | 本模块沉淀的通用栅格规范,建议回写进公约 §2 供其余 7 个模块共用 |
| 4 | 页面根内边距 | §2「页面根内边距 24px」 | 语言设置页 **上下 0 / 左右由行内承担** | 通栏列表页若给根 padding,触摸涟漪会缩进一圈,宽屏下右半屏点不动。改为行内 padding + 通栏可点 |
---
## 6. 自查清单(对照公约 §8)
- [x] 每个信息字段都还在(含 layout 中存在但截图未拍到的 `升级来源` / `下载进度条` / `图片 Logo 模式`)
- [x] 页面结构与原截图一一对应,无区块搬家、无入口迁移
- [x] `baseline_ui.html` 中无散落十六进制,全部走 `var(--*)`
- [x] 圆角 / 间距全部引用 Token 变量
- [x] 字号只用了公约 §3 的层级(20 / 16 / 15 / 13 / 12)
- [x] 黑色胶囊开关(数据上传页)已替换为 M3 样式
- [x] 描边与投影无双重包边(差异点 #2 已单独声明)
- [x] 空态、禁用态、加载态、错误态均已定义
- [x] Token 映射字典见 `implementation_plan.md`