キーボードイベント

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 プロパティと文字プロパティの両方を見て、特別なアクションを実行したり、テキストを受け入れたりします。

すべてのキーボードイベントの基本クラスは KeyboardEventBase です。

固有のプロパティ

keyCode: keyCode プロパティは、キーボードやジョイスティックなどの入力デバイスの物理的なキーに直接対応する文字キーを返します。character プロパティと keyCode プロパティの違いは、keyCode が物理的なキーを表しているのに対し、character は特定の文字の入力を表していることです。例えば、keyDownEvent の間に a と A の両方とも keyCode=KeyCode.A を 返します。

character: keyDownEvent の間に、character プロパティは文字コードを返します。

modifiers: modifiers プロパティは、どのモディファイアキーが押されているかを返します。修飾キーの例としては、Shift、Ctrl、Alt キーなどがあります。

詳細は、修飾キー のセクションを参照してください。

イベントリスト

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

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 は、キーボードのキーを離すときに送られます。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 }

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.

1. Create a Unity project with any template.

2. In the SampleScene, select GameObject > UI Toolkit > UI Document.

3. Create a C# script named KeyboardEventTest.cs with the following contents:

   using UnityEngine;
   using UnityEngine.UIElements;
   
   // 有効な UIDocument を使用して KeyboardEventTest をゲームオブジェクトに加えます。
   // ユーザーがキーを押すと、キーボードイベントのプロパティがコンソールに出力されます。
   [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);
       }
   }
   

4. Select the UIDocument GameObject in the Hierarchy window.

5. Drag KeyboardEventTest.cs to Add Component in the Inspector window.

6. Enter Play mode and type in the TextField.

その他の参考資料

• UI Toolkit events
• UI Toolkit built-in controls reference
• UI Toolkit controls
• UI Toolkit controls examples