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 maju atau mundur 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-mulai)
2. Tombol ke-2 (kelas atas)
3. Tombol ke-3 (mulai-bawah)
4. Tombol ke-4 (ujung bawah)

Menekan Tab pada elemen terakhir akan mengembalikan fokus 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 dalam arah yang diminta.

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

Mereset penelusuran fokus dengan klik penunjuk

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

• Hapus fokus saat diketuk atau diklik: 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 ke 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 penelusuran satu dimensi

Untuk mengganti penelusuran 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, di batas tata letak), tetapkan FocusRequester.Cancel ke properti tersebut (misalnya, down = FocusRequester.Cancel). Untuk mempertahankan algoritma traversal default sistem secara eksplisit untuk arah tertentu, tetapkan FocusRequester.Default.