焦點遍歷順序

使用者可以使用 Tab 鍵或方向 (箭頭 / D-pad) 鍵，在 UI 元素之間移動鍵盤焦點：

  • Tab / Shift+Tab：在一維外觀順序中向前或向後移動焦點。
  • 方向鍵：在二維空間中移動焦點 (上、下、左和右)。

單一維度焦點遍歷

在單向焦點遍歷中，Tab 鍵會根據畫面上的視覺外觀順序，在 UI 中推進焦點。

舉例來說，如果四個按鈕排列成列：

Column {
    Row {
        Button(onClick = { /* ... */ }) { Text("1st") }
        Button(onClick = { /* ... */ }) { Text("2nd") }
    }
    Row {
        Button(onClick = { /* ... */ }) { Text("3rd") }
        Button(onClick = { /* ... */ }) { Text("4th") }
    }
}

按下 Tab 鍵後，焦點會依序在按鈕之間移動，順序如下：

  1. 第 1 個按鈕 (頂端開頭)
  2. 第 2 個按鈕 (頂端)
  3. 第 3 個按鈕 (底部開頭)
  4. 第 4 個按鈕 (底部)

在最後一個元素上按下 Tab 鍵，會回到第一個焦點目標。按下 Shift + Tab 鍵，焦點會反向移動。

二維焦點遍歷

按下鍵盤方向鍵或使用 D-Pad 會觸發二維焦點遍歷。

在二維遍歷中，系統會檢查 UI 元素的幾何座標和空間邊界，判斷指定方向上最接近的目標。

與使用 鍵的單向焦點遍歷功能不同，二維焦點遍歷功能不會循環。如果使用者在焦點位於最底部元素時按下向下鍵，焦點會停留在該元素上，而不會跳到畫面頂端。

使用指標點擊重設焦點周遊

在電腦或大螢幕裝置上切換實體鍵盤和滑鼠或觸控板時：

  • 輕觸或點選時清除焦點：使用滑鼠或觸控板點選或輕觸非互動空間，即可釋放焦點。
  • 重新開始遍歷：清除焦點後，下次按下 Tab 鍵時，系統會按照視覺外觀順序，從「第一個焦點目標」重新開始單一維度遍歷，而不是從先前啟用的元素繼續。這與二維焦點遍歷相同。方向鍵會將鍵盤焦點移至所選方向上最接近的焦點目標。

如要進一步瞭解如何透過程式輔助方式清除焦點，請參閱「移動及清除焦點」。

自訂焦點遍歷順序

您可以使用 focusProperties 修飾符自訂周遊行為。

自訂一維遍歷順序

如要覆寫一維周遊，請使用 FocusRequester 指定 next 或 previous 屬性：

  1. 使用 remember { FocusRequester() } 建立 FocusRequester 物件。
  2. 使用 focusRequester 修飾符將 FocusRequester 附加至目標可組合項。
  3. 將 focusProperties 修飾符套用至來源可組合項，並將 FocusRequester 指派給 next (適用於 Tab) 或 previous (適用於 Shift+Tab)。

val (first, second, third) = remember { FocusRequester.createRefs() }

Column {
    Button(
        onClick = { /* ... */ },
        modifier = Modifier
            .focusRequester(first)
            .focusProperties { next = third }
    ) {
        Text("First (Tab jumps to Third)")
    }
    Button(
        onClick = { /* ... */ },
        modifier = Modifier.focusRequester(second)
    ) {
        Text("Second")
    }
    Button(
        onClick = { /* ... */ },
        modifier = Modifier.focusRequester(third)
    ) {
        Text("Third")
    }
}

自訂二維遍歷順序

同樣地，您也可以在 focusProperties 中，將 FocusRequester 執行個體指派給 up、down、start、end、left 或 right，藉此覆寫二維焦點遍歷：

val (topButton, bottomButton) = remember { FocusRequester.createRefs() }

Button(
    onClick = { /* ... */ },
    modifier = Modifier
        .focusRequester(topButton)
        .focusProperties {
            down = bottomButton
            right = bottomButton
        }
) {
    Text("Top button")
}
Button(
    onClick = { /* ... */ },
    modifier = Modifier.focusRequester(bottomButton)
) {
    Text("Bottom button")
}

如要封鎖特定方向的焦點導覽 (例如在版面配置邊界)，請將 FocusRequester.Cancel 指派給該屬性 (例如 down = FocusRequester.Cancel)。如要明確保留系統在特定方向的預設周遊演算法，請指派 FocusRequester.Default。

上一頁
焦點目標
下一頁
將焦點移到文字欄位