键盘事件

当您按下或释放键盘上的键时会发生键盘事件。每个事件都包含有关该事件的修改键、字符以及关联的键代码。

许多标准控件使用 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 文档的“修改键”部分。

事件列表

以下列表提供了该事件系列中每个事件的名称、描述和目标。有关事件的更多信息，请参阅 UI 工具包 API。

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);
    }
}