Echo/Assets/_Project/Docs/SpecialUseUI_Technical_Reference.md

物品使用特殊弹窗 UI 技术参考（左键 Use + DOTween 弹出）

本文档描述“物品左键使用后弹出特殊 UI（Image 从下往上弹出 + 文本展示）”的落地实现、UI 搭建与场景绑定方式。

1. 总览

目标：

• 玩家按下左键（Input Action：Use）使用当前选中背包格子物品
• 若该物品在 ItemData 中勾选了 Show Special Use UI，则弹出一个 UI 面板（可翻页）
  • 面板主体是一个 Image，使用 DOTween 从屏幕下方弹出到指定位置
  • Image 下挂一个 TMP_Text（或任意 TMP_Text 子节点）用于展示文字
• 面板提供：
  • 关闭按钮（手动关闭）
  • 上一页/下一页按钮（由配置决定是否出现）
  • 通过 UIPanelStack 兼容 ESC 关闭（不额外监听 ESC）
• 打开阅读时锁定玩家常规输入并解锁鼠标（通过 PlayerControlLockService）
• 文字与图片内容由 ItemData 配置决定
  • 单页：specialUseUIText → description → displayName
  • 多页：specialUseUIPages[*].text
  • 图片：specialUseSprite → icon

涉及脚本：

• 物品数据：ItemData.cs
• 使用入口：ItemUsageSystem.cs
• UI 控制器：SpecialUsePopupController.cs

2. 调用链（Use → 弹窗）

1. 输入系统触发 Use（默认绑定鼠标左键）
2. ItemUsageSystem.OnUsePerformed 取 InventorySystem.selectedSlotIndex 的物品
3. ItemUsageSystem.UseItem 根据 ItemType 处理使用逻辑
4. 若 ItemData.showSpecialUseUI == true：调用 SpecialUsePopupController.ShowPages(pages, sprite, startIndex)

注：

• ItemType.Resource 默认不可使用；但如果勾选了 showSpecialUseUI，则允许“只弹 UI 不消耗”。
• ItemType.Tool 当前不做默认逻辑，但同样支持弹 UI（方便做“说明/提示型工具”）。

3. ItemData 配置字段（Special Use UI）

字段位置：ItemData.cs

• showSpecialUseUI
  • 勾选后：该物品在左键 Use 时会弹出特殊 UI
• useSpecialUseUIPages
  • 勾选后：使用 specialUseUIPages 作为分页内容来源
• specialUseUIPages
  • 每一页的文字内容（不会做“文字超长自动分页”）
  • 当 useSpecialUseUIPages=true 且列表非空时，会忽略 specialUseUIText 的单页文本
• specialUseUIText
  • 弹窗文字内容
  • 为空时 fallback：description → displayName
• specialUseSprite
  • 弹窗图片（用于替换 UI Image 的 sprite）
  • 为空时 fallback：icon

4. UI 结构（推荐）

建议场景中放一个专用 Canvas（也可挂在已有 HUD Canvas 下）：

• SpecialUseCanvas（Canvas）
  • SpecialUseRoot（RectTransform，可空，用于收纳）
    • PopupImage（Image + RectTransform）
      • PopupText（TextMeshPro - Text）
      • CloseButton（Reach Button / ButtonManager）
      • PrevPageButton（Reach Button / ButtonManager）
      • NextPageButton（Reach Button / ButtonManager）
    • SpecialUsePopupController（脚本，建议挂在 SpecialUseRoot 或 PopupImage 的父级）

要求：

• PopupImage 必须是一个 RectTransform，用于动画 DOAnchorPosY
• 文本必须是 TMP_Text（TextMeshProUGUI），脚本会自动查找子节点里的第一个 TMP_Text

5. 场景绑定步骤（最少依赖）

5.1 绑定 UI 控制器

1. 将 SpecialUsePopupController 挂到 SpecialUseRoot（或任意该 Canvas 下的父节点）
2. 在 Inspector 里绑定：
   • Popup Image Rect：拖入 PopupImage 的 RectTransform
   • Popup Image：拖入 PopupImage 的 Image（可不填，脚本会尝试自动找）
   • Popup Text：拖入 PopupText（可不填，脚本会尝试自动找）
   • Close Button：拖入 CloseButton
   • Previous Page Button：拖入 PrevPageButton
   • Next Page Button：拖入 NextPageButton
3. 调整参数：
   • Hidden Y：面板完全藏到屏幕外时的 Y（通常是负数）
   • Shown Y：面板弹出后停留的 Y
   • Tween Duration / Tween Ease
   • Lock Player Control：打开阅读时是否锁玩家输入并解锁鼠标（推荐开启）
   • Use Panel Stack Escape Close：是否入 UIPanelStack 以支持 ESC 关闭（推荐开启）

5.2 绑定物品数据

对需要弹窗的物品 ItemData：

1. 勾选 Show Special Use UI
2. 配置分页方式（二选一）：
   • 单页：填写 Special Use UI Text（或直接使用 Description 作为 fallback）
   • 多页：勾选 Use Special Use UI Pages，并在 Special Use UI Pages 列表里逐页填写 Text
3. （可选）填写 Special Use Sprite

5.3 使用验证

1. 确保玩家身上有 ItemUsageSystem 且 PlayerInput 的 ActionMap 能触发 Use
2. 在背包 UI 里选中该物品所在格子（影响 InventorySystem.selectedSlotIndex）
3. 鼠标左键（Use）应弹出 UI

6. 常见问题

• “按左键没反应”
  • 检查玩家 PlayerInput 的 Use action 是否存在且绑定到左键
  • 检查 ItemUsageSystem 是否启用、以及当前 ActionMap 是否为 Player
• “弹窗控制器找不到 / Instance 为空”
  • 确保场景里存在 SpecialUsePopupController
  • 如果该对象初始是 Inactive，Awake 不会执行，Instance 不会建立（建议控制器对象保持 Active，让脚本自己在 Awake 里隐藏）
• “按 ESC 没法关闭”
  • 确保场景里存在 UIPanelStack 与 UIPanelStackInput（工程通常由 SettingsBootstrap 自动创建）
  • 确保控制器勾选了 Use Panel Stack Escape Close
• “图片弹出但文字不显示”
  • 确保使用的是 TextMeshPro（TMP_Text），并且 PopupText 在 PopupImage 的子层级中