接入 Hud 输入提示并完善 InputModule 提示映射

2026-06-16 17:09:20 +08:00
parent e5630f0896
commit 21d0b410b6
13 changed files with 397 additions and 33 deletions
@@ -589,7 +589,7 @@ GameEntry.InputModule.RegisterListener(InputActionId.Confirm, _ =>

 - `InputPrompt`（Base 层 readonly struct）：承载提示数据
  - `TextLabel`：文本标签（如 `”A”`, `”Enter”`, `”E”`）
-  - `SpriteName`：可选的 sprite 资源键（项目自定义，模块不管理 sprite 资源）
+  - `SpriteName`：可选的 sprite 资源键（项目自定义，模块不管理 sprite 资源）；多个 sprite 可用 `|` 分隔，如 `keyboard_w|keyboard_a|keyboard_s|keyboard_d`
  - `HasSprite` / `IsValid`：便捷检查属性
 - `IInputPromptMap`（Base 层接口）：项目可自定义实现
  - `TryGetPrompt(InputActionId, InputDeviceKind, out InputPrompt)`：查找提示
@@ -623,6 +623,21 @@ map.TryGetPrompt(InputActionId.Confirm, InputDeviceKind.Gamepad, out InputPrompt
 GameEntry.InputModule.PromptMap = new MyPlayStationPromptMap();
 ```

+**TMP 文本工具：**
+
+`Assets/Plugins/InputModule/Presentation/InputPromptTextUtility.cs` 提供了将 `InputPrompt` 转成 TMP 文本的工具：
+
+```csharp
+if (GameEntry.InputModule.TryGetPrompt(InputActionId.Move, out InputPrompt prompt))
+{
+    _movePromptText.text = InputPromptTextUtility.BuildTmpText(prompt);
+}
+```
+
+- `BuildTmpText(InputPrompt)`：输出 `"<sprite name=\"keyboard_w\"> <sprite name=\"keyboard_a\"> ... 移动"` 这类可直接给 `TMP_Text.text` 的字符串
+- `BuildSpriteTags(string)`：只把 `SpriteName` 转成 TMP sprite tag
+- `SpriteName` 使用 `|` 分隔时会输出多个 sprite tag；单个 sprite 仍按原方式输出
+
 **自定义 PromptMap 示例：**

 ```csharp
@@ -651,30 +666,70 @@ public sealed class PlayStationPromptMap : IInputPromptMap

 **触发器：** `DeviceKindChanged` 事件。无需单独的 `PromptsChanged` 事件。

-**消费模式：**
+**推荐接入现有 UI 架构：**
+
+当前项目 UI 采用 `Controller -> Context -> Form`，输入提示也应沿用这条数据流：
+
+- Controller：监听 `GameEntry.InputModule.DeviceKindChanged`，查询 `TryGetPrompt()`，用 `InputPromptTextUtility.BuildTmpText()` 生成 TMP 文本
+- Context：保存当前 UI 需要展示的提示字符串，如 `MovePrompt`、`ConfirmPrompt`、`CancelPrompt`
+- Form：只负责展示，不直接判断设备类型，也不直接查询 InputModule
+
+**Hud 示例：**

 ```csharp
-private Action<InputDeviceKind> _onDeviceChanged;
-
-private void OnEnable()
+public class HudContext : UIContext
 {
-    _onDeviceChanged = _ => RefreshPrompts();
-    GameEntry.InputModule.DeviceKindChanged += _onDeviceChanged;
-    RefreshPrompts(); // 初始状态
+    public string MovePrompt { get; set; }
+}
+```
+
+```csharp
+private static HudContext BuildHudContext()
+{
+    return new HudContext
+    {
+        MovePrompt = BuildPromptText(InputActionId.Move)
+    };
 }

-private void OnDisable()
+private static string BuildPromptText(InputActionId actionId)
 {
-    GameEntry.InputModule.DeviceKindChanged -= _onDeviceChanged;
-    _onDeviceChanged = null;
+    if (GameEntry.InputModule == null || !GameEntry.InputModule.TryGetPrompt(actionId, out InputPrompt prompt))
+    {
+        return null;
+    }
+
+    return InputPromptTextUtility.BuildTmpText(prompt);
 }

-private void RefreshPrompts()
+protected override void SubscribeCustomEvents()
 {
-    if (GameEntry.InputModule.TryGetPrompt(InputActionId.Interact, out InputPrompt p))
-        _interactLabel.text = p.TextLabel;
-    if (GameEntry.InputModule.TryGetPrompt(InputActionId.Cancel, out InputPrompt c))
-        _cancelLabel.text = c.TextLabel;
+    GameEntry.InputModule.DeviceKindChanged += OnDeviceKindChanged;
+}
+
+protected override void UnsubscribeCustomEvents()
+{
+    GameEntry.InputModule.DeviceKindChanged -= OnDeviceKindChanged;
+}
+
+private void OnDeviceKindChanged(InputDeviceKind deviceKind)
+{
+    if (Context == null || Form == null)
+    {
+        return;
+    }
+
+    Context.MovePrompt = BuildPromptText(InputActionId.Move);
+    Form.RefreshMovePrompt(Context.MovePrompt);
+}
+```
+
+```csharp
+public void RefreshMovePrompt(string prompt)
+{
+    bool visible = !string.IsNullOrEmpty(prompt);
+    _movePromptRoot.SetActive(visible);
+    _movePromptText.text = prompt;
 }
 ```

@@ -792,17 +847,16 @@ private void RefreshPrompts()
 ```csharp
 if (GameEntry.InputModule.TryGetPrompt(InputActionId.Interact, out InputPrompt prompt))
 {
-    // 文本标签
-    _label.text = prompt.TextLabel;
-
-    // 图标（通过 TMP Sprite Tag）
-    if (prompt.HasSprite)
-    {
-        _iconText.text = $"<sprite=\"InputPrompt\" name={prompt.SpriteName}>";
-    }
+    _label.text = InputPromptTextUtility.BuildTmpText(prompt);
 }
 ```

+如果只想显示图标，可以使用：
+
+```csharp
+_iconText.text = InputPromptTextUtility.BuildSpriteTags(prompt.SpriteName);
+```
+
 **说明：**

 - 此步骤完全可选；不设置 Default Sprite Asset 不影响任何核心功能