Genarrative/docs/MOBILE_UI_DEV_EXPERIENCE.md

奇幻酒馆 UI 开发经验沉淀

1. 总体原则

1.1 先保证移动端成立，再兼容网页端

• 入口页、世界选择、角色选择、冒险页、弹窗面板，都要先按手机竖屏去定义信息密度。
• 网页端只做“放宽容器、增加留白、补充 hover”，不要反过来让桌面布局压垮手机体验。
• 任何区域如果在移动端需要滚动，必须明确谁滚动，不能让整页和局部同时争夺滚动。

1.2 游戏 UI 要优先“状态清晰”，而不是“文案很多”

• 开始页应该像主菜单，不像产品介绍页。
• 角色选择页应该像角色选择器，不像角色说明书。
• 冒险页应该像战斗/剧情操作台，不像文档阅读器。

1.3 一屏内的层级顺序要稳定

• 上半部分：画面演出。
• 中间部分：剧情或核心信息。
• 底部：操作按钮。
• 玩家必须能快速判断“我在看什么、下一步点哪里”。

2. 入口页经验

2.1 开始页

• 极简化是对的。
• 当前实践证明：开始页只保留“开始游戏”和“开发团队”两个主按钮，体验明显更像游戏。
• 游戏名和英文副标题可以保留，但不要再加长段描述。

2.2 世界选择

• 纵向焦点轮播比普通列表更适合移动端。
• 当前居中的卡片应该最大、最清晰、最亮；上下卡片缩放和透明度随滚动连续变化。
• 世界确认动作应该绑定当前聚焦卡，而不是每张卡都塞太多按钮。

2.3 角色选择

• 横向轮播是正确方向。
• 中间卡片应承担“主视觉 + 主要信息”。
• 左右卡片只做预览，不需要承载完整信息。
• 左右卡片倾斜方向一定要符合透视直觉： 左侧卡片向左外倾，右侧卡片向右外倾。
• 中间卡片不要出现任何模糊，否则会破坏“当前选中”的确认感。

3. 角色选择页经验

3.1 聚焦卡的表现

• 中间聚焦卡用角色 run 动画是有效的，能明显提升“角色活着”的感觉。
• 但动画资源和静态立绘的锚点通常不一致，必须单独做位置与缩放修正。
• 结论： 动画版角色不要直接复用静态图样式，要单独给 transform、height、transform-origin。

3.2 信息区要紧凑

• 角色数值和角色背景应该放在轮播下方，但必须压缩高度。
• 如果下方面板过高，会直接破坏上半部分轮播体验，尤其在手机上。
• 删除背景面板里的额外动画模块是正确的，因为它与主轮播重复抢视觉焦点。

3.3 文案层级

• 页面标题只保留一句： “选择你扮演的角色”
• 不要再强调 CHARACTER SELECT 之类的开发向分类标签。
• 聚焦卡下方直接显示角色名，比把名字只放在卡片底部更直观。

3.4 按钮位置

• “确认选择”必须放在角色轮播和信息区之后，作为页面最后的主动作。
• 按钮不宜过宽过高，否则会抢轮播的视觉重心。

4. 冒险页经验

4.1 剧情区必须自适应

• 剧情文本区不应该写死高度。
• 正确做法是： 让它自动填满“上方画面下缘”和“底部按钮区上缘”之间的剩余空间。
• 这样才能同时保证：
  1. 上方画面一屏可见
  2. 下方三个选项一屏可见
  3. 中间剧情尽量大

4.2 底部操作区必须锚定到底

• 队伍、背包、换一换、选项列表，都应该属于底部控制区。
• 用户会天然在屏幕底部寻找交互入口，尤其是手机。
• 因此： 不要把这些按钮漂在中间，不要让剧情区把它们挤走。

4.3 队伍与背包不应打断主流程

• 在冒险页内，队伍和背包更适合“弹出面板”而不是“切换整页”。
• 原因：
  1. 不会打断当前剧情阅读
  2. 用户返回成本更低
  3. 操作像手游副面板，更符合预期

4.4 图标优于文字按钮

• 在底部工具区，队伍/背包改成 icon 后更紧凑。
• 但必须保留 aria-label，保证语义清晰、后续也方便测试。

5. 队伍面板经验

5.1 移动端成员列表不能太“卡片化”

• 如果每个成员都再套一层大边框卡片，手机上会显得很挤。
• 更好的方式是直接在主面板里陈列成员，弱化分隔、强化内容。

5.2 队伍列表展示什么

• 头像
• 姓名
• 称号
• 身份标记（领队/同行）
• HP / MP

5.3 队伍详情弹窗

• 弹窗必须可滚动。
• 弹窗宽度不宜太大，手机优先单列或偏单列。
• 技能、装备、属性三个区块保持稳定结构，便于扫读。

6. 背包页经验

6.1 格子数要优先适配手机

• 手机端格子间距要小一号。
• 图标尺寸和分类角标要跟着缩小。
• 目标不是“每个格子信息很多”，而是“单屏能看更多格子”。

6.2 背包详情弹窗

• 手机端改成单列/窄宽度布局更合理。
• 详情窗里的信息顺序建议固定：
  1. 名称与类别
  2. 品质与数量
  3. 大图标
  4. 说明
  5. 标签

7. 样式与动画经验

7.1 轮播动画要连续，不要离散

• 滚动时应根据“当前位置与当前卡片中心的距离”实时计算：
  • scale
  • opacity
  • rotate
  • translate
• 不要做成“翻页后才跳变”的效果。

7.2 焦点卡与非焦点卡的职责要不同

• 焦点卡负责可读性与确认感。
• 非焦点卡负责预告与空间深度。
• 所以焦点卡不该模糊，非焦点卡可以轻微降透明度、缩放、偏移。

7.3 资源锚点要单独校准

• 静态立绘和动画帧经常不是同一锚点。
• 只要切换成动画，就需要重新调：
  • 高度
  • Y 偏移
  • 缩放
  • transform-origin

8. 工程经验

8.1 组件要继续拆

• 本轮重构证明，把入口页、冒险页、队伍页、背包页拆成独立组件是正确的。
• 后续新增 UI 需求时，应优先落在：
  • GameShell.tsx
  • AdventurePanel.tsx
  • CharacterPanel.tsx
  • InventoryPanel.tsx

8.2 不要相信“服务已经在跑”

• 这轮出现过“端口上有进程，但浏览器仍然拿到旧模块”的问题。
• 实际经验：
  1. 要检查 src 文件内容
  2. 要检查 dev server 实际返回的模块内容
  3. 要确认启动脚本是否是当前项目真正使用的脚本

8.3 本项目当前开发服务入口

• 本地正确启动脚本是： node scripts/vite-cli.mjs --port=3000 --host=0.0.0.0
• 历史脚本或旧进程会导致“代码已改但 UI 看起来没变”的假象。

9. 后续建议

9.1 可以继续统一中英混杂文案

• 当前部分新旧文本仍有历史遗留字符问题。
• 如果后面继续做 UI 精修，建议单独做一轮文案清洗。

9.2 可以把轮播抽成通用组件

• 世界纵向焦点轮播
• 角色横向倾斜轮播
• 这两套逻辑已经足够稳定，适合后续抽成通用 hook 或通用组件。

9.3 可以补移动端安全区适配

• 当前已经偏移动端优先，但还可以继续加：
  • safe-area-inset-bottom
  • safe-area-inset-top
  • 更细的竖屏断点处理

10. 一句话结论

这一轮最关键的经验是： 游戏 UI 的移动端优化，本质不是把元素缩小，而是重组视觉重心、固定操作锚点、让焦点内容在一屏内自然成立。