mirror of
https://github.com/Shu-Ying/noname-shuying.git
synced 2026-10-06 08:30:02 +08:00
99 lines
5.8 KiB
Markdown
99 lines
5.8 KiB
Markdown
# 梦三手牌 UI 子扩展
|
||
|
||
## 模块边界
|
||
|
||
这是术樱包内部的必需子模块，由梦三战斗加载，不是另一个可安装扩展。
|
||
没有单独关闭开关。JS 或样式加载失败时进入既有战斗异常处理流程，
|
||
保留存档并提供返回模式选择入口；不会静默略过必需模块。
|
||
|
||
| 位置 | 职责 |
|
||
| --- | --- |
|
||
| `ui/hand/index.js` | 挂载、同步、局部输入适配、回退和幂等卸载 |
|
||
| `ui/hand/adapter.js` | 校验引擎容器并读取真实卡牌，识别第二容器离线结构 |
|
||
| `ui/hand/overlays.js` | 费用与强化覆盖层，仅维护当前手牌的显示节点 |
|
||
| `ui/hand/style.css` | 独立排列、尺寸、间距、选中标记及隔离样式 |
|
||
| `ui/hand/diagnostics.js` | 生命周期、回退和加载失败诊断日志 |
|
||
| `tools/test-hand-ui.cjs` | 浏览器隔离验证，非发布资源 |
|
||
| `verification/hand-ui/` | 本地验证报告、截图和清单，非发布资源 |
|
||
| `logs/log.txt` | 游戏内生成的最近 100 条诊断，非发布资源 |
|
||
|
||
`cards/personal-piles.js` 只负责个人牌堆业务，原先的手牌 DOM 显示逻辑
|
||
已移入本模块。旧的 `ui/hand-upgrade.js` 和通用样式文件中的对应规则
|
||
已移除，避免两套覆盖层并行维护。发布入口仍为 `register.js`。
|
||
|
||
## 交互方案与证据
|
||
|
||
本体 `noname/ui/click/index.js` 的 `card()` 使用真实 `this` 操作
|
||
`ui.selected.cards` 并调用 `game.check()`。本体 `card.updateTransform()`
|
||
检查卡牌祖先是否为 `ui.me`。十周年 `core/layout.js`、`cardDragSort.js`
|
||
也依赖真实节点的父容器和变换。因此首期选用真实节点原位复用，
|
||
不复制卡面，不移动手牌容器，不替换全局原型或布局函数。
|
||
|
||
排列使用独立命名空间的 flex 样式；默认卡牌 90×110、间距 8，
|
||
小屏卡牌 80×100，牌多时横向滚动。具体尺寸集中在本模块 CSS。
|
||
卡面继续采用当前引擎/主题生成的内容。选择、取消、出牌、响应和
|
||
选目标继续交给引擎，模块不另行计算卡牌可用性或提交出牌事件。
|
||
|
||
引擎仍维护节点上的 `selected`、`selectable` 等状态。本模块通过这些
|
||
原有类显示选择状态，保留 DOM 顺序作为引擎排序的依据。
|
||
检测到移动手势时临时退回既有排列，释放或取消后恢复独立排列；
|
||
触屏水平滚动保留独立排列。首期没有另做手动拖动排序系统。
|
||
|
||
费用调用既有 `cardCost`，强化读取既有 `cardUpgradeLevel`。
|
||
覆盖层只在自己的子节点 dataset 上保存显示值，使用伪元素显示文字，
|
||
避免十周年对出牌子节点 innerText 的扫描误识别费用数字。
|
||
覆盖层不接收指针事件；离开手牌区即回收，返回手牌区重新生成。
|
||
若业务直接修改卡牌 storage，修改者应调用返回控制器的 `refresh()`。
|
||
|
||
十周年 `uiCreateMe()` 的第二手牌容器默认离线。
|
||
适配器允许“主容器连接、第二容器离线且为空”的结构。
|
||
未知或被替换的容器退回原排列，保留覆盖层，并通过游戏日志和
|
||
诊断文件报告，不依赖 `decadeUI` 的内部坐标接口。
|
||
|
||
## 生命周期与日志
|
||
|
||
`mode.js` 在玩家初始化后、开局摸牌前等待 `mountHandUI()`。
|
||
模块资源登记到 battle-session，逆序释放早于个人牌堆和玩家资源。
|
||
正常战斗结束和流程异常另有显式卸载入口；DOM 根节点被移除时
|
||
观察器会触发卸载。加载中取消会结束等待并取消计时器。
|
||
卸载移除覆盖层、观察器、局部监听、样式链接、自己的类名，并恢复
|
||
自己改过的属性；多次调用安全。它不销毁真实卡牌或重置选择状态。
|
||
|
||
支持引擎文件接口时，日志写入安装目录下
|
||
`extension/术樱包/mengsan/logs/log.txt`，包含时间、战斗 session ID、
|
||
挂载、回退、卸载与加载错误。最近 100 条覆盖写入，串行提交。
|
||
没有文件接口时保留控制台日志；布局回退也写入游戏日志。
|
||
|
||
## 验证结果及边界
|
||
|
||
本次参考安装源码：本体 `game/update.js` 为 1.11.5.2；
|
||
十周年 `info.json` 为 1.3.1。
|
||
十周年 `STYLE_TO_SKIN` 将 off/on/othersOff 映射到
|
||
shousha/shizhounian/xinsha，配置菜单显示名与规划文档略有不同。
|
||
|
||
浏览器验证加载安装目录中的本体 CSS、十周年实际基础样式组合及
|
||
手杀/十周年/新杀的按钮和技能样式，以匹配 `uiCreateMe()` 的 DOM 结构
|
||
构造测试场景；点击测试使用安装源码中的真实 `ui.click.card` 函数体，
|
||
其 `game.check` 等引擎服务为测试替身，不代表完整游戏事件链验证。
|
||
|
||
| 场景 | 桌面 1280×720 | 小屏 540×360 | 完整游戏实测 |
|
||
| --- | --- | --- | --- |
|
||
| 原生 UI | 隔离验证通过 | 隔离验证通过 | 待验证 |
|
||
| 手杀 off/shousha | 隔离验证通过 | 隔离验证通过 | 待验证 |
|
||
| 十周年 on/shizhounian | 隔离验证通过 | 隔离验证通过 | 待验证 |
|
||
| 新杀 othersOff/xinsha | 隔离验证通过 | 隔离验证通过 | 待验证 |
|
||
|
||
已验证真实节点父级及点击身份、选择/取消、费用与强化移除、
|
||
手牌离开/返回、横向滚动处理、手势布局退让、会话结束、重复卸载、
|
||
根节点移除、加载中取消、CSS 加载失败、回退覆盖层及属性恢复。
|
||
已有梦三逻辑回归 44 项通过。发布清单包含本模块全部 JS/CSS，
|
||
不包含 tools、verification、.planning 和 log.txt。
|
||
|
||
尚需真实游戏验证出牌/响应、技能虚拟牌、选目标/取消、引擎自动排序、
|
||
十周年拖拽排序插件及真实手机触屏。本次没有改动已安装的游戏文件，
|
||
也没有把隔离场景结果标记为游戏内实测通过。
|
||
|
||
运行浏览器测试：`node mengsan/tools/test-hand-ui.cjs`。
|
||
可用 NONAME_APP 指向本体目录、CODEX_NODE_MODULES 指向提供 Playwright
|
||
的依赖目录；脚本使用本机 Chrome 的无界面独立实例。
|