キーボードイベントは、キーボードのキーを押下またはリリースするときに発生します。各イベントには、イベントのモディファイア、テキスト文字、および関連キーコードに関する情報が含まれます。
多くの標準コントロールは、ショートカットやアクセシビリティの動作をエンコードするために、KeyDownEvent を使用しています。以下の例はすべて、キーボードイベントを使用しています。
Toggle と Button クラスは、Enter と Spacebar のキー押下を、マウスクリックの代替としてリッスンします。keyCode プロパティと文字プロパティの両方を見て、特別なアクションを実行したり、テキストを受け入れたりします。すべてのキーボードイベントの基本クラスは KeyboardEventBase です。
| イベント | 説明 | 下降 | 上昇 | キャンセル可能 |
|---|---|---|---|---|
| KeyDownEvent | ユーザーがキーボードのキーを押下するときに送信されます。 | はい | はい | はい |
| KeyUpEvent | ユーザーがキーボードのキーを離すときに送信されるイベント | はい | はい | はい |
keyCode: keyCode プロパティは、キーボードやジョイスティックなどの入力デバイスの物理的なキーに直接対応する文字キーを返します。character プロパティと keyCode プロパティの違いは、keyCode が物理的なキーを表しているのに対し、character は特定の文字の入力を表していることです。例えば、a と A はどちらも、keyDownEvent 中に keyCode=KeyCode.A を返します。
character: keyDownEvent の間に、character プロパティは文字コードを返します。
modifiers: modifiers プロパティは、どの修飾キーが押されているかを返します。修飾キーの例としては、Shift、Ctrl、Alt キーなどがあります。
詳細については、MDN ドキュメントの修飾キーのセクションを参照してください。
以下のリストは、イベントファミリの各イベントの名前、説明、およびターゲットを示しています。
デフォルトでは、ビジュアル要素はキーボードイベントを受け取りません。フォーカス可能で現在フォーカスされている要素のみがキーボードイベントのターゲットになります。これは、キーボードイベントが下降と上昇を繰り返し、親要素もそれを受け取ることができるからです。
つまり、キーボードイベントの受信を開始するには、要素を focusable=true としてマークし、element.Focus() を使用して明示的にフォーカスを与える必要があります。これにより、要素は確実にキーボードイベントを受け取ることができます。
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 は、キーボードのキーをリリースするときに送信されます。そのイベントの 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 }
target: フォーカスがあるビジュアル要素。フォーカスがある要素がない場合は、パネルのルートビジュアル要素。
以下のコードサンプルでは、ユーザーがテキストフィールドのキーを押すと、コンソールにメッセージが表示されます。このコードサンプルでは、KeyUpEvent と KeyDownEvent の両方のイベントの発生を強調しています。
任意のテンプレートで Unity プロジェクトを作成します。
サンプルシーンで GameObject > UI Toolkit > UI Document の順に選択します。
以下のコンテンツの 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);
}
}
Hierarchy ウィンドウで UIDocument ゲームオブジェクトを選択します。
Inspector ウィンドウで KeyboardEventTest.cs を Add Component にドラッグします。
再生モードに入り、テキストフィールドに入力します。