Dokumentacja interfejsu API reakcji haptycznych na Androida

W tej sekcji omawiamy różne interfejsy API dotykowe dostępne na Androidzie. Dowiesz się z niego również, kiedy i jak sprawdzić, czy urządzenie obsługuje odpowiednie funkcje haptyczne.

Jest kilka sposobów na wywoływanie efektów haptycznych, a podczas wyboru warto wziąć pod uwagę zasady projektowania reakcji na dotyk Androida. W tabeli poniżej znajdziesz podsumowanie atrybutów tych ogólnych metod:

  • Dostępność jest szczególnie ważna przy planowaniu działania awaryjnego. Należy ją łączyć ze sprawdzaniem obsługi poszczególnych urządzeń.
  • Czyste czujniki haptyczne to ostre i czyste wrażenia, które są mniej rażące dla użytkowników.
  • Bogate czujniki haptyczne zapewniają większą ekspresję i często wymagają bardziej rozbudowanego sprzętu.
Interfejs API Dostępność Wyczyść czujnik haptyczny Bogata reakcja haptyczna
Stałe opinie Haaptic Android 1.5+
(na stałą)
Wstępnie zdefiniowany efekt wibracji Android 10 i nowsze
Kompozycja efektu wibracji Android 11 lub nowszy (za stałą)
Włączanie i wyłączanie, wibracje typu „one-shot” i sygnały fali Android 1

Dodatkowo opisane na tej stronie interfejsy API powiadomień umożliwiają dostosowanie efektów haptycznych odtwarzanych w przypadku przychodzących powiadomień.

Na tej stronie znajdują się też dodatkowe pojęcia dotyczące platform API:

HapticFeedbackConstants

Klasa HapticFeedbackConstants udostępnia stałe oparte na działaniu, co umożliwia aplikacjom dodawanie reakcji na dotyk, które są spójne dla całego urządzenia, dzięki czemu poszczególne aplikacje nie mogą mieć różnych efektów w przypadku typowych działań.

Zgodność i wymagania

Użycie metody View.performHapticFeedback z tymi stałymi nie wymaga żadnych specjalnych uprawnień aplikacji. Podlega ona właściwości View.hapticFeedbackEnabled, która – jeśli ma wartość false – wyłącza wszystkie wywołania reakcji na dotyk w danym widoku, w tym także te domyślne.Główne ustawienie właściwości View.hapticFeedbackEnabled, które jest ustawione na false, wyłącza wszystkie wywołania reakcji na dotyk w danym widoku, w tym wywołania domyślne. Ta metoda uwzględnia też ustawienie systemowe użytkownika dotyczące włączania reagowania na dotyk.

Jedyną kwestią dotyczącą zgodności jest poziom SDK konkretnej stałej działania.

Gdy używasz HapticFeedbackConstants, nie musisz stosować działania awaryjnego.

Wykorzystanie: HapticsFeedbackConstants

Więcej informacji o korzystaniu z funkcji HapticFeedbackConstants znajdziesz w artykule Dodawanie reakcji haptycznych do wydarzeń.

Wstępnie zdefiniowany VibrationEffect

Klasa VibrationEffect zawiera kilka wstępnie zdefiniowanych stałych, takich jak CLICK, TICK i DOUBLE_CLICK. Te efekty mogą być zoptymalizowane pod kątem urządzenia.

Zgodność i wymagania

Odtworzenie dowolnego elementu VibrationEffect wymaga uprawnienia VIBRATE w manifeście aplikacji.

Gdy używasz wstępnie zdefiniowanego parametru VibrationEffect, nie musisz podawać działania awaryjnego, ponieważ stałe bez implementacji zoptymalizowanej pod kątem urządzenia przywracają standardową wersję zastępczą platformy.

Interfejsy API Vibrator.areEffectsSupported i Vibrator.areAllEffectsSupported służą do określania, czy istnieje implementacja zoptymalizowana pod kątem urządzenia. Wstępnie zdefiniowanych efektów nadal można używać bez zoptymalizowanej implementacji i korzystamy ze standardowej kreacji zastępczej platformy. Dlatego te interfejsy API areEffectsSupported są potrzebne tylko wtedy, gdy aplikacja chce wziąć pod uwagę, czy efekt jest zoptymalizowany pod kątem urządzenia, czy nie.

