# UIExtension InputGlyph 输入图标模块手册

## 模块概述
`InputGlyph` 提供输入设备检测、绑定解析、图标数据库查询、UI Image/TMP 输出和重绑定后自动刷新能力。

## 适用场景
- 显示键盘、手柄按键图标。
- 文本中嵌入按键提示。
- 输入重绑定后自动刷新 UI 提示。

## 快速上手
1. 创建 `InputGlyphDatabase` 并放到 `Resources/InputGlyphDatabase.asset`。
2. 给目标对象挂 `InputGlyph`。
3. 选择动作来源与输出模式。

## 详细使用说明
- `InputGlyph` 会监听 `InputDeviceWatcher` 与 `InputBindingManager.BindingsChanged`。
- 输出为 `Image` 时设置 `targetImage.sprite`。
- 输出为 `Text` 时写入 TMP `<sprite>` 标签或回退显示文本。

## 可调用 API
### 类型：`InputGlyph`
源码：`Packages/com.alicizax.unity.ui.extension/Runtime/InputGlyph/InputGlyph.cs`
- 枚举：`ActionSourceMode`、`OutputMode`
- 类型：`DeviceCategoryEvent`
  - `category`
  - `onMatched`
  - `onNotMatched`

### 类型：`InputGlyphBehaviourBase`
源码：`Packages/com.alicizax.unity.ui.extension/Runtime/InputGlyph/InputGlyphBehaviourBase.cs`
- 说明：抽象基类，负责设备变化与绑定变化监听。

### 类型：`GlyphService`
源码：`Packages/com.alicizax.unity.ui.extension/Runtime/InputGlyph/Core/GlyphService.cs`
- `GetBindingControlPath(InputAction action, string compositePartName = null, InputDeviceWatcher.InputDeviceCategory? deviceOverride = null)`
- `GetBindingControlPath(InputActionReference actionReference, string compositePartName = null, InputDeviceWatcher.InputDeviceCategory? deviceOverride = null)`
- `TryGetTMPTagForActionPath(InputAction action, string compositePartName, InputDeviceWatcher.InputDeviceCategory device, out string tag, out string displayFallback, InputGlyphDatabase db = null)`
- `TryGetTMPTagForActionPath(InputActionReference actionReference, string compositePartName, InputDeviceWatcher.InputDeviceCategory device, out string tag, out string displayFallback, InputGlyphDatabase db = null)`
- `TryGetUISpriteForActionPath(InputAction action, string compositePartName, InputDeviceWatcher.InputDeviceCategory device, out Sprite sprite, InputGlyphDatabase db = null)`
- `TryGetUISpriteForActionPath(InputActionReference actionReference, string compositePartName, InputDeviceWatcher.InputDeviceCategory device, out Sprite sprite, InputGlyphDatabase db = null)`
- `TryGetTMPTagForActionPath(string controlPath, InputDeviceWatcher.InputDeviceCategory device, out string tag, out string displayFallback, InputGlyphDatabase db = null)`
- `TryGetUISpriteForActionPath(string controlPath, InputDeviceWatcher.InputDeviceCategory device, out Sprite sprite, InputGlyphDatabase db = null)`
- `GetDisplayNameFromInputAction(InputAction action, string compositePartName = null, InputDeviceWatcher.InputDeviceCategory? deviceOverride = null)`
- `GetDisplayNameFromControlPath(string controlPath)`
- `TryGetBindingControl(InputAction action, string compositePartName, InputDeviceWatcher.InputDeviceCategory? deviceOverride, out InputBinding binding)`

### 类型：`InputActionReader`
源码：`Packages/com.alicizax.unity.ui.extension/Runtime/InputGlyph/Core/InputActionReader.cs`
- `ReadValue<T>(string actionName)`
- `ReadValue(string actionName)`
- `TryReadValue<T>(string actionName, out T value)`
- `TryReadValue(string actionName, out object value)`
- `TryReadValueOnce<T>(UnityEngine.Object owner, string actionName, out T value)`
- `ReadButton(string actionName)`
- `ReadButtonOnce(UnityEngine.Object owner, string actionName)`
- `ReadButtonOnce(int instanceID, string actionName)`
- `ReadButtonOnce(string key, string actionName)`
- `ReadButtonToggle(UnityEngine.Object owner, string actionName)`
- `ReadButtonToggle(int instanceID, string actionName)`
- `ReadButtonToggle(string key, string actionName)`
- `ResetToggledButton(string key, string actionName)`
- `ResetToggledButton(string actionName)`
- `ResetToggledButtons()`

### 类型：`InputBindingManager`
源码：`Packages/com.alicizax.unity.ui.extension/Runtime/InputGlyph/Core/InputBindingManager.cs`
- 公开字段：`actions`、`debugMode`
- 事件：`OnApply`、`OnRebindPrepare`、`OnRebindStart`、`OnRebindEnd`、`OnRebindConflict`、`BindingsChanged`
- 属性：`ActionMaps`、`PreparedRebinds`
- 方法：`FindBestBindingIndexForKeyboard(...)`、`Action(string actionName)`、`TryGetAction(...)`、`StartRebind(...)`、`CancelRebind()`、`ConfirmApply(...)`、`DiscardPrepared()`、`ResetToDefaultAsync()`、`GetBindingPath(...)`
- 公开嵌套类型：`ActionMap`、`Action`、`Binding`、`BindingPath`、`RebindContext`

### 类型：`InputDeviceWatcher`
源码：`Packages/com.alicizax.unity.ui.extension/Runtime/InputGlyph/Core/InputDeviceWatcher.cs`
- 枚举：`InputDeviceCategory`
- 结构：`DeviceContext`
- 属性：`CurrentCategory`、`CurrentDeviceName`、`CurrentDeviceId`、`CurrentVendorId`、`CurrentProductId`、`CurrentContext`
- 事件：`OnDeviceChanged`、`OnDeviceContextChanged`
- 方法：`Initialize()`、`Dispose()`

### 类型：`InputGlyphDatabase`
源码：`Packages/com.alicizax.unity.ui.extension/Runtime/InputGlyph/Data/InputGlyphDatabase.cs`
- 字段：`tables`、`placeholderSprite`
- 方法：`GetTable(string deviceName)`、`GetTable(InputDeviceWatcher.InputDeviceCategory device)`、`GetPlatformIcon(...)`、`TryGetSprite(...)`、`FindSprite(...)`、`FindEntryByControlPath(...)`、`EditorRefreshCache()`、`EditorNormalizeControlPath(...)`
- 类型：`GlyphEntry`、`DeviceGlyphTable`

## 示例
```csharp
if (GlyphService.TryGetUISpriteForActionPath(actionRef, null, InputDeviceWatcher.CurrentCategory, out var sprite))
{
    image.sprite = sprite;
}
```