键盘事件

Keyboard events occur when you press or release keys on the keyboard. Each event includes information about the modifier, text character, and related key code for the event.

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

• Toggle 和 Button 类监听 Enter 和 Spacebar 按键作为鼠标点击的替代动作。
• ScrollView 和 Slider 控件使用方向箭头按键来调整它们的值。
• TextField 控件根据 keyCode 属性和 character 属性执行特殊操作或接受文本。

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

独特的属性

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

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

modifiers：modifiers 属性返回按下的是哪个修改键。修改键的一些示例是 Shift、Ctrl 或 Alt 键。

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

事件列表

The following list provides the name, description, and target of each event in the event family.

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 的事件触发。

要查看示例运行效果，请执行以下操作：

1. 创建一个具有有效 UIDocument 的游戏对象。
2. 在 Assets > Scripts 下，创建一个 C# 脚本，名为 KeyboardEventTest。
3. 将该示例复制到 C# 脚本。
4. 将 KeyboardEventTest 脚本附加到带有 UIDocument 的游戏对象
5. 进入运行模式并在 TextField 中输入。

using UnityEngine;
using UnityEngine.UIElements;

// 将 KeyboardEventTest 添加到具有有效 UIDocument 的游戏对象。
// 当用户按下一个键时，它会将键盘事件的属性打印到控制台。
[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);
    }
}