AlicizaX/Client/Assets/Books/UIExtension/InputGlyph.md

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

示例

if (GlyphService.TryGetUISpriteForActionPath(actionRef, null, InputDeviceWatcher.CurrentCategory, out var sprite))
{
    image.sprite = sprite;
}