Referensi API haptics Android

Bagian ini memberikan pengantar tentang berbagai API haptik yang tersedia di Android. Panduan ini juga membahas kapan dan cara memeriksa dukungan perangkat yang diperlukan untuk memastikan efek haptik Anda diputar seperti yang Anda inginkan.

Ada beberapa cara untuk membuat efek haptic, dan sebaiknya pertimbangkan prinsip desain haptik Android saat memilih di antara efek tersebut. Tabel berikut merangkum atribut tingkat tinggi dari setiap pendekatan:

  • Ketersediaan sangat penting saat merencanakan penggantian perilaku, dan perlu dikombinasikan dengan memeriksa dukungan setiap perangkat.
  • Haptik yang jelas adalah sensasi yang jernih dan bersih yang tidak terlalu mengganggu pengguna.
  • Haptik yang kaya memiliki ekspresi yang lebih besar dan sering kali memerlukan hardware yang lebih kaya fitur.
Platform API Ketersediaan Hapus haptic Haptik yang kaya
HapticFeedbackConstants Android 1.5+
(per konstanta)
VibrationEffect Standar Android 10+
Komposisi VibrationEffect Android 11+ (per konstanta)
Getaran aktif/nonaktif, one-shot, dan gelombang Android 1

Selain itu, API notifikasi, yang dijelaskan di halaman ini, memungkinkan Anda menyesuaikan efek haptic yang diputar untuk notifikasi yang masuk.

Konsep tambahan yang mencakup platform API juga dijelaskan di halaman ini:

HapticFeedbackConstants

Class HapticFeedbackConstants menyediakan konstanta berbasis tindakan untuk memungkinkan aplikasi menambahkan respons haptik yang konsisten di seluruh pengalaman perangkat, bukan setiap aplikasi memiliki efek yang berbeda untuk tindakan umum.

Kompatibilitas dan persyaratan

Menggunakan metode View.performHapticFeedback dengan konstanta ini tidak memerlukan izin khusus untuk aplikasi. Hal ini tunduk pada properti View.hapticFeedbackEnabled, yang jika disetel ke false akan menonaktifkan semua panggilan respons haptik pada tampilan, termasuk yang default.Setelan utama terkait properti View.hapticFeedbackEnabled, yang jika disetel ke false akan menonaktifkan semua panggilan respons haptik pada tampilan, termasuk yang default. Metode ini juga mengikuti setelan sistem pengguna untuk mengaktifkan masukan sentuh.

Satu-satunya pertimbangan kompatibilitas adalah tingkat SDK konstanta tertentu untuk tindakan.

Anda tidak perlu memberikan perilaku penggantian saat menggunakan HapticFeedbackConstants.

Penggunaan HapticsFeedbackConstants

Untuk mengetahui detail tentang penggunaan HapticFeedbackConstants, lihat Menambahkan respons haptik ke peristiwa.

VibrationEffect bawaan

Class VibrationEffect menyediakan beberapa konstanta yang telah ditetapkan seperti CLICK, TICK, dan DOUBLE_CLICK. Efek ini dapat dioptimalkan untuk perangkat.

Kompatibilitas dan persyaratan

Memutar VibrationEffect apa pun memerlukan izin VIBRATE dalam manifes aplikasi.

Tidak perlu memberikan perilaku penggantian saat menggunakan VibrationEffect yang telah ditentukan, karena konstanta yang tidak memiliki penerapan yang dioptimalkan untuk perangkat akan dikembalikan ke penggantian platform standar.

API Vibrator.areEffectsSupported dan Vibrator.areAllEffectsSupported adalah untuk menentukan apakah ada implementasi yang dioptimalkan untuk perangkat. Efek standar masih dapat digunakan tanpa implementasi yang dioptimalkan, dan menggunakan penggantian platform standar. Oleh karena itu, API areEffectsSupported ini hanya diperlukan jika aplikasi ingin mempertimbangkan apakah efek dioptimalkan untuk perangkat atau tidak.

Metode pemeriksaan efek dapat menampilkan salah satu dari tiga nilai:

