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

174 lines
21 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 屏)— 原生落地图纸 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 个子任务协调,避免资源限定符策略打架。