テキスト フィールドにフォーカス

ユーザーがハードウェア キーボード、D-pad、ロータリー コントローラを使用して Compose UI を操作する場合、テキスト フィールドは他のフォーカス ターゲットとともにフォーカス ナビゲーションに参加します。

デフォルトでは、フォーカスはテキスト フィールドにトラップされません。ユーザーがテキスト フィールドから離れることができるようにするために、カスタムキー イベント ハンドラ（onKeyEvent または onPreviewKeyEvent）を追加する必要はありません。ユーザーは、Shift+Tab を使用するか、方向キーでテキストの境界を越えて移動することで、いつでも終了できます。

KeyboardOptions を使用すると、ハードウェア キーボード ナビゲーションと連携する直感的なソフトウェア キーボード アクションを提供できます。たとえば、ImeAction.Next を押すと、フォーカスが次のフォーカス ターゲットに移動します。

1 次元のフォーカス走査

1 次元フォーカス走査では、Tab キーの動作は、テキスト フィールドに構成されている lineLimits によって異なります。

• 1 行のテキスト フィールド（TextFieldLineLimits.SingleLine） Tab キーを押すと、UI の次のフォーカス ターゲットにフォーカスが移動します。
• 複数行テキスト フィールド（TextFieldLineLimits.MultiLine() またはデフォルト）: Tab キーを押すと、フォーカスが移動するのではなく、タブ文字（\t）がテキスト バッファに挿入されます。
• 逆方向のナビゲーション（Shift+Tab）: Shift+Tab キーを押すと、1 行のテキスト フィールドと複数行のテキスト フィールドの両方で、フォーカスが前のフォーカス ターゲットに無条件で戻ります。

// Single-line text field: Tab advances focus to the next focus target
BasicTextField(
    state = singleLineState,
    lineLimits = TextFieldLineLimits.SingleLine,
    modifier = Modifier.fillMaxWidth()
)

// Multi-line text field: Tab inserts '\t'; Shift + Tab moves to previous target
BasicTextField(
    state = multiLineState,
    lineLimits = TextFieldLineLimits.MultiLine(),
    modifier = Modifier.fillMaxWidth()
)
FocusInTextFields.kt

2 次元フォーカス走査

矢印キー（または D-pad）を使用する場合、方向キーはまずテキスト フィールド内でテキスト カーソル（キャレット）を移動します。

• 垂直方向の移動（上 / 下）: Down キーを押すと、カーソルが 1 行ずつ下に移動します。カーソルが最後の行に到達したときに、下キーをもう一度押すと、テキスト フィールドの下にある隣接するフォーカス ターゲットにフォーカスが移動します。最初の行で 上キーを押すと、フォーカスが前のフォーカス ターゲットに移動します。
• 水平方向のナビゲーション（左 / 右 / 開始 / 終了）: 水平方向の矢印キーを押すと、カーソルが文字間を移動します。キャレットがテキスト バッファの先頭または末尾に到達したときに、方向キーをもう一度押すと、その方向にある隣接するフォーカス ターゲットにフォーカスが移動します。

Android TV のテキスト フィールド

Android TV で、物理キーボードを使用せずに D-pad コントローラを使用する場合:

1. テキスト フィールドにフォーカスを移動すると、画面上のソフトウェア キーボードが自動的に表示されます。
2. ユーザーは D-pad を使用してソフトウェア キーボードのキーを操作します。
3. 戻るボタンを押すと、テキスト フィールドにフォーカスを維持したまま、ソフトウェア キーボードが閉じます。
4. ソフトウェア キーボードを閉じると、D-pad の方向キーを押すことで、画面上の隣接するフォーカス ターゲットにフォーカスが移動します。
5. [戻る] ボタンを 2 回目に押すと、標準のシステム戻るナビゲーションがトリガーされます。