將焦點移到文字欄位

使用者透過硬體鍵盤、D-Pad 或旋轉控制器瀏覽 Compose UI 時，文字欄位會與其他焦點目標一起參與焦點導覽。

根據預設，焦點不會停留在文字欄位中。您不需要新增自訂按鍵事件處理常式 (onKeyEvent 或 onPreviewKeyEvent)，即可允許使用者離開文字欄位。使用者隨時可以按下 Shift+Tab 鍵，或使用方向鍵瀏覽文字界線以外的內容，藉此退出編輯模式。

KeyboardOptions 可用來提供直覺式螢幕鍵盤動作，與硬體鍵盤導覽功能協調運作。例如，ImeAction.Next 會將焦點移至下一個焦點目標。

單一維度焦點遍歷

在單向焦點遍歷中，Tab 鍵的行為取決於文字欄位上設定的 lineLimits：

• 單行文字欄位 (TextFieldLineLimits.SingleLine) 按下 Tab 鍵可將焦點移至 UI 中的下一個焦點目標。
• 多行文字欄位 (TextFieldLineLimits.MultiLine() 或預設)： 按下 Tab 鍵會在文字緩衝區中插入 Tab 字元 (\t)，而不是移動焦點。
• 反向導覽 (Shift+Tab)： 按下 Shift+Tab 鍵會無條件將焦點向後移至 單行和多行文字欄位中的上一個焦點目標。

// 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

二維焦點遍歷

使用方向鍵 (或 D-Pad) 時，方向鍵會先在文字欄位中移動文字游標 (插入點)：

• 垂直導覽 (向上 / 向下)： 按 Down 鍵可逐行向下移動插入號。 當插入點到達最後一行時，再次按下「向下」鍵，焦點就會轉移至文字欄位下方的相鄰焦點目標。在第一行按下「向上」鍵，可將焦點移至前一個焦點目標。
• 水平導覽 (左 / 右 / 開始 / 結束)： 按下水平方向鍵，即可在字元間移動插入號。 當插入點抵達文字緩衝區的開頭或結尾時，再次按下方向鍵會將焦點轉移至該方向的相鄰焦點目標。

Android TV 上的文字欄位

在 Android TV 上使用 D-Pad 控制器 (不含實體鍵盤)：

1. 將焦點移至文字欄位時，系統會自動顯示螢幕軟體鍵盤。
2. 使用者使用 D-pad 瀏覽螢幕鍵盤的按鍵。
3. 按下「返回」按鈕會關閉螢幕鍵盤，但焦點仍會保留在文字欄位。
4. 軟體鍵盤關閉後，按下 D-Pad 方向鍵會將焦點移至畫面上的相鄰焦點目標。
5. 再次按下「返回」按鈕，即可觸發標準系統返回導覽。