將焦點移到文字欄位

使用者透過硬體鍵盤、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. 按下「Back」按鈕會關閉螢幕鍵盤，同時保留文字欄位的焦點。
4. 關閉螢幕鍵盤後，按下 D-pad 方向鍵會將焦點移至畫面上的相鄰焦點目標。
5. 第二次按下「返回」按鈕時，會觸發標準系統返回導覽。