Menangani tindakan keyboard

Saat pengguna memberikan fokus ke komponen teks yang dapat diedit, seperti TextField, dan perangkat memiliki keyboard hardware yang terpasang, semua input akan ditangani oleh sistem. Anda dapat menyediakan pintasan keyboard dengan menangani peristiwa tombol.

Pintasan keyboard default

Pintasan keyboard berikut tersedia secara default.

Pintasan keyboard Tindakan Composable yang mendukung pintasan
Shift+Ctrl+Panah kiri/Panah kanan Memilih teks ke awal/akhir kata BasicTextField, TextField
Shift+Ctrl+Panah atas/Panah bawah Memilih teks ke awal/akhir paragraf BasicTextField, TextField
Shift+Alt+Panah atas/Panah bawah atau Shift+Meta+Panah kiri/Panah kanan Memilih teks ke awal/akhir teks BasicTextField, TextField
Shift+Panah kiri/Panah kanan Pilih karakter BasicTextField, TextField
Ctrl+A Pilih semua BasicTextField, TextField
Ctrl+C/Ctrl+X/Ctrl+V Menyalin/memotong/menempel BasicTextField, TextField
Ctrl+Z/Ctrl+Shift+Z Urungkan/ulangi BasicTextField, TextField
PageDown/PageUp Scroll LazyColumn, pengubah verticalScroll, pengubah scrollable

Acara utama

Di Compose, Anda dapat menangani setiap penekanan tombol dengan pengubah onKeyEvent. Pengubah menerima lambda yang dipanggil saat komponen yang diubah menerima peristiwa tombol. Peristiwa tombol dijelaskan sebagai objek KeyEvent. Anda bisa mendapatkan informasi setiap peristiwa tombol dengan merujuk ke objek dalam lambda yang diteruskan ke pengubah onKeyEvent.

Penekanan tombol mengirimkan dua peristiwa tombol. Satu dipicu saat pengguna menekan tombol; yang lain dipicu saat tombol dilepaskan. Anda dapat membedakan kedua peristiwa tombol dengan merujuk ke atribut type dari objek KeyEvent.

Nilai yang ditampilkan dari lambda onKeyEvent menunjukkan apakah peristiwa tombol ditangani atau tidak. Tampilkan true jika aplikasi Anda menangani peristiwa tombol, yang menghentikan penerapan peristiwa.

Cuplikan berikut menunjukkan cara memanggil fungsi doSomething() saat pengguna melepaskan tombol S pada komponen Box:

Box(
    modifier = Modifier
        .onKeyEvent {
            if (
                it.type == KeyEventType.KeyUp &&
                it.key == Key.S
            ) {
                doSomething()
                true
            } else {
                false
            }
        }
        .focusable()
) {
    Text("Press S key")
}

Tombol pengubah

Objek KeyEvent memiliki atribut berikut yang menunjukkan apakah tombol pengubah ditekan atau tidak:

Berikan informasi yang spesifik saat menjelaskan peristiwa utama yang ditangani aplikasi Anda. Cuplikan berikut memanggil fungsi doSomething() hanya jika pengguna melepaskan tombol S saja. Jika pengguna menekan tombol pengubah apa pun, seperti tombol Shift, aplikasi tidak akan memanggil fungsi.

Box(
    modifier = Modifier
        .focusable()
        .onKeyEvent {
            if (
                it.type == KeyEventType.KeyUp &&
                it.key == Key.S &&
                !it.isAltPressed &&
                !it.isCtrlPressed &&
                !it.isMetaPressed &&
                !it.isShiftPressed
            ) {
                doSomething()
                true
            } else {
                false
            }
        }
) {
    Text("Press S key with a modifier key")
}

Peristiwa klik tombol Spasi dan Enter

Tombol Spasi dan Enter juga memicu peristiwa klik. Misalnya, pengguna dapat mengalihkan (memutar atau menjeda) pemutaran media dengan tombol Spasi atau Enter dengan menangani peristiwa klik sebagai berikut:

MediaPlayer(modifier = Modifier.clickable { togglePausePlay() })

