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

21 KiB
Raw Permalink Blame History

系统设置类页面(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 组二次确认)

  1. 字号 Token 冲突(§1.3):公约 §3 的 15sp 正文 / 13sp 辅助说明,与仓库现有 dimens.xml 的 14sp/11sp 不一致,需与其他并行 UI 子任务对齐后再定新 Token,避免重复定义。
  2. radius_lg 命名歧义:dimens.xml 中同时存在 radius_lg(12dp,用于版型卡圆角) 与语义应为 20dp 的公约 corner_radius_lg(实际也已存在,20dp),两者数值不同但命名相似,容易在 XML 中引用错。@coder 落地时需明确:版型卡沿用现有 radius_lg(12dp,对应公约的 corner-md),不要误用 20dp 的 corner_radius_lg。
  3. color_secondary_container 实际取值:未在本次检索中读取 colors.xml 完整内容确认该值是否已是浅绿,需 @coder 核实(检索关键字:color_secondary_container)。
  4. MaxWidthXxxLayout 自定义容器是否已存在:检索关键字 MaxWidth、CenteredContainer、widget包下的自定义 ViewGroup,本次未做穷尽检索。
  5. Material Components 版本对 strokeColor ColorStateList 的支持情况:需 @coder 查看 app/build.gradle 中 com.google.android.material:material 版本号后确认,本次未检索 build.gradle。
  6. values-w600dp/ / layout-w600dp/ 现为空目录:是否有其他并行模块已计划使用这两个目录,需要与其他 7 个子任务协调,避免资源限定符策略打架。