Metody sprawdzania efektów mogą zwracać jedną z 3 wartości:

Wartość UNKNOWN wskazuje, że interfejs API sprawdzający jest niedostępny. Dlatego zwykle jest zwracany w przypadku wszystkich efektów lub nie zwraca żadnego z nich. Te urządzenia dynamicznie korzystają z powrotu.

Użycie wstępnie zdefiniowanej listy VibrationEffect

Więcej informacji o używaniu wstępnie zdefiniowanego elementu VibrationEffect znajdziesz w artykule Używanie wstępnie zdefiniowanego elementu VibrationEffect do generowania reakcji haptycznych.

VibrationEffect kompozycja

Kompozycja VibrationEffect to efekt wibracji utworzony za pomocą interfejsu API VibrationEffect.startComposition. Ten interfejs API umożliwia ekspresję dotykową reakcją na dotyk przez utworzenie sekwencji elementów podstawowych o niestandardowych opóźnieniach i intensywności. Zachowaj jednak szczególną ostrożność, by mieć pewność, że urządzenie obsługuje łączone funkcje, co pozwoli uniknąć niespójności.

Zgodność i wymagania

Odtworzenie dowolnego elementu VibrationEffect wymaga uprawnienia VIBRATE w manifeście aplikacji.

Nie wszystkie urządzenia obsługują wszystkie funkcje interfejsu Compose API. Ważne jest też, aby mieć dostęp do podstawowych elementów.

Sprawdź, czy obsługuje ona podstawowe wibracje

Obsługa jednostek podstawowych można pobrać za pomocą metody Vibrator.arePrimitivesSupported. Zbiór podstawowych elementów można też sprawdzić razem przy użyciu metody Vibrator.areAllPrimitivesSupported – jest to odpowiednik AND obsługi na poziomie prymitywnym.

Wykorzystanie VibrationEffect kompozycji

Szczegółowe informacje na temat używania kompozycji VibrationEffect znajdziesz w artykule Tworzenie kompozycji z wibracjami.

Wibracje włączone, jednostrzałowe oraz fale

Najstarszą formą wibracji obsługiwanej na Androidzie są proste, włączane i wyłączane wibracje o konfigurowanym czasie trwania. Te interfejsy API zazwyczaj nie są dobrze zgodne z zasadami projektowania haptycznego, ponieważ mogą generować wywołania reakcji haptycznej. Należy ich unikać z wyjątkiem ostateczności.

Najczęściej przydaje się to w przypadku powiadomień, w których pożądana jest pewna wibracja. Wibracje fali również umożliwiają powtarzanie wzorca w nieskończoność, jak można to wyobrazić sobie w przypadku dzwonka.

Wzór jednorazowy oznacza wibrację raz przez N milisekund.

Istnieją 2 rodzaje wzorców fal:

  • Tylko terminy. Ten typ fali to opis naprzemiennych okresów czasu trwania fali oraz czasów trwania. Czasy zaczynają się od wyznaczonego czasu trwania. W związku z tym wzorce fali często zaczynają się od wartości 0, co oznacza, że natychmiast zaczynają wibrować.
  • Czasy i amplitudy. Ten typ fali ma dodatkową tablicę amplitudy pasującej do poszczególnych wartości czasowych, a nie niejawne włączanie pierwszej postaci. Należy jednak sprawdzić, czy urządzenie obsługuje kontrolę amplitudy, co pozwoli uzyskać zamierzone skalowanie.

Zgodność i wymagania

Wibracje przy włączaniu są najstarszą formą wibracji, dlatego są obsługiwane praktycznie na wszystkich urządzeniach wyposażonych w wibracje, co opisaliśmy w dalszej części tej strony.

Odtwarzanie dowolnych wywołań funkcji VibrationEffect lub starszych stylów vibrate wymaga uprawnienia VIBRATE w pliku manifestu aplikacji.

