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 element 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.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.