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 saat digunakan.

Acara utama

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

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

Nilai lambda onKeyEvent yang ditampilkan menunjukkan apakah peristiwa tombol tertangani atau tidak. Tampilkan true jika aplikasi Anda menangani peristiwa utama, yang menghentikan penyebaran peristiwa.

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

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

Tombol pengubah

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

• isAltPressed
• isCtrlPressed
• isMetaPressed
• isShiftPressed

Jelaskan secara spesifik peristiwa utama yang ditangani aplikasi Anda. Cuplikan berikut memanggil fungsi doSomething() hanya jika pengguna hanya melepaskan kunci S. Jika pengguna menekan tombol pengubah, 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")
}

Spasi dan Enter peristiwa klik tombol

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:

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

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

Peristiwa utama yang tidak digunakan

Peristiwa utama yang tidak digunakan akan disebarkan dari komponen tempat peristiwa terjadi ke komponen luar yang melingkupi. Pada contoh di bawah, InnerComponent menggunakan peristiwa tombol saat tombol S dilepas, sehingga OuterComponent tidak menerima peristiwa utama 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 ingin mencegat peristiwa utama sebelum memicu tindakan default. Menambahkan pintasan khusus ke TextField adalah salah satu standar. 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 {i>keyboard<i} tanpa menambahkan karakter tab apa pun, menangani peristiwa utama sebelum memicu tindakan yang terkait dengan peristiwa utama, seperti dalam cuplikan. Lambda onKeyPreviewEvent() mencegat peristiwa utama dengan menampilkan true.

Komponen induk dapat menangkap peristiwa tombol yang terjadi pada turunannya. Dalam cuplikan berikut, fungsi previewSKey() dipanggil saat pengguna menekan tombol S, alih-alih 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 tidak dipicu saat pengguna menekan tombol Tab. Lambda onPreviewKeyEvent() dipanggil di komponen induk terlebih dahulu, maka onPreviewKeyEvent() dalam komponen turunan akan dipanggil. Anda dapat menerapkan pintasan keyboard di seluruh layar dengan memanfaatkan perilaku ini.

Referensi lainnya

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