148 lines
10 KiB
Markdown
148 lines
10 KiB
Markdown
# UI 改动记录（供后续 Agent 阅读）
|
||
|
||
本文档汇总 **像素 RPG UI 皮肤化** 相关实现与决策，便于新会话快速接手。更细的命名与规范见同目录上一级的 **`UI_CODING_STANDARD.md`**。
|
||
|
||
---
|
||
|
||
## 1. 相关文件一览
|
||
|
||
| 路径 | 作用 |
|
||
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||
| `UI_CODING_STANDARD.md` | 资源目录约定、9-slice 规则、图标语义、`Icons`/`UI` 命名解读、已知问题（含世界按钮切片） |
|
||
| `src/uiAssets.ts` | **唯一推荐** 的 UI 资源映射：`UI_CHROME`（9-slice 配置）、`TAB_ICONS`、`WORLD_SELECT_ICONS`、`getNineSliceStyle()` |
|
||
| `src/components/PixelIcon.tsx` | 小图标 `<img>`，`image-rendering: pixelated` |
|
||
| `src/index.css` | `.pixel-nine-slice`、`.pixel-root-shell` / `.pixel-app-shell`、tab/按钮布局类、`--ui-scale` |
|
||
| `src/App.tsx` | 世界选择、角色卡、底部 tab、剧情/背包面板、地图弹窗、`MudMapRoom` |
|
||
| `src/components/GameCanvas.tsx` | 场景名按钮（9-slice `Title_frame_m`） |
|
||
| `vite.config.ts` | `root` / `envDir` 指向 `__dirname`，保证 `.env.local` 从项目根加载 |
|
||
| `public/UI/`、`public/Icons/` | 静态资源（路径以 `/UI/...`、`/Icons/...` 引用） |
|
||
|
||
---
|
||
|
||
## 2. 架构要点
|
||
|
||
### 2.1 9-slice（禁止整图 `background-size: 100% 100%` 拉框体）
|
||
|
||
- 使用 CSS **`border-image`** + **`fill`**，通过自定义属性注入切片参数。
|
||
- 类名：**`pixel-nine-slice`**（定义在 `src/index.css`）。
|
||
- 行内样式由 **`getNineSliceStyle(texture, overrides?)`** 生成（`src/uiAssets.ts`），设置 `--frame-src`、`--slice-*`、`--frame-pad-*`、`--frame-repeat`、可选 `--frame-base`（一般仅在图源中心确实透明时使用）。
|
||
|
||
### 2.2 响应与缩放
|
||
|
||
- `:root` 上 **`--ui-scale`**：`clamp`（桌面）+ 小屏媒体查询内固定约 `0.8`。
|
||
- 边框宽度 = 切片像素 × `--ui-scale`，与 padding 同逻辑，避免移动端边框比例失控。
|
||
|
||
### 2.3 交互
|
||
|
||
- **`pixel-pressable`**：hover 用 `translateY` + `brightness`，**避免**对像素框体做 `scale()` 以免糊边。
|
||
|
||
### 2.4 全局背景
|
||
|
||
- **根布局**（`App.tsx` 最外层）：`pixel-root-shell` + `Background_fill.png` 平铺 + 深色半透明渐变（替代纯 `#050505` 死底）。
|
||
- **下半屏内容区** `pixel-app-shell`：同一纹理 + **更轻**的遮罩，让纹理更明显。
|
||
- 开局标题区已去掉单独 `bg-zinc-950`，与根背景一致。
|
||
|
||
---
|
||
|
||
## 3. `UI_CHROME` 当前用途（速查）
|
||
|
||
以下为 `src/uiAssets.ts` 中主要键与界面位置的对应关系（切片数值以文件内为准）：
|
||
|
||
| Key | 资源（示例） | 用途 |
|
||
| ----------------------------------------- | ------------------------------------- | ------------------------------------------ |
|
||
| `appBackground` | `Background_fill.png` | 根壳 + 下半屏平铺底 |
|
||
| `worldButtonWuxia` / `worldButtonXianxia` | `1_orange_button` / `1_violet_button` | 开局武侠/仙侠（**条高 28px**，切片见下文） |
|
||
| `characterCardFrame` | `pick_hero_frame` | 选角卡片 |
|
||
| `tabActive` / `tabInactive` | `Shop_tab_picked` / `Shop_tab` | 底部「角色 / 冒险 / 背包」 |
|
||
| `panel` | `Frame_bg_big_2` | 装备区等通用面板 |
|
||
| `storyPanel` | `Dialogue_frame` | 剧情正文区 |
|
||
| `inventoryPanel` | `Inventory_bg` | 背包条目 |
|
||
| `statsPanel` | `Stats_bar` | 角色数值面板 |
|
||
| `choiceButton` | `Options_bar` | 剧情选项按钮 |
|
||
| `modalPanel` | `Popup_window` | 地图弹窗外壳 |
|
||
| `infoPanel` | `Dialogue_frame` | 地图弹窗内「当前地点 / 可前往」信息块 |
|
||
| `sceneTitle` | `Title_frame_m` | 战斗画布顶部场景名按钮 |
|
||
| `mapRoomCell` | `Map_frame` | 地图节点卡片（`MudMapRoom`） |
|
||
| `mapDiagramPanel` | `Frame_bg_big_2` | 地图关系图整体衬底 |
|
||
|
||
图标路径：`TAB_ICONS`、`WORLD_SELECT_ICONS`、`CHROME_ICONS`；装备槽与背包分类见 `getEquipmentSlotIcon` / `getInventoryCategoryIcon`。
|
||
|
||
---
|
||
|
||
## 4. 已知坑（必读）
|
||
|
||
### 4.1 世界选择按钮「中间发空」
|
||
|
||
- 图源 **`1_orange_button.png` / `1_violet_button.png` 为 125×28**。
|
||
- 若 **`slice.top + slice.bottom >= 28`**，中间横带高度为 **0**，`border-image` 的 `fill` 异常，看起来像透明/没画上。
|
||
- **正确做法**：减小上下切片（当前为 **9+9**），并配合 `repeat: 'stretch'` 竖向拉伸条形成品。
|
||
- **不推荐**：用大色块 `baseColor` 糊底（与素材内渐变/内框不一致）。详见 `UI_CODING_STANDARD.md`「已知问题」。
|
||
|
||
### 4.2 新增 9-slice 前
|
||
|
||
先读 PNG **宽高**，保证 **`top+bottom < height`** 且 **`left+right < width`**。
|
||
|
||
---
|
||
|
||
## 5. 环境与运行（与 UI 无关但易踩坑）
|
||
|
||
- LLM：`VITE_LLM_*` 写在项目根 **`.env.local`**；因 `vite.config.ts` 固定 `envDir: __dirname`，从任意 cwd 启动也应能读到。
|
||
- 开发：`npm run dev`（默认端口见 `package.json`）。
|
||
|
||
---
|
||
|
||
## 6. 尚未统一成 UI 图、仍用 Tailwind 小块面的区域（可选后续）
|
||
|
||
若产品要求「全盘无纯色板」，可继续替换，当前仍可能为 `bg-black/20`、`rounded-lg border` 等：
|
||
|
||
- 角色页装备行、属性格子
|
||
- 地图弹窗顶栏分隔、关闭按钮外圈
|
||
- `GameCanvas` 内血条、名字条等 HUD
|
||
|
||
---
|
||
|
||
## 7. 修改清单摘要（按主题）
|
||
|
||
1. **资源规范**：`UI_CODING_STANDARD.md` + 集中映射 `uiAssets.ts`。
|
||
2. **9-slice 系统**：`index.css` + `getNineSliceStyle`。
|
||
3. **开局 / 主界面**：世界按钮、选角卡、tab、面板、选项、背包、根与内容区背景纹理。
|
||
4. **地图弹窗**：外壳、信息板、节点 `Map_frame`、关系图 `Frame_bg_big_2`。
|
||
5. **画布**：场景名 `Title_frame_m`。
|
||
6. **世界按钮**：按真实像素尺寸修正切片，去掉错误 `baseColor` 方案。
|
||
7. **Vite**：`root`/`envDir` 保证环境变量加载稳定。
|
||
|
||
---
|
||
|
||
## 8. 2026-04-18 / 2026-04-20 账号入口补充记录
|
||
|
||
- 早期方案曾在 `AuthGate` 层提供右上角全局账号信息条，并在 `GameShellRuntime` 中临时隐藏。
|
||
- 2026-04-20 起，这个全局悬浮入口已整体下线，不再区分“平台显示 / 冒险隐藏”。
|
||
- 原因是右上角高频观察区不适合承载账号入口，且平台内已经有更明确的页面内入口。
|
||
- 当前账号相关入口统一保留在平台首页受保护动作、个人页、存档页与账号弹窗，不再占用全局悬浮层。
|
||
|
||
---
|
||
|
||
## 9. 2026-04-20 等级 HUD / 冒险布局补充
|
||
|
||
- 当前运行中的等级 UI 已从 `AdventurePanel` 底部移出，改为放在 `GameShellRuntime` 左上角固定 HUD，避免把主对话区挤短。
|
||
- 左上角 HUD 复用 `CharacterInfoShared.tsx` 里的 `PlayerLevelProgress`，角色面板、实体详情、游戏 HUD 使用同一套等级进度表现。
|
||
- `AdventurePanel` 不再承担等级条展示，底部交互区只保留队伍 / 背包 / 刷新 / 退出聊天 / 选项 / 自定义输入，并压缩了底部留白与面板间距。
|
||
- 角色信息不只在总 HUD 里显示：`CharacterPanel` 的队伍成员卡、角色详情面板，以及 `AdventureEntityModal` 的实体详情头部都会展示角色身份与等级信息。
|
||
- 队长展示正式 `Lv.`；同行角色展示“参考 Lv.”；NPC 优先展示运行时 `levelProfile.level`，这样 UI 只负责表现，不在前端虚构额外成长逻辑。
|
||
- 左上角等级 HUD 不使用背景框体，仅保留 `Lv`、等级数字与极细经验线，避免遮挡场景背景与移动端视野。
|
||
|
||
---
|
||
|
||
## 10. 2026-04-20 平台亮色主题主 Tab 修正
|
||
|
||
- `PlatformHomeView.tsx` 的四个主 Tab（首页 / 创作 / 存档 / 我的）现在统一挂在 `platform-remap-surface` 下，让亮色主题能接管历史遗留的 `text-zinc-*`、`bg-black/*`、`border-white/*` 组合。
|
||
- 平台首页卡片覆层不要在组件里继续写死深色 `rgba(8,10,14,...)` 渐变；这次已收口为 `--platform-card-overlay-soft`、`--platform-card-overlay-strong`、`--platform-card-overlay-deep`，明暗主题都从 token 走。
|
||
- 平台桌面顶栏里的账号头像、移动端底部主 Tab 分隔线，也不要保留暗色主题时留下的固定蓝色渐变和深色边线，应直接使用平台主题变量（如 `--platform-profile-avatar-fill`、`--platform-line-soft`）。
|
||
- 后续如果继续调整平台主 Tab 视觉，优先改 `src/index.css` 的平台主题 token 和 remap 规则；只有 token 无法表达时，再做局部组件样式补丁，避免亮色主题再次出现“页面整体是亮的，但局部卡片仍是暗的”。
|
||
- 参考图方向已明确：平台亮色主题应以白色为主底色，粉红只承担背景气氛和重点 CTA，不应让整页主壳继续像深粉底板。
|
||
- 移动端底部 `platform-bottom-nav` 的 Tab 激活态必须与默认态使用同一套盒模型；边框要预占位，不能在 onPress / active 时临时增加边框导致按钮尺寸和留白跳变。
|
||
|
||
---
|
||
|
||
_文档目的：交接给下一个 Agent 时，优先读本文件 + `UI_CODING_STANDARD.md`，再改 `uiAssets.ts` / `App.tsx` / `index.css`。_
|