Gestur satu tangan dengan Compose

Mulai Wear OS 7 (API level 37), framework gestur satu tangan, beserta API yang merupakan bagian dari Compose untuk Wear OS, memungkinkan pengguna berinteraksi dengan aplikasi Anda tanpa sentuhan.

Meskipun awalnya didukung di perangkat Pixel Watch (Pixel Watch 3 dan yang lebih baru), framework ini tersedia untuk semua OEM. Dengan mengadopsi API ini, dukungan gestur aplikasi Anda akan otomatis diskalakan di seluruh ekosistem seiring dengan perluasan dukungan hardware.

Untuk membantu pengguna menemukan gestur yang tersedia tanpa membuat UI berantakan, framework Wear OS menyediakan indikator gestur animasi. Petunjuk visual ini menyoroti tempat gestur dapat dilakukan, sementara sistem secara otomatis mengelola irama tampilan dan frekuensi nonaktifnya sesuai dengan preferensi pengguna.

Gestur dan tindakan yang didukung

Framework gestur Wear OS mendukung dua jenis gestur:

  • Tindakan utama (cubit dua kali): Dipetakan ke tindakan utama di layar, seperti menjawab panggilan atau mengalihkan pemutaran media.
  • Tindakan tutup (Putar pergelangan tangan): Dipetakan ke navigasi mundur, menutup dialog, atau membatalkan perintah.

Mengonfigurasi gestur di Compose

Meskipun API gestur satu tangan dapat meningkatkan UI Anda, penting untuk diingat bahwa beberapa hardware dan OEM tidak mendukung gestur ini. Jika API mendeteksi bahwa aplikasi Anda berjalan di salah satu perangkat yang tidak didukung ini, library akan otomatis melakukan no-op tanpa memengaruhi interaksi sentuh standar.

Seperti perilaku Compose standar, Anda mengaktifkan gestur satu tangan pada elemen UI menggunakan pengubah. Anda mengonfigurasi gestur aplikasi sesuai dengan tindakan yang akan dilakukan—baik utama maupun tutup—dan gestureId untuk berkoordinasi dengan preferensi pengguna tingkat sistem, seperti irama tampilan petunjuk dan frekuensi nonaktif. Anda menyatakan konfigurasi ini dengan membuat objek OneHandedGestureConfiguration; sebaiknya gunakan fungsi rememberOneHandedGestureConfiguration untuk membuatnya. OneHandedGestureConfiguration juga merupakan tempat Anda dapat memberikan prioritas gestur.

Fungsi rememberOneHandedGestureConfiguration melacak histori interaksi pengguna di seluruh rekomposisi tanpa mengekspos status aplikasi. Setelah membuat konfigurasi, aplikasi Anda harus meneruskan konfigurasi ke Modifier.oneHandedGesture pada composable interaktif.

Untuk membantu pengguna menemukan gestur yang tersedia, library menyediakan metode OneHandedGestureClickIndicator. Metode ini bertindak sebagai wrapper yang menggantikan konten dasarnya untuk menunjukkan kepada pengguna bahwa tindakan gestur tersedia.

Komponen interaktif

Untuk mengaktifkan gestur pada kontrol interaktif seperti tombol, buat konfigurasi yang menentukan OneHandedGestureAction.Primary dan terapkan pengubah oneHandedGesture. Teruskan MutableInteractionSource yang sama ke kontrol dan pengubah sehingga peristiwa gestur memancarkan masukan visual ke kontrol.

Untuk mengaktifkan indikator gestur, buat dan ingat instance OneHandedGestureClickIndicatorState. Kemudian, untuk memicu masukan visual, panggil showIndicator dalam callback onGestureAvailable yang disediakan oleh pengubah oneHandedGesture, yang memberi sinyal kepada sistem bahwa peristiwa indikasi telah terjadi. Setelah dipanggil, komponen akan mengganti konten normalnya dengan animasi gestur untuk sementara.

var isPlaying by remember { mutableStateOf(false) }
val onClick = { isPlaying = !isPlaying }

val gestureConfig = rememberOneHandedGestureConfiguration(
    action = OneHandedGestureAction.Primary
)
val indicatorState = remember { OneHandedGestureClickIndicatorState() }
val coroutineScope = rememberCoroutineScope()
val interactionSource = remember { MutableInteractionSource() }

Button(
    onClick = onClick,
    interactionSource = interactionSource,
    modifier = Modifier
        .fillMaxWidth()
        .oneHandedGesture(
            gestureConfiguration = gestureConfig,
            interactionSource = interactionSource,
            onGestureLabel = if (isPlaying) "pause" else "play",
            onGestureAvailable = { coroutineScope.launch { indicatorState.showIndicator() } },
            onGesture = onClick
        )
) {
    OneHandedGestureClickIndicator(
        gestureConfiguration = gestureConfig,
        state = indicatorState
    ) {
        Text(if (isPlaying) "Pause" else "Play", modifier = Modifier.fillMaxWidth())
    }
}

Container yang dapat di-scroll

Untuk layar atau daftar yang dapat di-scroll, buat konfigurasi yang menentukan OneHandedGestureAction.Primary dan terapkan pengubah oneHandedGesture ke container Anda, dengan memanggil helper scroll seperti scrollDown.

