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.
Many standard controls use the KeyDownEvent to encode shortcuts or accessibility behaviors. The following examples all use keyboard events:
Toggle 和 Button 类监听 Enter 和 Spacebar 按键作为鼠标点击的替代动作。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 文档的“修改键”部分。
The following list provides the name, description, and target of each event in the event family.
By default, a visual elementA node of a visual tree that instantiates or derives from the C# VisualElement class. You can style the look, define the behaviour, and display it on screen as part of the UI. More info
See in Glossary doesn’t receive keyboard events. Only elements that are focusable and currently in focus are targeted for keyboard events. This is because keyboard events trickle down and bubble up, allowing parent elements to receive them as well.
In summary, to begin receiving keyboard events, you must mark the element as focusable=true and explicitly give it focus using element.Focus(). This ensures that the element is eligible to receive keyboard events.
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 事件。该事件的 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：具有焦点的视觉元素。如果没有元素具有焦点，则为面板的根视觉元素。
The following code example prints a message to the console when you press a key in a TextField. This code sample highlights the event firing of both KeyUpEvent and KeyDownEvent.
Create a Unity project with any template.
In the SampleScene, select GameObject > UI Toolkit > UI Document.
Create a C# script named KeyboardEventTest.cs with the following contents:
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);
}
}
Select the UIDocument GameObject in the Hierarchy window.
Drag KeyboardEventTest.cs to Add Component in the Inspector window.
Enter Play mode and type in the TextField.