493 lines
15 KiB
Markdown
493 lines
15 KiB
Markdown
# 25 · 输入重映射 UI
|
||
|
||
> **命名空间** `BaseGames.Input`
|
||
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)
|
||
> **依赖** `BaseGames.Input`（InputReaderSO）· `BaseGames.UI` · Unity Input System
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [系统总览](#1-系统总览)
|
||
2. [重映射架构](#2-重映射架构)
|
||
3. [RebindPanel — UI 面板](#3-rebindpanel--ui-面板)
|
||
4. [RebindActionRow — 单行绑定控件](#4-rebindactionrow--单行绑定控件)
|
||
5. [冲突检测](#5-冲突检测)
|
||
6. [按键名称显示（Key-to-String）](#6-按键名称显示key-to-string)
|
||
7. [持久化存储](#7-持久化存储)
|
||
8. [设备切换后自动刷新](#8-设备切换后自动刷新)
|
||
9. [完整实现示例](#9-完整实现示例)
|
||
10. [编辑器友好设计](#10-编辑器友好设计)
|
||
|
||
---
|
||
|
||
## 1. 系统总览
|
||
|
||
```
|
||
输入重映射职责:
|
||
├─ RebindPanel → 重映射面板（SettingsPanel 的子页签）
|
||
├─ RebindActionRow → 单条 Action 的绑定显示 + 重映射按钮
|
||
├─ ConflictDetector → 检测新绑定与现有绑定是否冲突
|
||
├─ KeyDisplayNameResolver → 将 InputControl.path 转换为可读字符串
|
||
└─ RebindPersistence → 将覆盖数据保存至 PlayerPrefs（JSON 格式）
|
||
```
|
||
|
||
**设计原则**：重映射仅修改 `InputActionAsset` 的运行时 Override，不改动资产本身；游戏启动时从 `PlayerPrefs` 读取并重新应用 Override。
|
||
|
||
---
|
||
|
||
## 2. 重映射架构
|
||
|
||
### 数据流
|
||
|
||
```
|
||
玩家点击 [重新绑定] 按钮
|
||
│
|
||
▼
|
||
InputActionRebindingExtensions
|
||
.PerformInteractiveRebinding(action, bindingIndex)
|
||
│
|
||
▼
|
||
等待玩家按键（屏蔽菜单键/退出键）
|
||
│
|
||
├─ 冲突检测 → 若冲突：弹出警告，允许覆盖或取消
|
||
│
|
||
▼
|
||
应用 Override
|
||
InputBinding.overridePath = newPath
|
||
│
|
||
▼
|
||
持久化：SaveOverrides()
|
||
│
|
||
▼
|
||
UI 刷新：所有 RebindActionRow 更新显示
|
||
```
|
||
|
||
### 核心 Unity API
|
||
|
||
| API | 用途 |
|
||
|-----|------|
|
||
| `action.PerformInteractiveRebinding(index)` | 启动交互式重映射 |
|
||
| `action.ApplyBindingOverride(index, path)` | 直接应用 Override |
|
||
| `action.RemoveBindingOverride(index)` | 移除某条 Override（恢复默认）|
|
||
| `asset.RemoveAllBindingOverrides()` | 全部恢复默认 |
|
||
| `asset.SaveBindingOverridesAsJson()` | 序列化所有 Override 为 JSON |
|
||
| `asset.LoadBindingOverridesFromJson(json)` | 从 JSON 恢复 Override |
|
||
|
||
---
|
||
|
||
## 3. RebindPanel — UI 面板
|
||
|
||
### 面板结构（UXML）
|
||
|
||
```
|
||
<ui:VisualElement name="RebindPanel" class="panel">
|
||
<ui:Label text="键位设置" class="panel-title"/>
|
||
<ui:ScrollView name="ActionList">
|
||
<!-- RebindActionRow × N（运行时动态填充）-->
|
||
</ui:ScrollView>
|
||
<ui:VisualElement name="ButtonRow">
|
||
<ui:Button name="ResetAllButton" text="恢复默认"/>
|
||
<ui:Button name="CloseButton" text="关闭"/>
|
||
</ui:VisualElement>
|
||
<!-- 重映射遮罩（监听按键时显示）-->
|
||
<ui:VisualElement name="ListeningOverlay" style="display:none">
|
||
<ui:Label name="ListeningLabel" text="请按下新按键..."/>
|
||
<ui:Button name="CancelRebindButton" text="取消"/>
|
||
</ui:VisualElement>
|
||
</ui:VisualElement>
|
||
```
|
||
|
||
### RebindPanel.cs
|
||
|
||
```csharp
|
||
namespace BaseGames.Input
|
||
{
|
||
public class RebindPanel : MonoBehaviour
|
||
{
|
||
[SerializeField] InputReaderSO _inputReader;
|
||
[SerializeField] VisualTreeAsset _rowTemplate; // RebindActionRow.uxml
|
||
|
||
UIDocument _doc;
|
||
VisualElement _listeningOverlay;
|
||
Label _listeningLabel;
|
||
|
||
// 需要在面板中显示的 Action 名单（顺序即显示顺序）
|
||
static readonly string[] ShownActions =
|
||
{
|
||
"Move", "Jump", "Attack", "Parry", "Dash", "Heal", "Interact", "Pause"
|
||
};
|
||
|
||
void Awake()
|
||
{
|
||
_doc = GetComponent<UIDocument>();
|
||
}
|
||
|
||
void OnEnable()
|
||
{
|
||
var root = _doc.rootVisualElement;
|
||
_listeningOverlay = root.Q("ListeningOverlay");
|
||
_listeningLabel = root.Q<Label>("ListeningLabel");
|
||
|
||
root.Q<Button>("ResetAllButton").clicked += OnResetAll;
|
||
root.Q<Button>("CancelRebindButton").clicked += OnCancelRebind;
|
||
|
||
BuildRows(root.Q("ActionList"));
|
||
}
|
||
|
||
void BuildRows(VisualElement list)
|
||
{
|
||
list.Clear();
|
||
var asset = _inputReader.GetInputActionAsset();
|
||
foreach (string actionName in ShownActions)
|
||
{
|
||
var action = asset.FindAction(actionName);
|
||
if (action == null) continue;
|
||
// 为每个 Binding（键盘 + 手柄）各建一行
|
||
for (int i = 0; i < action.bindings.Count; i++)
|
||
{
|
||
if (action.bindings[i].isComposite) continue;
|
||
var row = new RebindActionRow(action, i, _rowTemplate);
|
||
row.OnRebindRequested += StartRebind;
|
||
list.Add(row.Root);
|
||
}
|
||
}
|
||
}
|
||
|
||
InputActionRebindingExtensions.RebindingOperation _currentOp;
|
||
|
||
void StartRebind(InputAction action, int bindingIndex)
|
||
{
|
||
_listeningOverlay.style.display = DisplayStyle.Flex;
|
||
_listeningLabel.text = $"正在重映射：{action.name} 按下新按键 / Esc 取消";
|
||
|
||
_inputReader.DisableAllInput();
|
||
|
||
_currentOp = action
|
||
.PerformInteractiveRebinding(bindingIndex)
|
||
.WithCancelingThrough("<Keyboard>/escape")
|
||
.OnMatchWaitForAnother(0.1f)
|
||
.OnCancel(_ => FinishRebind(false))
|
||
.OnComplete(_ =>
|
||
{
|
||
string conflict = ConflictDetector.FindConflict(action, bindingIndex,
|
||
_inputReader.GetInputActionAsset());
|
||
if (conflict != null)
|
||
{
|
||
// TODO: 弹出冲突提示对话框（见 §5），暂时允许覆盖
|
||
Debug.LogWarning($"绑定冲突：{conflict}，已覆盖");
|
||
}
|
||
FinishRebind(true);
|
||
})
|
||
.Start();
|
||
}
|
||
|
||
void FinishRebind(bool save)
|
||
{
|
||
_currentOp?.Dispose();
|
||
_currentOp = null;
|
||
_listeningOverlay.style.display = DisplayStyle.None;
|
||
_inputReader.EnableGameplayInput();
|
||
if (save) RebindPersistence.Save(_inputReader.GetInputActionAsset());
|
||
// 刷新所有行
|
||
var root = _doc.rootVisualElement;
|
||
BuildRows(root.Q("ActionList"));
|
||
}
|
||
|
||
void OnResetAll()
|
||
{
|
||
_inputReader.GetInputActionAsset().RemoveAllBindingOverrides();
|
||
RebindPersistence.Clear();
|
||
BuildRows(_doc.rootVisualElement.Q("ActionList"));
|
||
}
|
||
|
||
void OnCancelRebind() => _currentOp?.Cancel();
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. RebindActionRow — 单行绑定控件
|
||
|
||
```csharp
|
||
namespace BaseGames.Input
|
||
{
|
||
public class RebindActionRow
|
||
{
|
||
public VisualElement Root { get; }
|
||
public event System.Action<InputAction, int> OnRebindRequested;
|
||
|
||
readonly InputAction _action;
|
||
readonly int _bindingIndex;
|
||
readonly Label _actionNameLabel;
|
||
readonly Label _currentBindingLabel;
|
||
readonly Button _rebindButton;
|
||
|
||
public RebindActionRow(InputAction action, int bindingIndex, VisualTreeAsset template)
|
||
{
|
||
_action = action;
|
||
_bindingIndex = bindingIndex;
|
||
Root = template.CloneTree();
|
||
|
||
_actionNameLabel = Root.Q<Label>("ActionName");
|
||
_currentBindingLabel = Root.Q<Label>("CurrentBinding");
|
||
_rebindButton = Root.Q<Button>("RebindButton");
|
||
|
||
_actionNameLabel.text = action.name;
|
||
Refresh();
|
||
|
||
_rebindButton.clicked += () => OnRebindRequested?.Invoke(_action, _bindingIndex);
|
||
}
|
||
|
||
public void Refresh()
|
||
{
|
||
_currentBindingLabel.text = KeyDisplayNameResolver.Resolve(
|
||
_action.bindings[_bindingIndex]);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### RebindActionRow.uxml
|
||
|
||
```xml
|
||
<ui:VisualElement class="rebind-row">
|
||
<ui:Label name="ActionName" class="action-name"/>
|
||
<ui:Label name="CurrentBinding" class="binding-label"/>
|
||
<ui:Button name="RebindButton" text="重新绑定" class="rebind-btn"/>
|
||
</ui:VisualElement>
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 冲突检测
|
||
|
||
当新绑定路径已被其他 Action 使用时，触发冲突警告：
|
||
|
||
```csharp
|
||
namespace BaseGames.Input
|
||
{
|
||
public static class ConflictDetector
|
||
{
|
||
/// <returns>冲突的 Action 名称，无冲突返回 null</returns>
|
||
public static string FindConflict(
|
||
InputAction editingAction,
|
||
int editingBindingIndex,
|
||
InputActionAsset asset)
|
||
{
|
||
string newPath = editingAction.bindings[editingBindingIndex].effectivePath;
|
||
if (string.IsNullOrEmpty(newPath)) return null;
|
||
|
||
foreach (var map in asset.actionMaps)
|
||
foreach (var otherAction in map.actions)
|
||
{
|
||
if (otherAction == editingAction) continue;
|
||
foreach (var binding in otherAction.bindings)
|
||
{
|
||
if (binding.effectivePath == newPath)
|
||
return otherAction.name;
|
||
}
|
||
}
|
||
return null;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 冲突 UI 处理策略
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|---------|
|
||
| 绑定与同 ActionMap 的其他 Action 冲突 | 弹出提示：「{冲突Action} 将失去该按键绑定，是否继续？」|
|
||
| 绑定与不同 ActionMap 冲突（如 UI Map）| 忽略，不同 Map 间不冲突 |
|
||
| 重复按下同一按键（与自身绑定相同）| 忽略，等价于不变 |
|
||
|
||
---
|
||
|
||
## 6. 按键名称显示（Key-to-String）
|
||
|
||
将 `InputBinding.effectivePath`（如 `<Keyboard>/space`）转换为玩家友好字符串：
|
||
|
||
```csharp
|
||
namespace BaseGames.Input
|
||
{
|
||
public static class KeyDisplayNameResolver
|
||
{
|
||
static readonly Dictionary<string, string> _overrides = new()
|
||
{
|
||
{ "<Keyboard>/leftShift", "LShift" },
|
||
{ "<Keyboard>/rightShift", "RShift" },
|
||
{ "<Keyboard>/leftCtrl", "LCtrl" },
|
||
{ "<Keyboard>/space", "空格" },
|
||
{ "<Keyboard>/escape", "Esc" },
|
||
{ "<Keyboard>/backspace", "退格" },
|
||
{ "<Keyboard>/enter", "回车" },
|
||
{ "<Gamepad>/buttonSouth", "× / A" },
|
||
{ "<Gamepad>/buttonNorth", "△ / Y" },
|
||
{ "<Gamepad>/buttonEast", "○ / B" },
|
||
{ "<Gamepad>/buttonWest", "□ / X" },
|
||
{ "<Gamepad>/leftShoulder", "L1 / LB" },
|
||
{ "<Gamepad>/rightShoulder","R1 / RB" },
|
||
{ "<Gamepad>/leftTrigger", "L2 / LT" },
|
||
{ "<Gamepad>/rightTrigger", "R2 / RT" },
|
||
{ "<Gamepad>/start", "Start" },
|
||
};
|
||
|
||
public static string Resolve(InputBinding binding)
|
||
{
|
||
string path = binding.effectivePath;
|
||
if (string.IsNullOrEmpty(path)) return "未绑定";
|
||
if (_overrides.TryGetValue(path, out string display)) return display;
|
||
|
||
// 默认：取 path 最后一段并首字母大写
|
||
int slash = path.LastIndexOf('/');
|
||
string key = slash >= 0 ? path[(slash + 1)..] : path;
|
||
return char.ToUpper(key[0]) + key[1..];
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 持久化存储
|
||
|
||
```csharp
|
||
namespace BaseGames.Input
|
||
{
|
||
public static class RebindPersistence
|
||
{
|
||
const string PrefsKey = "InputBindingOverrides";
|
||
|
||
public static void Save(InputActionAsset asset)
|
||
{
|
||
string json = asset.SaveBindingOverridesAsJson();
|
||
PlayerPrefs.SetString(PrefsKey, json);
|
||
PlayerPrefs.Save();
|
||
}
|
||
|
||
public static void Load(InputActionAsset asset)
|
||
{
|
||
if (!PlayerPrefs.HasKey(PrefsKey)) return;
|
||
string json = PlayerPrefs.GetString(PrefsKey);
|
||
if (!string.IsNullOrEmpty(json))
|
||
asset.LoadBindingOverridesFromJson(json);
|
||
}
|
||
|
||
public static void Clear()
|
||
{
|
||
PlayerPrefs.DeleteKey(PrefsKey);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 加载时机
|
||
|
||
在 `InputReaderSO.OnEnable()` 中调用 `RebindPersistence.Load(inputActionAsset)`，确保进入游戏前绑定已恢复：
|
||
|
||
```csharp
|
||
// InputReaderSO.cs
|
||
void OnEnable()
|
||
{
|
||
if (_inputActions == null) _inputActions = new PlayerInputActions();
|
||
RebindPersistence.Load(_inputActions.asset);
|
||
_inputActions.Enable();
|
||
// ... 注册回调
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 设备切换后自动刷新
|
||
|
||
当玩家切换设备（键盘 ↔ 手柄）时，UI 面板中的按键图标/文字需要更新：
|
||
|
||
```csharp
|
||
// RebindPanel.OnEnable() 中订阅
|
||
InputSystem.onActionChange += OnActionChange;
|
||
InputSystem.onDeviceChange += OnDeviceChange;
|
||
|
||
void OnDeviceChange(InputDevice device, InputDeviceChange change)
|
||
{
|
||
if (change == InputDeviceChange.Added ||
|
||
change == InputDeviceChange.Removed)
|
||
{
|
||
// 重新构建行（自动根据当前活跃设备过滤绑定）
|
||
BuildRows(_doc.rootVisualElement.Q("ActionList"));
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 完整实现示例
|
||
|
||
### 初始化序列
|
||
|
||
```
|
||
游戏启动
|
||
│
|
||
▼
|
||
InputReaderSO.OnEnable()
|
||
└─ RebindPersistence.Load(asset) // 从 PlayerPrefs 恢复 Override
|
||
│
|
||
▼
|
||
玩家打开设置 → SettingsPanel.ShowTab("键位")
|
||
└─ RebindPanel.OnEnable()
|
||
└─ BuildRows() // 遍历 ShownActions 构建 RebindActionRow
|
||
│
|
||
▼
|
||
玩家点击 [重新绑定]
|
||
└─ StartRebind(action, bindingIndex)
|
||
└─ PerformInteractiveRebinding()
|
||
│
|
||
▼
|
||
玩家按下新按键
|
||
└─ ConflictDetector.FindConflict() // 检查冲突
|
||
└─ FinishRebind(true)
|
||
├─ RebindPersistence.Save()
|
||
└─ BuildRows() // 刷新 UI
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 编辑器友好设计
|
||
|
||
### RebindPanel 自定义 Inspector
|
||
|
||
```csharp
|
||
[CustomEditor(typeof(RebindPanel))]
|
||
public class RebindPanelEditor : Editor
|
||
{
|
||
public override VisualElement CreateInspectorGUI()
|
||
{
|
||
var root = new VisualElement();
|
||
InspectorElement.FillDefaultInspector(root, serializedObject, this);
|
||
|
||
var testBtn = new Button(() =>
|
||
{
|
||
if (Application.isPlaying)
|
||
Debug.Log("当前绑定 JSON:\n" +
|
||
((RebindPanel)target)
|
||
// 通过反射或公开方法访问 asset
|
||
.GetComponent<UIDocument>() != null
|
||
? "[请在 Play Mode 下查看]"
|
||
: "未运行");
|
||
}) { text = "输出当前绑定 JSON（Play Mode）" };
|
||
root.Add(testBtn);
|
||
return root;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 快速验证清单
|
||
|
||
| 验证项 | 方法 |
|
||
|--------|------|
|
||
| Override 是否持久化 | 重映射后重启游戏，检查按键是否保留 |
|
||
| 冲突检测是否触发 | 将两个 Action 绑定到同一键，检查警告弹窗 |
|
||
| 恢复默认是否生效 | 点击「恢复默认」后所有绑定回到 InputActions 资产原始值 |
|
||
| 设备切换刷新 | 拔插手柄，检查 UI 文字是否更新 |
|