Untuk memberikan masukan visual untuk tindakan scroll, Anda dapat menggunakan OneHandedGestureScrollIndicator. Komponen ini berfungsi sebagai indikator scroll standar yang menampilkan posisi scroll, tetapi juga dapat menunjukkan bahwa gestur scroll tersedia untuk pengguna. Indikator ini biasanya diteruskan ke slot scrollIndicator dari ScreenScaffold dan digabungkan dengan status container yang dapat di-scroll, seperti TransformingLazyColumn. Indikator ini juga mengamati OneHandedGestureScrollIndicatorState untuk mengelola transisi visualnya.

Untuk memicu masukan visual, panggil showIndicator pada status ini—biasanya di dalam callback onGestureAvailable dari pengubah oneHandedGesture. Setelah dipicu, indikator akan mengganti status visual standarnya dengan urutan animasi gestur untuk sementara guna memberi tahu pengguna.

val scrollState = rememberTransformingLazyColumnState()
val gestureConfig = rememberOneHandedGestureConfiguration(
    action = OneHandedGestureAction.Primary,
    priority = OneHandedGesturePriority.Scrollable
)
val indicatorState = remember(gestureConfig) { OneHandedGestureScrollIndicatorState() }
val coroutineScope = rememberCoroutineScope()

ScreenScaffold(
    scrollState = scrollState,
    scrollIndicator = {
        OneHandedGestureScrollIndicator(
            gestureConfiguration = gestureConfig,
            indicatorState = indicatorState,
            scrollState = scrollState,
            modifier = Modifier.align(Alignment.CenterEnd)
        )
    }
) { contentPadding ->
    TransformingLazyColumn(
        state = scrollState,
        contentPadding = contentPadding,
        modifier = Modifier
            .fillMaxSize()
            .oneHandedGesture(
                gestureConfiguration = gestureConfig,
                onGestureLabel = "scroll",
                onGestureAvailable = {
                    coroutineScope.launch { indicatorState.showIndicator() }
                },
                onGesture = { OneHandedGestureDefaults.scrollDown(scrollState) }
            )
    ) {
        items(10) { index ->
            Text("Item $index", modifier = Modifier.padding(8.dp))
        }
    }
}

Menggabungkan beberapa gestur

Anda dapat mengonfigurasi gestur scroll dan gestur klik dengan tindakan utama yang sama dengan menambahkan gesturePriority ke objek OneHandedGestureConfiguration:

  • OneHandedGesturePriority.Clickable (tertinggi): Tetapkan ke kontrol interaktif—seperti kontrol dengan jenis Button atau Card—agar kontrol tersebut menangkap gestur saat terlihat di layar.
  • OneHandedGesturePriority.Scrollable (sedang): Tetapkan ke container yang dapat di-scroll atau di-page sehingga container tersebut dapat di-scroll saat tidak ada kontrol yang dapat diklik.
  • OneHandedGesturePriority.Unspecified (terendah): Prioritas yang tidak ditetapkan. Ini adalah nilai default untuk gestur yang tidak memiliki priority yang ditetapkan.

Dengan menetapkan priority = OneHandedGesturePriority.Clickable secara eksplisit pada tombol dalam dan priority = OneHandedGesturePriority.Scrollable pada daftar induknya, sistem dapat menampilkan perilaku prioritas gestur ini. Saat pengguna memicu tindakan utama dengan gestur satu tangan, tindakan tersebut akan men-scroll daftar ke bawah terlebih dahulu hingga tombol terlihat. Kemudian, tindakan tersebut akan menangkap tindakan klik tombol.

Menguji dan men-debug gestur dengan ADB

Anda dapat menguji gestur satu tangan di perangkat fisik atau emulator tanpa melakukan gerakan pergelangan tangan fisik menggunakan Android Debug Bridge (adb) dan layanan sistem IWearGestureService.

Mengaktifkan simulasi gestur

  1. Pastikan perangkat Wear OS Anda menjalankan Wear OS 7 (level API 37) dan yang lebih tinggi.
  2. Jika menguji di perangkat fisik yang tidak berada di pergelangan tangan atau di pengisi daya, ganti status sensor di luar tubuh sehingga perangkat tetap aktif:
adb shell cmd sensorservice set-off-body-state 0

Memicu peristiwa gestur menggunakan ADB

Untuk menyimulasikan gestur Pinch Ganda (yang merupakan tindakan Primary di smartwatch Pixel), jalankan perintah shell ADB berikut:

adb shell cmd IWearGestureService gesture 1

Untuk menyimulasikan gestur Putar Pergelangan Tangan (yang merupakan tindakan Dismiss di smartwatch Pixel), jalankan perintah shell ADB berikut:

adb shell cmd IWearGestureService gesture 2

Mereset pelacakan petunjuk gestur

Sistem melacak histori interaksi pengguna dan menampilkan petunjuk gestur mengambang berdasarkan setelan irama global (seperti Selalu atau Harian). Saat men-debug indikator gestur aplikasi, reset histori pelacakan ini agar petunjuk muncul lagi untuk paket Anda:

adb shell cmd IWearGestureService hint clear <your_package_name>

Untuk mereset status sensor di luar tubuh setelah selesai menguji:

adb shell cmd sensorservice reset-off-body-state

Referensi lainnya

Untuk panduan desain tentang kapan dan tempat menggunakan gestur satu tangan, lihat Gestur satu tangan.