Pengubah clickable menangkap peristiwa tombol dan memanggil callback onClick() saat tombol Spasi atau Enter ditekan. Itulah sebabnya fungsi togglePausePlay() dipanggil dengan menekan tombol Spasi atau Enter di cuplikan.

Peristiwa utama yang tidak digunakan

Peristiwa tombol yang tidak digunakan akan disebarkan dari komponen tempat peristiwa terjadi ke komponen luar yang melingkupinya. Dalam contoh di bawah, InnerComponent menggunakan peristiwa tombol saat tombol S dilepaskan, sehingga OuterComponent tidak menerima peristiwa tombol apa pun yang dipicu dengan melepaskan tombol S. Itulah sebabnya fungsi actionB() tidak pernah dipanggil.

Peristiwa tombol lainnya di InnerComponent, seperti melepaskan tombol D, dapat ditangani oleh OuterComponent. Fungsi actionC() dipanggil karena peristiwa tombol untuk melepaskan tombol D disebarkan ke OuterComponent.

OuterComponent(
    modifier = Modifier.onKeyEvent {
        when {
            it.type == KeyEventType.KeyUp && it.key == Key.S -> {
                actionB() // This function is never called.
                true
            }

            it.type == KeyEventType.KeyUp && it.key == Key.D -> {
                actionC()
                true
            }

            else -> false
        }
    }
) {
    InnerComponent(
        modifier = Modifier.onKeyEvent {
            if (it.type == KeyEventType.KeyUp && it.key == Key.S) {
                actionA()
                true
            } else {
                false
            }
        }
    )
}

Pengubah onKeyPreviewEvent

Dalam beberapa kasus penggunaan, Anda mungkin ingin menangkap peristiwa tombol sebelum peristiwa tersebut memicu tindakan default. Menambahkan pintasan kustom ke TextField adalah salah satu contohnya. Cuplikan berikut memungkinkan pengguna berpindah ke komponen berikutnya yang dapat difokuskan dengan menekan tombol tab.

val focusManager = LocalFocusManager.current
var textFieldValue by remember { mutableStateOf(TextFieldValue()) }

TextField(
    textFieldValue,
    onValueChange = {
        textFieldValue = it
    },
    modifier = Modifier.onPreviewKeyEvent {
        if (it.type == KeyEventType.KeyUp && it.key == Key.Tab) {
            focusManager.moveFocus(FocusDirection.Next)
            true
        } else {
            false
        }
    }
)

Secara default, komponen TextField menambahkan karakter tab setiap kali pengguna menekan tombol Tab, meskipun peristiwa tombol ditangani dengan pengubah onKeyEvent. Untuk memindahkan fokus keyboard tanpa menambahkan karakter tab, tangani peristiwa tombol sebelum memicu tindakan yang terkait dengan peristiwa tombol, seperti dalam cuplikan. Lambda onKeyPreviewEvent() menangkap peristiwa tombol dengan menampilkan true.

Komponen induk dapat menangkap peristiwa tombol yang terjadi pada turunannya. Dalam cuplikan berikut, fungsi previewSKey() dipanggil saat pengguna menekan tombol S, bukan memanggil fungsi actionForPreview().

Column(
    modifier = Modifier.onPreviewKeyEvent {
        if (it.key == Key.S) {
            previewSKey()
            true
        } else {
            false
        }
    }
) {
    Box(
        modifier = Modifier
            .focusable()
            .onPreviewKeyEvent {
                actionForPreview(it)
                false
            }
            .onKeyEvent {
                actionForKeyEvent(it)
                true
            }
    ) {
        Text("Press any key")
    }
}

Lambda onPreviewKeyEvent() untuk komponen Box juga tidak dipicu saat pengguna menekan tombol Tab. Lambda onPreviewKeyEvent() dipanggil pada komponen induk terlebih dahulu, lalu onPreviewKeyEvent() di komponen turunan dipanggil. Anda dapat menerapkan pintasan keyboard di seluruh layar dengan memanfaatkan perilaku ini.

Referensi lainnya

  • Bantuan Pintasan Keyboard: Layar sistem yang memungkinkan pengguna menelusuri pintasan keyboard yang ditawarkan aplikasi Anda.
Berikutnya
Keyboard Shortcuts Helper