Referensi API haptics Android

Bagian ini memberikan pengantar berbagai API haptics yang tersedia di Android. Panduan ini juga membahas waktu dan cara memeriksa dukungan perangkat yang diperlukan untuk memastikan efek haptic diputar sesuai keinginan Anda.

Ada beberapa cara untuk membuat efek haptic, dan penting untuk mempertimbangkan prinsip desain haptic Android saat memilih di antaranya. Tabel berikut merangkum atribut tingkat tinggi dari setiap pendekatan:

  • Ketersediaan sangat penting saat merencanakan penggantian perilaku, dan perlu digabungkan dengan pemeriksaan dukungan perangkat individual.
  • Clear haptic adalah sensasi segar dan bersih yang tidak mengagetkan pengguna.
  • haptic kaya memiliki keekspresifan yang lebih baik dan sering kali memerlukan hardware yang lebih kaya fitur.
Platform API Ketersediaan Hapus haptic Haptic yang beragam
HapticFeedbackConstants Android 1.5+
(per konstanta)
VibrationEffect yang Telah Ditetapkan Android 10 dan yang lebih baru
Komposisi VibrationEffect Android 11+ (per konstanta)
Getaran aktif/nonaktif, satu kali, dan bentuk gelombang Android 1

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

Juga dijelaskan di halaman ini adalah konsep tambahan yang mencakup platform API:

  • Apakah perangkat memiliki vibrator?
  • Kontrol Amplitudo memungkinkan efek haptic yang lebih halus dan lebih kaya, tetapi tidak didukung di semua perangkat.
  • VibrationAttributes() membantu Anda mengklasifikasikan getaran berdasarkan penggunaannya, memastikan setelan pengguna yang sesuai akan diterapkan ke getaran tersebut, sehingga menghindari kejutan bagi pengguna.

HapticFeedbackConstants

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

Kompatibilitas dan persyaratan

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

Satu-satunya pertimbangan kompatibilitas adalah konstanta spesifik level SDK untuk tindakan tersebut.

Tidak perlu memberikan perilaku penggantian saat menggunakan HapticFeedbackConstants.

Penggunaan HapticsFeedbackConstants

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

VibrationEffect standar

Class VibrationEffect menyediakan beberapa konstanta yang telah ditentukan sebelumnya 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 implementasi yang dioptimalkan untuk perangkat akan dikembalikan ke penggantian platform standar.

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

Metode pemeriksaan efek dapat mengembalikan 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 kembali secara dinamis.

Penggunaan VibrationEffect yang telah ditentukan

Untuk mengetahui detail tentang penggunaan VibrationEffect standar, lihat Menggunakan VibrationEffect yang telah ditentukan untuk membuat respons haptic.

VibrationEffect komposisi

Komposisi VibrationEffect adalah efek getaran yang dibuat menggunakan VibrationEffect.startComposition API. API ini memungkinkan haptic kaya ekspresif dengan membuat urutan primitif dengan penundaan dan intensitas yang disesuaikan. Namun, Anda harus berhati-hati untuk memastikan bahwa perangkat mendukung penggabungan fitur 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 menggunakan metode Vibrator.areAllPrimitivesSupported - ini setara dengan AND-ing pada dukungan per-primitif.

Penggunaan Komposisi VibrationEffect

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

Getaran aktif-nonaktif, satu kali, dan bentuk gelombang

Bentuk getaran terlama yang didukung di Android adalah pola on-off vibrator sederhana dengan durasi yang dapat dikonfigurasi. API ini biasanya tidak selaras dengan prinsip desain Haptic karena dapat menghasilkan haptic yang ramai; menghindarinya, kecuali sebagai upaya terakhir.

Kasus penggunaan paling umum untuk getaran aktif saat nonaktif adalah notifikasi, yang memerlukan getaran. Getaran bentuk gelombang juga secara unik memungkinkan pola berulang tanpa batas, seperti yang dapat Anda bayangkan untuk nada dering.

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

Ada dua jenis pola bentuk gelombang:

  • Hanya pengaturan waktu. Jenis gelombang ini adalah deskripsi durasi selang waktu yang dihabiskan, dan durasi yang dihabiskan. Pengaturan waktu dimulai dengan durasi yang dihabiskan. Akibatnya, pola bentuk gelombang sering kali dimulai dengan nilai nol untuk menunjukkan bahwa getaran mulai segera mulai bergetar.
  • Waktu dan amplitudo. Jenis gelombang ini memiliki array amplitudo tambahan untuk dicocokkan dengan setiap angka waktu, bukan on-off 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 saat nonaktif adalah bentuk getaran terlama, getaran ini didukung di hampir semua perangkat yang memiliki vibrator, seperti yang akan dijelaskan nanti di halaman ini.

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

Jika menggunakan nilai amplitudo yang berbeda dalam bentuk gelombang, kami sangat menyarankan Anda agar perangkat mendukung kontrol amplitudo.

Memeriksa dukungan kontrol amplitudo

Nilai amplitudo yang bukan nol dibulatkan ke 100% di perangkat tanpa kontrol amplitudo, sehingga penting untuk memeriksa apakah dukungan tersedia menggunakan Vibrator.hasAmplitudeControl. Lihat kontrol amplitudo untuk detail selengkapnya.

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

Penggunaan getaran saat nonaktif

Di level SDK yang lebih baru, semua mode getaran digabungkan ke dalam 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 memiliki pola bentuk gelombang aktif dan 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 dapat memperoleh 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 membuka semua haptic pada suatu kondisi. Namun, jika diperlukan, aplikasi dapat memanggil hasVibrator() untuk menentukan apakah ini vibrator sungguhan (true) atau stub (false).

Apakah pengguna telah menonaktifkan haptic sentuh?

Beberapa implementasi kustom mungkin memerlukan pemeriksaan manual apakah pengguna telah menonaktifkan setelan Masukan sentuh Android sepenuhnya, dalam hal ini efek masukan 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 diberikan untuk membantu memberi tahu sistem tentang tujuan getaran. Hal ini diperlukan saat memulai getaran ketika aplikasi berada di latar belakang, karena hanya haptic atensi yang didukung untuk penggunaan latar belakang.

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

Sebagai panduan, pada umumnya, 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. Tanda audio tidak berpengaruh pada getaran.

Kontrol amplitudo

Jika vibrator memiliki kontrol amplitudo, vibrator dapat memutar getaran dengan berbagai intensitas. Hal ini adalah kemampuan penting untuk menghasilkan haptic yang kaya, serta berpotensi memungkinkan kontrol pengguna atas 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. Oleh karena itu, aplikasi yang menggunakan haptic kaya dengan amplitudo yang bervariasi harus mempertimbangkan untuk menonaktifkannya jika perangkat tidak memiliki kontrol amplitudo.