键盘事件

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

许多标准控件使用 KeyDownEvent 实现快捷方式或辅助操作的编码。以下示例均使用键盘事件：

Toggle 和 Button 类监听 Enter 和 Spacebar 按键作为鼠标点击的替代动作。
ScrollView 和 Slider 控件使用方向箭头按键来调整它们的值。
TextField 控件根据 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 文档的修改键部分。

事件列表

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

默认情况下，视觉元素不会接收键盘事件。只有可聚焦且当前处于焦点的元素才是键盘事件的目标。这是因为键盘事件会涓滴和冒泡，从而也允许父元素接收它们。

总之，要开始接收键盘事件，必须将元素标记为 focusable=true，并使用 element.Focus() 显式为其指定焦点。这样可以确保元素有资格接收键盘事件。

KeyDownEvent

KeyDownEvent 在每次按下键盘上的键时发送。按下的键包含该事件的 keyCode 属性。如果该按键具有与之关联的文本输入，则会为文本输入的每个字符发送额外的事件。character 属性包含这些事件的字符。

当您按下并释放 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：具有焦点的视觉元素。如果没有元素具有焦点，则为面板的根视觉元素。

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 工具包 (UI Toolkit) > UI 文档 (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 游戏对象。
在检视面板 (Inspector) 窗口中，将 KeyboardEventTest.cs 拖动到添加组件 (Add Component)。
进入运行模式并在 TextField 中输入。

其他资源

输入事件

鼠标事件

Unity 手册