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

19 KiB
Raw Permalink Blame History

系统设置类页面(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)

  • 每个信息字段都还在(含 layout 中存在但截图未拍到的 升级来源 / 下载进度条 / 图片 Logo 模式)
  • 页面结构与原截图一一对应,无区块搬家、无入口迁移
  • baseline_ui.html 中无散落十六进制,全部走 var(--*)
  • 圆角 / 间距全部引用 Token 变量
  • 字号只用了公约 §3 的层级(20 / 16 / 15 / 13 / 12)
  • 黑色胶囊开关(数据上传页)已替换为 M3 样式
  • 描边与投影无双重包边(差异点 #2 已单独声明)
  • 空态、禁用态、加载态、错误态均已定义
  • Token 映射字典见 implementation_plan.md