Karena nilai UNKNOWN menunjukkan bahwa API pemeriksaan tidak tersedia, nilai ini biasanya ditampilkan untuk semua efek atau tidak sama sekali. Perangkat ini akan kembali secara dinamis.

Penggunaan VibrationEffect standar

Untuk mengetahui detail tentang penggunaan VibrationEffect yang telah ditentukan sebelumnya, lihat Menggunakan VibrationEffect yang telah ditentukan sebelumnya untuk menghasilkan respons haptik.

Komposisi VibrationEffect

Komposisi VibrationEffect adalah efek getaran yang dibuat menggunakan VibrationEffect.startComposition API. API ini memungkinkan haptik yang kaya yang ekspresif dengan membuat urutan primitif dengan keterlambatan dan intensitas yang disesuaikan. Namun, berhati-hatilah secara khusus untuk memastikan bahwa perangkat mendukung fitur yang digabungkan untuk menghindari pengalaman keseluruhan yang tidak konsisten.

Kompatibilitas dan persyaratan

Memutar VibrationEffect apa pun memerlukan izin VIBRATE dalam manifes aplikasi.

Tidak semua perangkat mendukung semua fitur API komposisi, dan penting untuk memastikan bahwa primitif tersedia.

Memeriksa dukungan primitif getaran

Dukungan per primitif dapat diambil menggunakan metode Vibrator.arePrimitivesSupported. Atau, sekumpulan primitif dapat diperiksa bersama-sama menggunakan metode Vibrator.areAllPrimitivesSupported - ini setara dengan AND dukungan per primitif.

Penggunaan Komposisi VibrationEffect

Untuk mengetahui detail tentang penggunaan komposisi VibrationEffect, lihat Membuat komposisi getaran.

Getaran aktif-nonaktif, one-shot, dan gelombang

Bentuk getaran tertua yang didukung di Android adalah pola aktif-nonaktif vibrator sederhana dengan durasi yang dapat dikonfigurasi. API ini biasanya tidak selaras dengan Prinsip desain haptic karena dapat menghasilkan haptic yang berdengung; hindari API ini kecuali sebagai upaya terakhir.

Kasus penggunaan yang paling umum untuk getaran aktif-nonaktif adalah notifikasi, yang, apa pun yang terjadi, beberapa getaran diinginkan. Getaran bentuk gelombang juga memungkinkan pola diulang tanpa batas secara unik, seperti yang mungkin Anda bayangkan untuk nada dering.

Pola one-shot mengacu pada getaran satu kali selama N milidetik.

Ada dua jenis pola bentuk gelombang:

  • Khusus pengaturan waktu. Jenis bentuk gelombang ini adalah deskripsi durasi alternatif yang dihabiskan untuk nonaktif, dan durasi yang dihabiskan untuk aktif. Pengaturan waktu dimulai dengan durasi yang dihabiskan. Akibatnya, pola bentuk gelombang sering kali dimulai dengan nilai nol untuk menunjukkan agar segera mulai bergetar.
  • Pengaturan waktu dan amplitudo. Jenis bentuk gelombang ini memiliki array amplitudo tambahan untuk dicocokkan dengan setiap angka pengaturan waktu, bukan tombol aktif-nonaktif implisit dari bentuk pertama. Namun, penting untuk memeriksa apakah perangkat mendukung kontrol amplitudo untuk memastikan bahwa penskalaan yang diinginkan dapat dicapai.

Kompatibilitas dan persyaratan

Karena getaran aktif-nonaktif adalah bentuk getaran tertua, getaran ini didukung di hampir semua perangkat dengan vibrator, seperti yang dijelaskan nanti di halaman ini.

Memutar panggilan VibrationEffect atau vibrate gaya lama, memerlukan izin VIBRATE dalam manifes aplikasi.

Saat menggunakan nilai amplitudo yang berbeda dalam bentuk gelombang, sebaiknya pastikan perangkat mendukung kontrol amplitudo.

Memeriksa dukungan kontrol amplitudo

