5.7 KiB
5.7 KiB
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. 修改清单摘要（按主题）
- 资源规范：
UI_CODING_STANDARD.md+ 集中映射uiAssets.ts。 - 9-slice 系统：
index.css+getNineSliceStyle。 - 开局 / 主界面：世界按钮、选角卡、tab、面板、选项、背包、根与内容区背景纹理。
- 地图弹窗：外壳、信息板、节点
Map_frame、关系图Frame_bg_big_2。 - 画布：场景名
Title_frame_m。 - 世界按钮：按真实像素尺寸修正切片，去掉错误
baseColor方案。 - Vite：
root/envDir保证环境变量加载稳定。
文档目的：交接给下一个 Agent 时，优先读本文件 + UI_CODING_STANDARD.md，再改 uiAssets.ts / App.tsx / index.css。