键盘事件

当您按下或释放键盘上的键时，会发生键盘事件。每个事件都包含有关修饰符、文本字符和相关键码的信息。

许多标准控件使用KeyDownEvent来编码快捷键或辅助功能行为。以下示例都使用键盘事件

Toggle 和 Button 类监听Enter 和 Spacebar 键按下，作为鼠标点击的替代操作。
ScrollView一个 UI 控件，在一个可视区域中显示大量控件，您可以使用滚动条查看。更多信息
参见术语表和滑块控件使用方向箭头键按下以调节它们的值。
TextField 控件TextField 控件向用户显示一个非交互式的文本片段，例如标题、其他 GUI 控件的标签或说明。更多信息
参见术语表查看keyCode 属性和character 属性，以执行特殊操作或接受文本。

所有键盘事件的基类是KeyboardEventBase。

事件	描述	向下传递	向上冒泡	可取消
KeyDownEvent	当用户按下键盘上的键时发送。	是	是	是
KeyUpEvent	当用户释放键盘上的键时发送。	是	是	是

唯一属性

keyCode：keyCode 属性返回一个字符键，该字符键直接对应于输入设备（例如键盘或操纵杆）上的物理键。character 属性和keyCode 属性之间的区别在于，keyCode 表示物理键，而character 表示特定字符的输入。例如，a 和 A 在keyDownEvent 期间都返回keyCode=KeyCode.A。

character：character 属性在keyDownEvent 期间返回一个字符代码。

modifiers：modifiers 属性返回按下的修饰键。修饰键的一些示例包括Shift、Ctrl 或 Alt 键。

有关更多信息，请参阅 MDN 文档的修饰键部分。

事件列表

以下列表提供事件系列中每个事件的名称、描述和目标。

默认情况下，视觉元素一个视觉树的节点，它实例化或派生自 C# VisualElement 类。您可以设置外观、定义行为并将其显示在屏幕上作为 UI 的一部分。更多信息
参见术语表不会接收键盘事件。只有可获得焦点的元素并且当前处于焦点状态的元素才是键盘事件的目标。这是因为键盘事件向下传递并向上冒泡，允许父元素也接收它们。

总之，要开始接收键盘事件，您必须将元素标记为focusable=true 并使用element.Focus() 明确地赋予它焦点。这确保了元素有资格接收键盘事件。

KeyDownEvent

每次您按下键盘上的键时，都会发送一个KeyDownEvent。按下的键包含该事件的keyCode 属性。如果该键按下与文本输入相关联，则会为每个文本输入字符发送其他事件。character 属性包含这些事件的字符。

当您按下并释放a 时，UI(用户界面) 允许用户与您的应用程序交互。Unity 目前支持三种 UI 系统。更多信息
参见术语表工具包会发送以下事件


KeyDownEvent { keyCode=KeyCode.A }
KeyDownEvent { character=’a’ }
KeyUpEvent { keyCode=KeyCode.A }

当您按下并释放Ctrl+a 时，UI 工具包会发送以下事件


KeyDownEvent { keyCode=KeyCode.LeftControl, modifiers=EventModifiers.Control }
KeyDownEvent { keyCode=KeyCode.A, modifiers=EventModifiers.Control }
KeyUpEvent { keyCode=KeyCode.A, modifiers=EventModifiers.Control }
KeyUpEvent { keyCode=KeyCode.LeftControl }

target：具有焦点的视觉元素。如果没有元素具有焦点，则为面板的根视觉元素。

KeyUpEvent

当您释放键盘上的键时，会发送一个KeyUpEvent。该事件的keyCode 属性包含要释放的键。当键击与文本输入相关联时，KeyDownEvent 会发送其他事件。

当您按下并释放a 时，UI 工具包会发送以下事件

KeyDownEvent { keyCode=KeyCode.A }
KeyDownEvent { character=’a’ }
KeyUpEvent { keyCode=KeyCode.A }

当您按下并释放Ctrl+a 时，UI 工具包会发送以下事件


KeyDownEvent { keyCode=KeyCode.LeftControl, modifiers=EventModifiers.Control }
KeyDownEvent { keyCode=KeyCode.A, modifiers=EventModifiers.Control }
KeyUpEvent { keyCode=KeyCode.A, modifiers=EventModifiers.Control }
KeyUpEvent { keyCode=KeyCode.LeftControl }

target：具有焦点的视觉元素。如果没有元素具有焦点，则为面板的根视觉元素。

示例

以下代码示例在您在 TextField 中按下键时将消息打印到控制台。此代码示例突出显示了KeyUpEvent 和KeyDownEvent 的事件触发。

使用任何模板创建一个 Unity 项目。
在 SampleScene 中，选择GameObject > UI Toolkit > UI Document。

创建一个名为KeyboardEventTest.cs 的 C# 脚本，内容如下

using UnityEngine;
using UnityEngine.UIElements;

// Add KeyboardEventTest to a GameObject with a valid UIDocument.
// When the user presses a key, it will print the keyboard event properties to the console.
[RequireComponent(typeof(UIDocument))]
public class KeyboardEventTest : MonoBehaviour
{
    void OnEnable()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;
        root.Add(new Label("Press any key to see the keyDown properties"));
        root.Add(new TextField());
        root.Q<TextField>().Focus();
        root.RegisterCallback<KeyDownEvent>(OnKeyDown, TrickleDown.TrickleDown);
        root.RegisterCallback<KeyUpEvent>(OnKeyUp, TrickleDown.TrickleDown);
    }
    void OnKeyDown(KeyDownEvent ev)
    {
        Debug.Log("KeyDown:" + ev.keyCode);
        Debug.Log("KeyDown:" + ev.character);
        Debug.Log("KeyDown:" + ev.modifiers);
    }

    void OnKeyUp(KeyUpEvent ev)
    {
        Debug.Log("KeyUp:" + ev.keyCode);
        Debug.Log("KeyUp:" + ev.character);
        Debug.Log("KeyUp:" + ev.modifiers);
    }
}

在 Hierarchy 窗口中选择 UIDocument GameObjectUnity 场景中的基本对象，可以代表角色、道具、场景、摄像机、航点等。GameObject 的功能由附加到它的组件定义。更多信息
参见术语表。
将KeyboardEventTest.cs 拖动到Inspector一个 Unity 窗口，显示有关当前选择的 GameObject、资源或项目设置的信息，允许您检查和编辑值。更多信息
参见术语表窗口中的添加组件。
进入播放模式并在 TextField 中键入。

其他资源

输入事件

鼠标事件

Unity 手册