Nilai amplitudo non-nol dibulatkan ke atas hingga 100% pada perangkat tanpa kontrol amplitudo, jadi penting untuk memeriksa apakah dukungan ada menggunakan Vibrator.hasAmplitudeControl. Lihat kontrol amplitudo untuk detail selengkapnya.

Anda harus mempertimbangkan dengan cermat apakah efek Anda memiliki kualitas yang memadai tanpa kontrol amplitudo. Kembali ke getaran aktif-nonaktif yang didesain secara eksplisit mungkin lebih baik.

Penggunaan getaran aktif-nonaktif

Di level SDK yang lebih baru, semua mode getaran digabungkan menjadi satu class VibrationEffect ekspresif, tempat getaran sederhana ini dibuat menggunakan VibrationEffect.createOneshot atau VibrationEffect.createWaveform.

Notification API

Saat menyesuaikan notifikasi aplikasi, Anda dapat menggunakan salah satu API berikut untuk mengaitkan pola dengan setiap saluran notifikasi:

Semua bentuk ini menggunakan pola bentuk gelombang aktif-nonaktif dasar, seperti yang dijelaskan sebelumnya, dengan entri pertama adalah penundaan sebelum mengaktifkan vibrator.

Konsep umum

Beberapa konsep berlaku di seluruh platform API yang dijelaskan di atas.

Apakah perangkat memiliki vibrator?

Anda bisa mendapatkan class Vibrator non-null dari context.getSystemService(Vibrator.class). Jika perangkat tidak memiliki vibrator, panggilan ke API getaran tidak akan berpengaruh, sehingga aplikasi tidak perlu mengontrol semua haptic-nya berdasarkan kondisi. Namun, jika diperlukan, aplikasi dapat memanggil hasVibrator() untuk menentukan apakah ini adalah vibrator sungguhan (true) atau stub (false).

Apakah pengguna telah menonaktifkan haptic sentuh?

Beberapa penerapan kustom mungkin memerlukan pemeriksaan manual apakah pengguna telah menonaktifkan sepenuhnya setelan Feedback sentuh Android, dalam hal ini efek respons sentuh harus disembunyikan. Setelan ini dapat dikueri menggunakan kunci HAPTIC_FEEDBACK_ENABLED, dengan nilai nol berarti dinonaktifkan.

Atribut getaran

Atribut getaran (saat ini dalam bentuk AudioAttributes) dapat disediakan untuk membantu memberi tahu sistem tentang tujuan getaran. Hal ini diperlukan saat memulai getaran saat aplikasi Anda berada di latar belakang, karena hanya haptik perhatian yang didukung untuk penggunaan latar belakang.

Pembuatan AudioAttributes tercakup dalam dokumentasi class-nya, dan harus dianggap sebagai getaran, bukan suara.

Sebagai panduan, dalam sebagian besar kasus, jenis konten adalah CONTENT_TYPE_SONIFICATION, dan penggunaannya mungkin berupa nilai seperti USAGE_ASSISTANCE_SONIFICATION untuk masukan sentuh di latar depan, atau USAGE_ALARM untuk alarm di latar belakang. Flag audio tidak berpengaruh pada getaran.

Kontrol amplitudo

Jika memiliki kontrol amplitudo, penggetar dapat memutar getaran dengan intensitas yang bervariasi. Ini adalah kemampuan penting untuk menghasilkan haptik yang kaya, serta berpotensi memungkinkan kontrol pengguna terhadap intensitas haptic default.

Dukungan kontrol amplitudo dapat diperiksa dengan memanggil Vibrator.hasAmplitudeControl. Jika vibrator tidak memiliki dukungan amplitudo, semua nilai amplitudo akan dipetakan ke nonaktif/aktif berdasarkan apakah nilai tersebut nol/bukan nol. Akibatnya, aplikasi yang menggunakan haptik yang kaya dengan amplitudo yang bervariasi harus mempertimbangkan untuk menonaktifkannya jika perangkat tidak memiliki kontrol amplitudo.