Jeśli w fali używa się różnych wartości amplitudy, zdecydowanie zalecamy korzystanie z regulacji amplitudy urządzenia.

Sprawdź, czy obsługuje sterowanie amplitudą

Wartości amplitudy inne niż 0 są zaokrąglane do 100% na urządzeniach bez kontroli amplitudy, dlatego ważne jest, aby sprawdzić, czy dostępna jest obsługa za pomocą parametru Vibrator.hasAmplitudeControl. Więcej informacji znajdziesz w sekcji dotyczącej regulacji amplitudy.

Zastanów się dobrze, czy efekt ma wystarczającą jakość bez kontroli amplitudy. Lepiej wrócić do specjalnie zaprojektowanej wibracji przytłumionej.

Korzystanie z wibracji przy włączaniem

Na nowszych poziomach pakietów SDK wszystkie tryby wibracji były skonsolidowane w jedną klasę VibrationEffect, w której te proste wibracje są tworzone za pomocą VibrationEffect.createOneshot lub VibrationEffect.createWaveform.

Interfejsy API powiadomień

Podczas dostosowywania powiadomień z aplikacji możesz powiązać wzorce z każdym kanałem za pomocą jednego z tych interfejsów API:

Wszystkie te formy przyjmują podstawowy wzorzec fali przy braku fali, jak opisano wcześniej, gdzie pierwszy zapis to opóźnienie przed włączeniem wibracji.

Pojęcia ogólne

W podanych wyżej platformach API występuje kilka koncepcji.

Czy urządzenie ma wibracje?

Możesz uzyskać niepustą klasę Vibrator z context.getSystemService(Vibrator.class). Jeśli urządzenie nie ma wibracji, wywołania interfejsów API wibracji nie dają żadnego efektu, więc aplikacje nie muszą blokować wszystkich reakcji haptycznych w określonych sytuacjach. W razie potrzeby aplikacja może jednak wywołać metodę hasVibrator(), by ustalić, czy jest to prawdziwy wibrator (true) czy fragment kodu (false).

Czy użytkownik wyłączył reagowanie na dotyk?

Niektóre implementacje niestandardowe mogą wymagać ręcznego sprawdzenia, czy użytkownik całkowicie wyłączył ustawienie Sygnały dotykowe na Androidzie. W takim przypadku efekty reakcji na dotyk należy pominąć. To ustawienie można wykonywać przy użyciu klucza HAPTIC_FEEDBACK_ENABLED, gdzie wartość 0 oznacza wyłączoną.

Atrybuty wibracji

Można podać atrybuty wibracji (obecnie w formacie AudioAttributes), aby poinformować system o celu wibracji. Jest to wymagane przy inicjowaniu wibracji, gdy aplikacja działa w tle, ponieważ w tle obsługiwane są tylko czujniki haptyczne.

Tworzenie obiektu AudioAttributes zostało opisane w dokumentacji jego klasy i należy go traktować jako wibracje, a nie jako dźwięk.

Należy pamiętać, że w większości przypadków typ treści to CONTENT_TYPE_SONIFICATION, a użycie może mieć takie wartości jak USAGE_ASSISTANCE_SONIFICATION w przypadku potwierdzenia dotyku na pierwszym planie lub USAGE_ALARM w przypadku alarmu w tle. Sygnały dźwiękowe nie mają wpływu na wibracje.

Kontrola amplitudy

Jeśli wibrator ma regulację amplitudy, może odtwarzać wibracje o różnej intensywności. Jest to ważna zdolność do wytwarzania czujników haptycznych, która umożliwia też użytkownikom kontrolowanie domyślnych intensywności reakcji na dotyk.

Obsługę sterowania amplitudą można sprawdzić, wywołując metodę Vibrator.hasAmplitudeControl. Jeśli wibrator nie obsługuje amplitudy, wszystkie wartości amplitudy zostaną zmapowane na wyłączone lub włączone w zależności od tego, czy mają wartość 0 lub inną. Dlatego aplikacje używające sygnałów haptycznych o różnej amplitudzie powinny rozważyć ich wyłączenie, jeśli urządzenie nie ma kontroli amplitudy.