ColorMapRun H5 Card 风格重制与迁移实验总结 (Style Remake & Migration Experiment)

本文档总结了将原有的 sdk/index.html 和 sdk/detail.html 迁移至 sdk/test/ 目录，并在保持原有业务逻辑不变的前提下，重新设计为 “运动竞技风 (Sporty Tech)” 的全过程。这份文档可作为未来类似 UI 重构或风格迁移任务的操作流程模板。

1. 实验目标

核心任务: 在不改变任何 JS 逻辑功能（API 调用、交互流程）的前提下，完全重写 UI 样式。
目标风格: 运动竞技风 (Sporty Tech) —— 暗色背景、荧光配色、斜切几何图形、动感排版。
输出产物: sdk/test/ 目录下的完整可运行代码。

2. 操作流程 (SOP)

2.1 环境准备 (Preparation)

创建独立工作区:
- 新建目录 sdk/test/，避免污染主线代码。
- 新建子目录 sdk/test/css/ 和 sdk/test/js/。
复制核心依赖:
- 确保所有 JS 逻辑库和 CSS 库都已就位。
- 关键动作: 复制 api.js, bridge.js, mock_flutter.js 到 sdk/test/。
- 关键动作: 复制 js/multiavatar.min.js 到 sdk/test/js/。
- 关键动作: 复制 css/all.min.css 到 sdk/test/css/。
- 易错点: 务必复制 webfonts/ 目录！FontAwesome 图标依赖于此，否则图标会显示为空白。

2.2 逻辑迁移 (Migration)

读取原文件: 读取原始 index.html 和 detail.html 的完整代码。
提取 JS 逻辑: 将 <script> 标签内的所有业务逻辑（包括 Logger 封装、API 调用、数据处理、事件监听）完整提取出来。
保持引用: 确保新文件头部引用的 JS/CSS 路径 (./bridge.js, ./api.js 等) 与新目录结构一致。

2.3 样式重写 (Re-design)

定义主题变量 (:root):
- 设立新的色彩系统（如 --sport-bg, --sport-accent）。
- 统一字体栈。
重构 HTML 结构:
- 根据新设计调整 DOM 结构（例如将 Dashboard 的进度条从线性改为网格状）。
- 原则: 尽量复用原有的 ID (id="dashBadge", id="rankList")，这样原有的 JS 逻辑可以直接操作 DOM，无需修改 JS。
编写 CSS:
- 应用新的视觉风格（斜切 transform: skewX, 动态背景, 荧光边框）。
- 适配移动端: 注意 env(safe-area-inset-top) 和 bottom 的适配。

2.4 调试与微调 (Refinement)

图标与字体检查: 确认 FontAwesome 图标是否正常显示（检查 webfonts 路径）。
布局适配:
- 卡片圆角: 对于透明背景的卡片，使用 clip-path: inset(0 round 16px) 往往比 border-radius 更可靠，尤其是在 WebView 环境下。
- 全屏适配: 确保详情页 (detail.html) 占满全屏，使用 height: 100%; overflow: hidden; 固定框架，内部列表使用 flex: 1; overflow-y: auto; 滚动。
- 状态栏避让: 顶部导航栏增加 padding-top: max(30px, env(safe-area-inset-top)) 防止遮挡。
文本本地化: 检查是否有硬编码的英文占位符，将其替换回中文（如 "Loading..." -> "加载中..."）。

3. 关键注意事项 (Best Practices)

3.1 逻辑与视图分离

ID 锚点: 在重写 HTML 时，必须保留原有 JS 逻辑所依赖的 id 和 class（如果 JS 通过 class 选择）。例如 rankList 容器、myRankNum 文本节点等。
JS 零修改: 理想情况下，直接复制粘贴原有的 <script> 块即可运行。如果必须改 JS，说明 HTML 结构变动过大，需谨慎评估。

3.2 WebView 兼容性

背景透明: 在做圆角卡片时，html 和 body 必须设为 background-color: transparent !important;。
圆角裁剪: 推荐使用 clip-path 强制裁剪，以防止子元素（如绝对定位的背景图）溢出圆角。
滚动穿透: 全屏页面务必锁定 body 滚动，只允许特定容器内部滚动。

3.3 WebView 兼容性与透明圆角 (重点更新)

H5 透明度极限: H5 页面本身无法直接控制 WebView 宿主控件的背景色透明度。
圆角裁剪区域的颜色: 如果 html 和 body 都已设置为 background-color: transparent !important;，但圆角裁剪掉的部分仍显示颜色（如灰色），则该颜色来自WebView 控件自身的默认背景色。
原生透明度配置: 要实现真正的透明圆角，必须在 Native App (如 Flutter) 端配置 WebView 控件的背景色为透明（例如 Flutter 的 WebView(backgroundColor: Colors.transparent)）。
H5 替代方案: 如果无法修改 Native App 配置，H5 端可以通过将 html 或 body 的背景色强制设置为与 App 背景色一致的颜色（如白色），来视觉上“模拟”透明效果，以达到无缝融合。

3.4 资源完整性

FontAwesome: 仅仅复制 CSS 文件是不够的，必须同步复制 webfonts 字体文件目录，且保持相对路径一致。

4. 沟通模板 (用于后续任务)

如果您希望继续进行类似的风格重制任务，可以使用以下模板指令：

“请在 [目标目录] 下创建一个基于 [原文件] 的新版本。风格要求：[描述风格，如：赛博朋克/极简/复古]。核心要求：保持所有 JS 业务逻辑不变，仅重写 HTML/CSS。注意事项：

确保所有依赖文件（JS/CSS/Fonts）都已正确复制。

保持原有的 DOM ID 以兼容 JS。

适配移动端安全区域和圆角效果。”

Generated by Gemini based on "Sporty Edition" experiment.

STYLE_MIGRATION_GUIDE.md 5.6 KB Permalink Histórico Raw