焦點遍歷順序

使用者可以利用 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")
    }
}

自訂二維遍歷順序

同樣地，您可以將 FocusRequester 執行個體指派給 focusProperties 內的 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。

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