236 lines
14 KiB
Markdown
236 lines
14 KiB
Markdown
# Interaction Pattern Library（交互 pattern 库）
|
||
|
||
> **Status**: Complete（核心 8 成文 + 12 目录占位）
|
||
> **Author**: user + ux-designer
|
||
> **Last Updated**: 2026-09-15（雾格残留清理：pattern 4 / 10 同步格态两态与提示枚举，见文末修订记录）
|
||
> **Template**: Interaction Pattern Library
|
||
> **来源**: `design/ux/battle.md`（2026-09-12 /ux-review APPROVED）已拍板内容的成文固化——本库不引入新设计决策
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
- **用途**：ui-programmer 实现时引用既有 pattern，不重复发明；实现中出现新 pattern 时**必须回写本库**（team-ui Phase 3 义务）
|
||
- **输入约束**：PC / Keyboard-Mouse 主（全部操作纯鼠标可完成）、Gamepad Partial 非 MVP、Touch None
|
||
- **视觉依据**：art-bible §3.3（半拟物：容器穿戏服、数据素面；直角=逻辑信息、圆角=可触摸物件）、§4（彩为世，墨为信——逻辑信息一律近黑暖墨族）
|
||
- **全局语义红线**：无任何信息仅靠色相承载（art-bible §4.5 色弱安全清单逐对成立）；明度恒定（§2 硬规则——状态区分只用色相/饱和/运动/元素）
|
||
|
||
---
|
||
|
||
## Pattern Catalog
|
||
|
||
| # | Pattern | 类别 | 状态 |
|
||
|---|---|---|---|
|
||
| 1 | 双源拒绝反馈 | Feedback | **成文 ✓** |
|
||
| 2 | 原位窗口激活 | Overlay | **成文 ✓** |
|
||
| 3 | 逐行兑现明细带 | Data Display | **成文 ✓** |
|
||
| 4 | 悬停预承诺光标 | Input | **成文 ✓** |
|
||
| 5 | 点阵资源显示 | Data Display | **成文 ✓** |
|
||
| 6 | 模态 overlay 层级纪律 | Modal | **成文 ✓** |
|
||
| 7 | 破坏性确认异位 | Feedback | **成文 ✓** |
|
||
| 8 | 禁用态即理由 | Feedback | **成文 ✓** |
|
||
| 9 | 常驻意图徽标 | Data Display | **已实现**（enemy_card_view.gd——规格全文待补） |
|
||
| 10 | 一次性非模态教学提示 | Feedback | **已实现**（chord 提示——规格全文待补） |
|
||
| 11 | tooltip 规范 | Feedback | **已实现**（状态/道具悬停——规格全文待补） |
|
||
| 12 | 单意图帧批次提交 | Input | **已实现**（main.gd 组合根——规格全文待补） |
|
||
| 13 | 状态效果槽 | Data Display | **已实现**（status_slot_row.gd——规格全文待补） |
|
||
| 14 | 步进进度条 | Navigation | **已实现**（level_strip_view.gd——规格全文待补） |
|
||
| 15 | 移动路径预览 | Input | **已实现**（board_view.gd BFS 蓝点——规格全文待补） |
|
||
| 16 | 清图/换图演出编排 | Feedback | **已实现·占位级**（board_fx_view.gd 金粒彩纸——规格随战斗表现 美术批补） |
|
||
| 17 | 胜利/失败终局编排 | Feedback | **已实现·占位级**（battle_end_overlay.gd——规格随战斗表现补） |
|
||
| 18 | Boss 遭遇演出 | Feedback | **已实现·占位级**（紫赤影子——规格随战斗表现补） |
|
||
| 19 | 库存常读列表 | Data Display | **已实现**（inventory_panel_view.gd——规格全文待补） |
|
||
| 20 | 标准控件组（button/progress bar/list） | Control | **已实现**（ui_kit.gd 直角细线/凸圆角——规格全文待补） |
|
||
|
||
MVP 未使用标准控件（不入库）：toggle / dropdown / input field / tab bar——战斗屏无此需求；TunePanel slider 为调试专用。
|
||
|
||
---
|
||
|
||
## Patterns（核心 8）
|
||
|
||
### 1. 双源拒绝反馈（dual-source rejection feedback）
|
||
|
||
**Category**: Feedback
|
||
**Used In**: 战斗屏（棋盘/资源全部意图动作）
|
||
|
||
**Description**: 玩家意图被核心拒绝时，反馈必须同时做到：(a) 每次拒绝玩家可感知（防静默拒绝读感欺骗）；(b) 来源可区分——棋盘面（排雷玩法判，携 sub_reason 封闭枚举）/资源面（行动经济判，客户端推断）/相位（排雷玩法 ActionOutcome）三源各异；(c) 图标+文案双通道，非色相独载。
|
||
|
||
**Specification**:
|
||
- 触发：`ActionOutcome{accepted=false, reject_reason, sub_reason}` **返回值驱动**（拒绝无事件外发——排雷玩法发射面封闭，实现层不得等待拒绝信号）
|
||
- 反馈映射：board_face → 目标格旗朱 `#C63D22` 边框闪 + toast 具体原因（sub_reason→文案映射表：not_adjacent/target_revealed/target_concealed/flag_present/flag_absent/no_path/out_of_catalog）；resource_face → 对应资源数字脉冲（AP/RAP）+「AP 不足 · 剩 0 点」式文案；phase → toast（结算中/非挖掘期）
|
||
- 即时性：拒绝当帧呈现；toast 自动消退 2.5s
|
||
- **voided 区分**：作废 ≠ 拒绝（零效果零扣费零事件）——须独立文案如「本轮已清图，停手未执行 · 剩余 AP 已作废」，至少 stop 作废可感知
|
||
- Accessibility：旗朱边框闪为形状+运动通道；文案常驻
|
||
|
||
**When to Use**: 任何意图提交被拒绝时（唯一拒绝呈现通道）
|
||
**When NOT to Use**: 成功反馈（走动作本身的直接视觉反馈通道）；voided 语义场景（作废文案独立）
|
||
|
||
**Reference**: battle.md §States 拒绝/作废子态、§Interaction Map；排雷玩法×6⑥、行动经济双源契约
|
||
|
||
---
|
||
|
||
### 2. 原位窗口激活（in-place window activation）
|
||
|
||
**Category**: Overlay
|
||
**Used In**: 轮末道具使用窗口
|
||
|
||
**Description**: 窗口态切换不弹中央模态——既有面板**原位**点亮为窗口态（描边金光 + 标题切换），输入竞争区压暗锁输入。库存常读位置 = 窗口位置，空间记忆连续、不遮挡结算演出首屏。
|
||
|
||
**Specification**:
|
||
- 触发：战斗结算编排窗口锚点（授予段完成后、增益/减益段前）
|
||
- 行为：E 区面板描边金光点亮、标题切换「⏳ 轮末道具窗口 · 至多选 1 件」+ 时机指示常驻；D 区棋盘**去饱和 + 金橙色相偏移**锁输入（明度不变——art-bible §2）
|
||
- 退出：选用 1 件 / 跳过按钮 → 关闭回结算流；空库存不弹窗直接跳过
|
||
- 选中即承诺（照常消耗）；窗口选择序列 = 结算回放输入事件
|
||
- Accessibility：状态区分以饱和/色相表达，非明度；窗口内禁选项用 pattern 8
|
||
|
||
**When to Use**: 窗口内容与常读面板同域（空间记忆连续优先）、输入竞争区明确无需遮断全屏时
|
||
**When NOT to Use**: 全屏打断级信息（胜利/失败终局、图例回看——用 pattern 6 模态 overlay）
|
||
|
||
**Reference**: battle.md 布局决策 2、§States 道具窗口态
|
||
|
||
---
|
||
|
||
### 3. 逐行兑现明细带（line-by-line settlement feed）
|
||
|
||
**Category**: Data Display
|
||
**Used In**: 战斗画面区底部（结算期第一注视点）
|
||
|
||
**Description**: 轮末结算逐行流水实时呈现 + 可回看——「扫雷之因逐行兑现为战果」（P2 归因）的承载面。挖掘期收起为 1 行上轮摘要；结算期展开 84px 实时流；点击开完整回看 overlay。
|
||
|
||
**Specification**:
|
||
- 数据源：[战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（15 类行封闭协议；公共字段 `type/source_class/origin_cell/round_index/display_name/value/highlight?`）；**无来源行 = 断言失败**
|
||
- 行模板：「{行为} {值} → {目标}（来源）」——来源标注（第 N 轮 · 安全格式）；行文案最长 token = 道具名（4 汉字），模板预留 40% 膨胀宽度
|
||
- 聚合纪律：未生效类行（奖励未生效/已消耗未生效/使用被拒）按聚合计数呈现（防逐行惩罚轰炸）；衰减行聚合计数；效果行 value=单次贡献值、禁与 pool_value（池合成值）相加呈现；零值行可见不吞（免伤轮归因不断点）
|
||
- 高亮：highlight 字段 {flag_hit, clear_reward_h2, perfect_broken} → 金框强调；完美排雷 = 独立高光行 + 全屏喝彩级反馈
|
||
- 布局：固定槽高 + clip_contents；正文 ≥14px；数值暗底高对比；未生效类行带 icon/划线形状冗余
|
||
- 击杀标记呈现（H3 数据源 = 战斗结算流水击杀结果字段）
|
||
|
||
**When to Use**: 任何「因果可归因」的逐行流水呈现
|
||
**When NOT to Use**: 自造行类型/字段（15 类封闭枚举——增删 = 接口漂移，须走[《战斗结算》](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)修订）
|
||
|
||
**Reference**: battle.md §Component Inventory 结算明细带、§AC 信息与归因；归档《战斗结算》（b1-settlement.md）Core Rule 14 / Visual Req
|
||
|
||
---
|
||
|
||
### 4. 悬停预承诺光标（hover pre-commitment cursor）
|
||
|
||
**Category**: Input
|
||
**Used In**: 扫雷图 BoardView
|
||
|
||
**Description**: 左键双义（已开格=移动 / 未开相邻格=挖）的消歧完全依赖格态一瞥可辨 + 悬停光标区分——**误挖不可逆**（1 AP + 可能触雷）的感知保险。
|
||
|
||
**Specification**:
|
||
- 光标三态：移动（箭头）/挖（镐）/旗（旗形）——按悬停格态与键位自动切换
|
||
- 目标格边框高亮常驻
|
||
- 可挖域常驻指示：小人 8 向相邻未开格呼吸微光（挖掘期唯一在动元素——art-bible §2.1）
|
||
- 非相邻格：禁止光标 + 首次 toast「需先走近（点击已开格移动，免费）」
|
||
- 提交：悬停仅预承诺，**点击才提交意图**（单意图帧批次——目录 #12）
|
||
- chord 首遇提示：怀旧玩家双击快开尝试时一次性 toast（含排雷玩法登记锚点「点数字格可移动小人」）
|
||
|
||
**When to Use**: 一键多义且后果不对称的操作面
|
||
**When NOT to Use**: 单义控件（直接点击反馈即可，勿加光标层）
|
||
|
||
**Reference**: battle.md §Interaction Map；排雷玩法×6②③
|
||
|
||
---
|
||
|
||
### 5. 点阵资源显示（dot-matrix resource display）
|
||
|
||
**Category**: Data Display
|
||
**Used In**: AP 条、RAP 框
|
||
|
||
**Description**: 离散点阵 + 数字双承载的资源显示——点阵为图形载体（本地化零成本、一眼可读余量），数字为精确值。
|
||
|
||
**Specification**:
|
||
- 形态：`●●●●●○○○` + 「5/8」；直角细线数据框（信息=直线直角，art-bible §3.3）
|
||
- 更新触发：组合根每次调用返回后重查（**行动经济无推送信号**——实现层不得等待资源变更事件）
|
||
- 拒绝反馈：资源不足时数字脉冲（pattern 1 的 resource_face 腿）
|
||
- Accessibility：点阵=形状通道、数字=文本通道；对比 ≥4.5:1
|
||
|
||
**When to Use**: 小整数离散资源（≤16 量级）
|
||
**When NOT to Use**: 大数值/连续量（用直角细线进度条——目录 #20）
|
||
|
||
**Reference**: battle.md §Layout C/D 区；行动经济 UI Requirements
|
||
|
||
---
|
||
|
||
### 6. 模态 overlay 层级纪律（modal overlay discipline）
|
||
|
||
**Category**: Modal
|
||
**Used In**: 图例面板、结算明细回看、胜利/失败终局 overlay
|
||
|
||
**Description**: 任何模态覆盖层打开时必须**隐藏/锁定其遮挡的交互物**，关闭恢复——防「看不见但可点」的幽灵输入（垂直切片缺陷⑤教训，场景级断言强制）。
|
||
|
||
**Specification**:
|
||
- 打开：遮挡物隐藏或禁用 + 输入锁定；单一模态栈（无叠模态）
|
||
- 关闭：恢复被遮挡物；关闭按钮/再点入口切换
|
||
- 内容：固定槽高 + clip_contents（缺陷①——悬停文案换行不得推挤布局）
|
||
- 验收：**场景级断言「打开时遮挡物隐藏/输入锁定」为每个模态 overlay 的强制 AC**（battle.md 场景级测试节）
|
||
|
||
**When to Use**: 全屏打断级信息、只读回看、仪式性终局
|
||
**When NOT to Use**: 与常读面板同域的窗口态（用 pattern 2 原位激活）
|
||
|
||
**Reference**: battle.md §AC 场景级测试；缺陷①⑤（production/session-state entry 17）
|
||
|
||
---
|
||
|
||
### 7. 破坏性确认异位（destructive-confirm position offset）
|
||
|
||
**Category**: Feedback
|
||
**Used In**: 弃图刷新（RAP−8 消耗 + 旧板弃置）
|
||
|
||
**Description**: 消耗性/不可逆操作的确认交互与常规确认**不同位**——位置通道是色盲安全冗余（art-bible §4.5 清单 #7：UI 红/金强调对需图标+文案冗余，且破坏性确认不得与常规确认同位）。
|
||
|
||
**Specification**:
|
||
- 弃图刷新：确认微交互显式呈现全部代价（RAP−8 · **旧板旗随旧板作废**提示）；确认交互位置与常规确认不同位
|
||
- 双通道：图标 + 文案冗余
|
||
- 拒绝路径：RAP<8 → pattern 1 resource_face（EC13 合法拒绝可见）
|
||
|
||
**When to Use**: 任何消耗资源/不可逆的操作确认
|
||
**When NOT to Use**: 无代价操作（直接执行 + 直接反馈）
|
||
|
||
**Reference**: battle.md §Accessibility、§AC 交互与反馈；art-bible §4.5 #7
|
||
|
||
---
|
||
|
||
### 8. 禁用态即理由（disabled-state with reason）
|
||
|
||
**Category**: Feedback
|
||
**Used In**: 道具窗口 usable_now=false 件（满血治疗包）
|
||
|
||
**Description**: 禁用不许静默——灰置必须伴随**可见的禁选原因**（tooltip/toast），防「为什么点不动」的困惑。
|
||
|
||
**Specification**:
|
||
- 形态：灰置 + tooltip「HP 已满 · 禁选」；点击无效 + 原因 toast 兜底
|
||
- 语义区分：满血 = 零收益守卫（禁选、不烧包）≠ 缺血不足（超量 clamp 部分回复，**不**禁选）
|
||
- usable_now 由战斗结算组装进窗口载荷（地图战斗资源零跨系统读）——呈现层只消费不推断
|
||
|
||
**When to Use**: 任何可见但不可交互的元素
|
||
**When NOT to Use**: 完全隐藏的不可用功能（不存在的东西无需解释）
|
||
|
||
**Reference**: battle.md §States 道具窗口态、§Interaction Map；地图战斗资源 Rule 7 / AC-14
|
||
|
||
---
|
||
|
||
## Gaps & Patterns Needed
|
||
|
||
- **目录 #9–#20 已全部实现**（2026-09-12 战斗屏实现批，冒烟 149/149 + 三探针全绿）；规格全文回写 = HUD框架正式化批义务
|
||
- 实现期新增技术件（不单独立 pattern，规格归并）：去饱和+金橙状态切换 = 逐格共享 ShaderMaterial（明度不变，gl_compatibility 安全）；敌人死亡残位 = 卡体灰化+碎裂禁瞬消（归入 #17 终局编排规格）
|
||
- **MVP 未使用标准控件**：toggle / dropdown / input field / tab bar（无需求不设占位）；TunePanel slider 为调试专用不入库
|
||
- **实现偏差规则**：pattern 近似但不完全适配时，实现层不得静默变体——登记偏差交 ux-designer 复核后回写
|
||
|
||
---
|
||
|
||
## Open Questions
|
||
|
||
1. 目录占位项的补全时点 = 实现期随批回写（owner：ui-programmer → ux-designer 复核）
|
||
2. Gamepad 批次引入时，需为 pattern 4/12/15 增补手柄映射节（焦点序已在 battle.md OQ8 留位）
|
||
|
||
---
|
||
|
||
## 修订记录
|
||
|
||
| 日期 | 改动 |
|
||
|---|---|
|
||
| 2026-09-15 | 雾格残留清理：pattern 1 无改；pattern 4 的悬停预承诺消歧依据改按格态两态表述；目录 #10 一次性非模态提示的已实现说明去掉雾首遇、只留 chord 提示。pattern 库不引入新决策 |
|