95 lines
5.6 KiB
Markdown
95 lines
5.6 KiB
Markdown
# 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;
|
|
}
|
|
```
|