系统设置类页面(5 屏)— 原生落地图纸 implementation_plan
- 依据:同目录
baseline_ui.html + DESIGN_SPEC.md,严格对齐 ../UI_DEV_GUIDE.md(Token 宪法)与 ../BEAUTIFY_BASELINE_20260816.md(全局公约)。
- 性质:本文件只做「原生落地图纸」,不改任何源码。所有路径均已在仓库
E:\Bitbucket\EAPManageTeam\app\src\main\ 下实际检索确认(Glob + Read),无编造路径。
- 执行方:
@coder。
1. CSS → Android Token 映射字典
1.1 颜色(baseline_ui.html :root → res/values/colors.xml 语义别名)
| HTML CSS 变量 |
取值 |
Android 语义 Token |
现状 |
--color-primary |
#3949AB |
?attr/colorPrimary(= @color/color_primary = @color/md_theme_primary) |
✅ 已存在,直接复用 |
--color-on-primary |
#FFFFFF |
?attr/colorOnPrimary |
✅ 已存在 |
--color-primary-container |
#E8EAF6 |
?attr/colorPrimaryContainer(= @color/color_primary_container) |
✅ 已存在 |
--color-on-primary-container |
#1A237E |
?attr/colorOnPrimaryContainer |
✅ 已存在 |
--color-secondary |
#00897B |
?attr/colorSecondary(= @color/color_secondary) |
✅ 已存在 |
--color-secondary-container |
#E0F2F1 |
?attr/colorSecondaryContainer |
⚠️ 需核对 colors.xml 中该 container 值是否为浅绿;若当前指向 M3 默认紫调,需在 values/colors.xml 补充/校正为浅绿,不要新建平行 Token |
--color-on-secondary |
#FFFFFF |
?attr/colorOnSecondary |
✅ 已存在 |
--color-surface |
#FFFBFE |
?attr/colorSurface(= @color/color_surface) |
✅ 已存在 |
--color-on-surface |
#1C1B1F |
?attr/colorOnSurface |
✅ 已存在 |
--color-surface-variant |
#E7E0EC |
?attr/colorSurfaceVariant(= @color/color_surface_variant) |
✅ 已存在 |
--color-on-surface-variant |
#49454F |
?attr/colorOnSurfaceVariant |
✅ 已存在 |
--color-background |
#F1F1F1 |
?attr/colorBackground / @color/color_background |
✅ 已存在 |
--color-error |
#B3261E |
?attr/colorError(= @color/color_error) |
✅ 已存在 |
--color-error-container |
#FCEDEA |
?attr/colorErrorContainer |
✅ 已存在(Widget.App.Button.Danger 已在用) |
--text-primary |
= on-surface |
@color/text_primary |
✅ 已存在 |
--text-secondary |
= on-surface-variant |
@color/text_secondary |
✅ 已存在 |
--text-disabled |
#9E9E9E |
@color/text_disabled |
✅ 已存在 |
--text-hint |
#BDBDBD |
@color/text_hint |
✅ 已存在 |
--divider |
rgba(0,0,0,.12) |
@color/divider(#1F000000) |
✅ 已存在 |
--outline |
rgba(0,0,0,.24) |
@color/outline(#99000000,公约标注"原 0.6 过重",本模块沿用公约值,不额外新增) |
✅ 已存在,语义值需与公约 §1 描述一致核对 |
1.2 尺寸 / 圆角(新增 Token,需在 res/values/dimens.xml 补充)
| HTML CSS 变量 |
取值 |
建议新增 Android Token |
说明 |
--content-max-width |
840px |
新增 @dimen/content_max_width = 840dp |
★ 本模块核心新增 Token,建议同步提给其余 7 个并行模块复用 |
--content-gutter |
24px |
复用现有 @dimen/spacing_lg(16dp)不匹配,需新增 @dimen/content_gutter = 24dp |
24dp 与 spacing_lg(16dp)/spacing_xl(24dp) 撞值;直接复用 @dimen/spacing_xl 即可,无需新增,见下方"精简建议" |
--label-col-width |
140px |
新增 @dimen/settings_form_label_width = 140dp |
数据上传页 / 版本信息页共用 |
--row-height |
56px |
复用现有 @dimen/toolbar_height(56dp)或新增 @dimen/settings_row_height = 56dp 语义更清晰 |
建议新增语义 Token,避免和 AppBar 高度混用同一个 dimen 名 |
--field-height |
56px |
Material TextInputLayout OutlinedBox 默认即约 56dp,无需新增 |
Widget.EAPManage.TextInputLayout 已定义圆角,高度走组件默认值 |
--corner-sm |
8px |
@dimen/corner_radius_sm(8dp) |
✅ 已存在 |
--corner-md |
12px |
@dimen/corner_radius_md(12dp)或已用的 @dimen/radius_lg(12dp,命名歧义,见 §4 风险) |
⚠️ 见下方风险项 |
--corner-lg |
20px |
@dimen/corner_radius_lg(20dp) |
✅ 已存在 |
--spacing-xs/sm/md/lg/xl |
4/8/16/24/32 |
@dimen/spacing_xs/sm/md/lg/xl |
✅ 已存在,直接复用 |
--touch-min |
48px |
@dimen/touch_target_min(48dp) |
✅ 已存在 |
精简建议:--content-gutter 直接映射到已有的 @dimen/spacing_xl(24dp),不新增同值 Token,避免 dimens.xml 进一步膨胀。
1.3 字号(res/values/dimens.xml 已有字号阶梯,按公约 §3 对齐)
| HTML CSS 变量 |
取值 |
Android Token |
现状 |
--font-title(AppBar 标题) |
20px |
@dimen/text_size_headline(20sp) |
✅ 已存在,但 activity_*.xml 里 Toolbar 标题目前吃 ?attr/textAppearance 默认值,未显式引用,需在 Widget.EAPManage.Toolbar 样式中显式指定 titleTextAppearance |
--font-subtitle(区块标题/卡片标题) |
16px |
@dimen/text_size_title(16sp) |
✅ 已存在 |
--font-body(正文) |
15px |
⚠️ dimens.xml 现有阶梯是 14/16/18(text_size_body=14sp),没有 15sp |
需新增 @dimen/text_size_body_15 = 15sp,或将本模块正文对齐到就近的 text_size_body(14sp)。建议:为保持与公约 §3 表格严格一致,新增 15sp Token,命名 text_size_body(与现有 14sp 的 text_size_body 冲突,需要 @coder 与全局 UI 组核实 14 vs 15 何者为准,本任务不擅自改现有 Token 语义) |
--font-caption(辅助说明) |
13px |
⚠️ 现有 text_size_caption = 11sp,不等于 13sp |
同上,建议新增或核实,@coder 落地前需与其他并行模块对齐,避免各模块各定义一套 13sp/11sp |
--font-unit |
12px |
@dimen/text_size_sm(12sp) |
✅ 已存在 |
⚠️ 风险提示(写入 §4):公约 §3 定义的字号阶梯(20/16/15/13)与仓库现有 dimens.xml 字号阶梯(20 headline / 16 title / 14 body / 11 caption)不完全对齐(15 vs 14,13 vs 11)。这是跨模块共性问题,不是本模块独有,建议 @coder 在实施前先与其他并行 UI 子任务对齐一次"字号 Token 最终基准表",避免 8 个模块分别新增 8 套相近字号。本模块 implementation_plan 暂按"复用最接近的现有 Token"处理,不新增字号 Token,待全局基准表拍板后再统一改。
1.4 Elevation
| HTML CSS 变量 |
Android 落地 |
--elev-1 |
app:cardElevation="@dimen/dimen_2dp"(现有 activity_version_info.xml 已用 2dp,视觉上接近 Level 1,沿用现状不改) |
--elev-2 |
app:cardElevation="@dimen/elevation_card" 或新增 card_elevation_selected = 4dp(仅版型选中卡使用) |
--elev-3 |
本模块无弹窗/BottomSheet,不涉及 |
1.5 组件样式复用
| HTML class |
Android 复用样式 |
.btn--confirm(浅绿确认按钮) |
Widget.EAPManage.Button.Tonal(已在 5 个 layout 中普遍使用,保持不变,但需核对其 backgroundTint/textColor 是否真的落在 colorSecondaryContainer/colorSecondary,若当前 Tonal 样式走的是默认 M3 紫色系,需按 DESIGN_SPEC §3 补充 tint 覆盖) |
.btn--secondary(次按钮) |
Widget.EAPManage.Button.Outlined |
.switch(M3 开关) |
com.google.android.material.materialswitch.MaterialSwitch(需替换 activity_data_upload.xml 中的 androidx.appcompat.widget.SwitchCompat,SwitchCompat 在部分主题下会渲染成黑色胶囊,正是公约 §5.5 点名的"旧版残留") |
.card(信息卡) |
com.google.android.material.card.MaterialCardView,去描边只留 cardElevation |
.textfield(输入框) |
Widget.EAPManage.TextInputLayout(已存在,8dp 圆角),聚焦态由 M3 组件默认处理,无需自定义 |
.badge(Debug/Release 徽章) |
新增极小号 TextView + res/drawable/shape_badge_error.xml / shape_badge_success.xml(背景色引用 ?attr/colorErrorContainer / ?attr/colorSecondaryContainer,圆角引用 @dimen/corner_radius_sm) |
.segmented(Logo 分段控件) |
MaterialButtonToggleGroup(activity_logo_management.xml 已在用,仅需补充 app:cornerRadius 走 999dp 胶囊 + 选中态样式覆盖为 colorPrimaryContainer,当前是 ?attr/materialButtonOutlinedStyle,选中态默认落 colorSecondary 系,需要单独定义 Widget.EAPManage.Button.Segmented 覆盖选中态 tint) |
2. 落地文件清单(已实际检索确认路径)
2.1 屏 1 — 语言设置
| 类型 |
路径 |
改动点 |
| Layout |
app/src/main/res/layout/activity_language_settings.xml |
9 个 row_language_settings_lang_* 行:android:layout_height="@dimen/toolbar_height" → 新增 @dimen/settings_row_height(56dp);分割线 View 的 android:background="?attr/colorSurfaceVariant" → 改为 ?attr/colorOutlineVariant(或直接映射 @color/divider)并加左右 margin 对齐 840dp 容器;给每个 row_* 增加选中态背景(android:background 换成 selector,见下方新增 drawable) |
| Activity |
app/src/main/java/com/umilab/eapmanage/team/ui/settings/subsettings/language/LanguageSettingsActivity.java |
补充选中行的背景/文字色切换逻辑(当前很可能只切 RadioButton.setChecked,需要联动整行 LinearLayout 的 isSelected 状态) |
| 工具类 |
app/src/main/java/com/umilab/eapmanage/team/util/LanguageUtils.java |
待 @coder 确认是否涉及選中态回填逻辑,本次不改业务逻辑,仅核对 |
| 新增 drawable |
app/src/main/res/drawable/selector_language_row_bg.xml(新建) |
state_selected → ?attr/colorPrimaryContainer;默认 → ?attr/selectableItemBackground |
2.2 屏 2 — 选择版型
| 类型 |
路径 |
改动点 |
| Layout |
app/src/main/res/layout/activity_edition_selection.xml |
两张 MaterialCardView(card_edition_selection_professional / card_edition_selection_custom)的 app:strokeColor 当前分别写死 ?attr/colorPrimary 和 ?attr/colorSecondary(与选中状态无关,是本次要修的核心 Bug)→ 改为动态 selector 或代码控制:未选中 ?attr/colorOutlineVariant 1dp,选中 ?attr/colorPrimary 2dp;两张卡的 RadioButton buttonTint 统一为 ?attr/colorPrimary(当前自定义卡是 colorSecondary,需统一) |
| Activity |
app/src/main/java/com/umilab/eapmanage/team/edition/EditionSelectionActivity.java |
onCheckedChangeListener 回调中补充:切换卡片的 strokeColor(professional/custom)、strokeWidth、卡片 backgroundTint(选中态 colorPrimaryContainer,未选中 colorSurface)随选中状态联动。当前逻辑只处理了 RadioButton 的 checked,未处理视觉态 |
| 关联类 |
app/src/main/java/com/umilab/eapmanage/team/edition/AppEdition.java、EditionManager.java |
数据枚举与持久化,不涉及本次视觉改动,仅供 @coder 理解上下文 |
2.3 屏 3 — 版本信息
| 类型 |
路径 |
改动点 |
| Layout |
app/src/main/res/layout/activity_version_info.xml |
三张 MaterialCardView 内的 LinearLayout(horizontal) 标签列 android:layout_width="@dimen/dimen_120dp" → 统一改为新增 Token @dimen/settings_form_label_width(140dp),三卡共用同一 dimen 保证列对齐;tv_version_info_build_type 的 android:textColor="?attr/colorError" 纯红字 → 改为徽章样式(背景 shape_badge_error.xml + padding),文字色不变;升级卡内按钮 btn_version_info_check_or_update 外层补一层 View 分割线 + 顶部 margin,做出"动作行"效果 |
| Activity |
app/src/main/java/com/umilab/eapmanage/team/ui/settings/subsettings/version/VersionInfoActivity.java |
补充按钮容器分割线的显隐逻辑(若沿用现有 XML 静态分割线则无需改代码) |
| ViewModel |
app/src/main/java/com/umilab/eapmanage/team/ui/settings/subsettings/version/VersionInfoViewModel.java |
不涉及视觉改动,仅核对状态字段(检查中/已最新/有更新/下载中/失败)是否已有对应 LiveData,供 Activity 侧驱动徽章与进度条显隐 |
| 新增 drawable |
app/src/main/res/drawable/shape_badge_error.xml、shape_badge_success.xml(新建) |
徽章背景,圆角 @dimen/corner_radius_sm |
2.4 屏 4 — Logo 授权管理
| 类型 |
路径 |
改动点 |
| Layout |
app/src/main/res/layout/activity_logo_management.xml |
tg_logo_mode(MaterialButtonToggleGroup)内两个 MaterialButton 当前 style="?attr/materialButtonOutlinedStyle" → 新增 Widget.EAPManage.Button.Segmented 样式(胶囊圆角 + 选中态 colorPrimaryContainer/colorOnPrimaryContainer);文本/图片模式内的预览卡 MaterialCardView(app:cardCornerRadius="@dimen/radius_md")内部 LinearLayout 的 android:background="?attr/colorSurfaceVariant" → 改为 ?attr/colorSurface + 卡片本身补 app:strokeColor="?attr/colorOutlineVariant" app:strokeWidth="@dimen/dimen_1dp";til_custom_text 的 app:counterEnabled 计数器默认样式已由 M3 TextInputLayout 承担(位置在框下方),基本符合 DESIGN_SPEC 要求,核实实际渲染位置是否与截图一致,若组件默认渲染已经在下方则此项标记"确认无需改" |
| Activity |
app/src/main/java/com/umilab/eapmanage/team/ui/settings/subsettings/logo/LogoManagementActivity.java |
分段切换时补充卡片描边/底色的联动(若靠 selector 自动处理则无需改代码) |
| ViewModel |
app/src/main/java/com/umilab/eapmanage/team/ui/settings/subsettings/logo/LogoManagementViewModel.java |
不涉及视觉改动 |
| Repository |
app/src/main/java/com/umilab/eapmanage/team/data/repository/LogoRepository.java |
不涉及视觉改动,仅上下文参考 |
| 工具类 |
app/src/main/java/com/umilab/eapmanage/team/util/LogoPickerHelper.java |
不涉及视觉改动 |
| 复用 Layout |
app/src/main/res/layout/layout_empty_state.xml |
图片 Logo 空态直接复用该已有空态布局(tv_logo_management_logo_empty 已 include 了它),核对其内部图标/文案样式是否符合公约 §5.7 三段式,不符合则按 §5.7 微调该公共文件(注意:此文件可能被其他模块共用,改动前需确认无副作用,@coder 谨慎处理) |
2.5 屏 5 — 数据上传
| 类型 |
路径 |
改动点 |
| Layout |
app/src/main/res/layout/activity_data_upload.xml |
核心修复:内层 androidx.constraintlayout.widget.ConstraintLayout 改写为 LinearLayout(vertical),四行(自动上传开关 / 表单地址 / 原始数据地址 / 端口)改写为四个横向 LinearLayout(gravity=center_vertical),每行左侧标签 TextView(width=@dimen/settings_form_label_width) + 右侧输入控件 weight=1;删除现有互相错位的 layout_constraintTop_toBottomOf/Bottom_toBottomOf 链;三个 TextInputLayout 上残留的无效 android:layout_weight="1"(ConstraintLayout 中不生效)一并清理;androidx.appcompat.widget.SwitchCompat(sw_upload_auto)→ 替换为 com.google.android.material.materialswitch.MaterialSwitch |
| Activity |
app/src/main/java/com/umilab/eapmanage/team/ui/settings/subsettings/upload/DataUploadActivity.java |
因 id 全部保留(et_upload_form_url/et_upload_json_url/et_upload_port/sw_upload_auto/btn_user_save/btn_data_upload_reset/btn_data_upload_test),View Binding 引用不受结构调整影响,理论上无需改代码;仅需核对"自动上传关闭 → 三输入框 alpha 0.38 且禁用"的联动是否已实现,若未实现需按 DESIGN_SPEC §3.5 状态机补充 |
2.6 全局资源文件
| 类型 |
路径 |
改动点 |
| dimens |
app/src/main/res/values/dimens.xml |
新增:content_max_width(840dp)、settings_form_label_width(140dp)、settings_row_height(56dp)。不新增与 spacing_xl 同值的 gutter Token(直接复用) |
| colors |
app/src/main/res/values/colors.xml |
核对 color_secondary_container 实际取值是否为浅绿(#E0F2F1 系),如已是 M3 默认紫需要新增/校正 |
| styles |
app/src/main/res/values/themes.xml |
新增 Widget.EAPManage.Button.Segmented(Logo 分段控件选中态样式);Widget.EAPManage.Toolbar 补充 titleTextAppearance 显式引用 @dimen/text_size_headline |
| 响应式限定符 |
app/src/main/res/values-w600dp/(已存在但为空目录)、app/src/main/res/layout-w600dp/(已存在但为空目录) |
★ 840dp 容器规范落地的推荐路径:在 values-w600dp/dimens.xml 中覆写内容 padding 相关 Token 为宽屏取值,或在 layout-w600dp/ 下为 5 个 activity 提供宽屏专用布局变体(外层多一层 840dp 居中容器)。待 @coder 决策采用"运行时用代码设置 maxWidth"还是"资源限定符切两套布局",两种方案在 5 个 layout 中一致处理 |
3. 关键实现难点与建议方案
3.1 840dp 居中容器的两种落地方式
| 方案 |
做法 |
优劣 |
| A. 资源限定符 |
layout-w600dp/activity_xxx.xml 中给内容区套一层 maxWidth=840dp 的容器 |
与项目已有空 layout-w600dp/ 目录意图吻合;但 5 个文件要维护两份,维护成本高 |
B. 自定义 MaxWidthLinearLayout/MaxWidthConstraintLayout |
写一个继承 LinearLayout 的容器 View,onMeasure 里钳制最大宽度后居中 |
只需在默认 layout 里换一个自定义 ViewGroup 标签,无需维护双份布局,跨模块可复用 |
建议:采用方案 B,新增 com.umilab.eapmanage.team.ui.widget.MaxWidthFrameLayout(或类似命名),5 屏统一用它包裹内容区。此类不在本次检索范围内确认是否已存在,待 @coder 确认:检索关键字 MaxWidth、CenteredContainer。若已存在同类容器则直接复用,避免重复造轮子。
3.2 语言设置"通栏可点 + 视觉居中"的矛盾
若采用方案 B 的 MaxWidth 容器包裹每一行,涟漪效果会被限制在 840dp 内,宽屏下点击行两侧空白区域无反馈,与 DESIGN_SPEC §1.4 的要求(列表本体通栏、内容居中)冲突。
建议:row_language_settings_lang_* 的 LinearLayout 本身保持 match_parent 承载点击与涟漪,内部再套一层 840dp 居中的 LinearLayout 只包文字和 RadioButton。即"外层可点通栏,内层视觉居中",与 baseline_ui.html 中 .lang-row / .lang-row-inner 的双层结构完全对应。
3.3 版型卡描边颜色的动态切换
MaterialCardView 的 app:strokeColor 不支持直接写 selector(部分 M3 版本支持 ColorStateList,需验证当前依赖的 Material Components 版本)。若不支持,只能在 EditionSelectionActivity.java 的 onCheckedChangeListener 回调中用代码 card.setStrokeColor(...)、card.setStrokeWidth(...)、card.setCardBackgroundColor(...) 显式设置,这是必须改代码的一项,不能只靠 XML。
4. 风险与待确认项(禁止编造,如下均需 @coder 或 UI 组二次确认)
- 字号 Token 冲突(§1.3):公约 §3 的 15sp 正文 / 13sp 辅助说明,与仓库现有
dimens.xml 的 14sp/11sp 不一致,需与其他并行 UI 子任务对齐后再定新 Token,避免重复定义。
radius_lg 命名歧义:dimens.xml 中同时存在 radius_lg(12dp,用于版型卡圆角) 与语义应为 20dp 的公约 corner_radius_lg(实际也已存在,20dp),两者数值不同但命名相似,容易在 XML 中引用错。@coder 落地时需明确:版型卡沿用现有 radius_lg(12dp,对应公约的 corner-md),不要误用 20dp 的 corner_radius_lg。
color_secondary_container 实际取值:未在本次检索中读取 colors.xml 完整内容确认该值是否已是浅绿,需 @coder 核实(检索关键字:color_secondary_container)。
MaxWidthXxxLayout 自定义容器是否已存在:检索关键字 MaxWidth、CenteredContainer、widget包下的自定义 ViewGroup,本次未做穷尽检索。
- Material Components 版本对
strokeColor ColorStateList 的支持情况:需 @coder 查看 app/build.gradle 中 com.google.android.material:material 版本号后确认,本次未检索 build.gradle。
values-w600dp/ / layout-w600dp/ 现为空目录:是否有其他并行模块已计划使用这两个目录,需要与其他 7 个子任务协调,避免资源限定符策略打架。