← Руководство

Клавиатурные события

События клавиатуры происходят, когда вы нажимаете или отпускаете клавиши на клавиатуре. Каждое событие содержит информацию о modifier, текстовом символеи соответствующем коде клавиши для события.

Многие стандартные элементы управления используют KeyDownEvent для кодирования ярлыков или поведения доступности. Все следующие примеры используют события клавиатуры:

Классы Toggle и Button просматривают нажатия клавиш Enter и Spacebar как действия замены кликов мыши.
Контроллеры ScrollView и Slider используют клавиши со стрелками для изменения их значений.
Контроллер TextField смотрит как на свойство keyCode, так и на свойство character для выполнения специальных действий или принятия текста.

Базовый класс для всех событий клавиатуры — KeyboardEventBase.

В следующей таблице описаны события клавиатуры и фазы их распространения.

Мероприятие	Описание	Просыпается	Пузырьки вверх	Аннулируемые
KeyDownEvent	Отправляется, когда пользователь нажимает клавишу на клавиатуре.	Да	Да	Да
KeyUpEvent	Отправляется, когда пользователь отпускает клавишу на клавиатуре.	Да	Да	Да

Уникальные свойства

keyCode: Свойство keyCode возвращает символьную клавишу, которая соответствует физической клавише на устройстве ввода, таком как клавиатура или джойстик. Разница между свойством character и свойством keyCode в том, что keyCode представляет физическую клавишу, в то время как character представляет ввод определенного символа. Например, a и A возвращают keyCode=KeyCode.A во время keyDownEvent.

character: Свойство character возвращает код символа во время keyDownEvent.

modifiers: Свойство modifiers возвращает информацию о том, какая клавишная комбинация была нажата. Примерами клавишных комбинаций являются Shift, Ctrlили Alt.

Дополнительные сведения см. в разделе Клавиши модификатора документации по MDN.

Список событий

В следующем списке приведены имя, описание и назначение каждого события в семействе событий.

По умолчанию визуальный элемент не получает событий клавиатуры. Только элементы, которые фокусируются и в настоящее время находятся в фокусе, являются объектами событий клавиатуры. Это происходит потому, что события клавиатуры просачиваются вниз и вверх, позволяя родительским элементам также получать их.

В общем, чтобы начать получать события клавиатуры, вы должны пометить элемент как focusable=true и явно дать ему фокус с помощью element.Focus(). Это гарантирует, что элемент может получать события клавиатуры.

KeyDownEvent

KeyDownEvent отправляется каждый раз, когда вы нажимаете клавишу на клавиатуре. Нажимаемая клавиша содержит свойство keyCode для этого события. Если с этим нажатием клавиши связан текстовый ввод, дополнительные события отправляются для каждого символа текстового ввода. Свойство character содержит символ для этих событий.

Когда вы нажимаете и отпускаете a, UI Toolkit отправляет следующие события:


KeyDownEvent { keyCode=KeyCode.A }
KeyDownEvent { character=’a’ }
KeyUpEvent { keyCode=KeyCode.A }

Когда вы нажимаете и отпускаете Ctrl+a, UI Toolkit отправляет следующие события:


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 Toolkit отправляет следующие события:

KeyDownEvent { keyCode=KeyCode.A }
KeyDownEvent { character=’a’ }
KeyUpEvent { keyCode=KeyCode.A }

Когда вы нажимаете и отпускаете Ctrl+a, UI Toolkit отправляет следующие события:


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 }

Примеры

Следующий пример кода отображает сообщение в консоли при нажатии клавиши в TextField. В этом примере кода выделяется запуск событий KeyUpEvent и KeyDownEvent.

Создайте проект Unity с любым шаблоном.
В SampleScene, выберите GameObject > UI Toolkit > UI Документ.

Создайте скрипт C# с именем KeyboardEventTest.cs со следующим содержанием:

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

Выберите UIDocument GameObject в окне Hierarchy.
Перетащите KeyboardEventTest.cs в Добавить компонент в окне Inspector.
Введите режим воспроизведения и введите TextField.