Urutan traversal fokus

Pengguna dapat memindahkan fokus keyboard di seluruh elemen UI menggunakan tombol Tab atau tombol arah (panah / D-pad):

• Tab / Shift+Tab: Memindahkan fokus ke depan atau ke belakang dalam urutan tampilan satu dimensi.
• Tombol arah: Memindahkan fokus secara dua dimensi (Atas, Bawah, Kiri, dan Kanan).

Traversal fokus satu dimensi

Dalam traversal fokus satu dimensi, tombol Tab memajukan fokus melalui UI berdasarkan urutan tampilan visual di layar.

Misalnya, saat empat tombol disusun dalam baris:

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

Menekan tombol Tab akan memindahkan fokus secara berurutan di seluruh tombol dalam urutan berikut:

1. Tombol ke-1 (atas-awal)
2. Tombol ke-2 (ujung atas)
3. Tombol ke-3 (bawah-awal)
4. Tombol ke-4 (ujung bawah)

Menekan Tab pada elemen terakhir akan kembali ke target fokus pertama. Menekan Shift+Tab akan memindahkan fokus dalam urutan terbalik.

Traversal fokus dua dimensi

Menekan tombol panah keyboard atau menggunakan D-pad akan memicu traversal fokus dua dimensi.

Dalam traversal dua dimensi, sistem memeriksa koordinat geometris dan batas spasial elemen UI untuk menentukan target terdekat ke arah yang diminta.

Traversal fokus dua dimensi tidak digabungkan. Jika pengguna menekan tombol Turun saat fokus pada elemen paling bawah, fokus akan tetap berada pada elemen tersebut, bukan melompat ke bagian atas layar.

Mereset penjelajahan fokus dengan klik pointer

Saat beralih antara keyboard fisik dan mouse atau touchpad di perangkat desktop atau perangkat layar besar:

• Hapus fokus saat mengetuk atau mengklik: Mengklik atau mengetuk ruang non-interaktif dengan mouse atau touchpad akan melepaskan fokus dari elemen aktif.
• Mulai ulang traversal: Setelah fokus dihapus, penekanan tombol Tab berikutnya akan memulai ulang traversal satu dimensi pada target fokus pertama dalam urutan tampilan visual, bukan melanjutkan dari elemen yang sebelumnya aktif. Hal ini sama dengan traversal fokus dua dimensi. Tombol arah memindahkan fokus keyboard ke target fokus terdekat dalam arah yang diminta.

Untuk mengetahui detail tentang cara menghapus fokus secara terprogram, lihat Memindahkan dan menghapus fokus.

Menyesuaikan urutan traversal fokus

Anda dapat menyesuaikan perilaku traversal dengan pengubah focusProperties.

Menyesuaikan urutan traversal satu dimensi

Untuk mengganti traversal satu dimensi, tentukan properti next atau previous dengan FocusRequester:

1. Buat objek FocusRequester dengan remember { FocusRequester() }.
2. Lampirkan FocusRequester ke composable target menggunakan pengubah focusRequester.
3. Terapkan pengubah focusProperties ke composable sumber dan tetapkan FocusRequester ke next (untuk Tab) atau previous (untuk 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")
    }
}
FocusTraversal.kt

Menyesuaikan urutan traversal dua dimensi

Demikian pula, Anda dapat mengganti traversal fokus dua dimensi dengan menetapkan instance FocusRequester ke up, down, start, end, left, atau right dalam focusProperties:

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")
}
FocusTraversal.kt

Untuk memblokir navigasi fokus ke arah tertentu (misalnya, pada batas tata letak), tetapkan FocusRequester.Cancel ke properti tersebut (misalnya, down = FocusRequester.Cancel). Untuk secara eksplisit mempertahankan algoritma traversal default sistem untuk arah tertentu, tetapkan FocusRequester.Default.