Dokumentacja interfejsu API reakcji haptycznych na Androida

W tej sekcji znajdziesz wprowadzenie do różnych interfejsów API wibracji dostępnych w Androidzie. Wyjaśniamy też, kiedy i jak sprawdzić, czy urządzenie obsługuje funkcje niezbędne do prawidłowego odtwarzania efektów haptycznych.

Efekty haptyczne można tworzyć na kilka sposobów. Przy wyborze jednego z nich warto wziąć pod uwagę zasady projektowania efektów haptycznych na Androidzie. W tabeli poniżej znajdziesz podsumowanie tych ogólnych atrybutów każdego podejścia:

  • Dostępność jest szczególnie ważna podczas planowania rezerwowego działania i musi być połączona ze sprawdzaniem obsługi poszczególnych urządzeń.
  • Wyraźne wibracje to czyste i wyraźne odczucia, które nie są tak uciążliwe dla użytkowników.
  • Zaawansowane wibracje są bardziej ekspresywne i często wymagają bardziej zaawansowanego sprzętu.
Powierzchnia interfejsu API Dostępność Wyczyść haptykę Rozbudowane reakcje haptyczne
HapticFeedbackConstants Android 1.5 lub nowszy
(stała)
Predefined VibrationEffect Android 10 lub nowszy
Kompozycja VibrationEffect Android 11 lub nowszy (w przypadku stałych)
Wibracje włączone/wyłączone, jednorazowe i falowe Android 1

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

Na tej stronie opisano też dodatkowe koncepcje dotyczące interfejsów API:

HapticFeedbackConstants

Klasa HapticFeedbackConstants udostępnia stałe oparte na działaniach, które umożliwiają aplikacjom dodawanie reakcji haptycznych spójnych w ramach działania urządzenia, zamiast stosowania przez każdą aplikację 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 po ustawieniu wartości false wyłącza wszystkie wywołania wibracji w widoku, w tym domyślne.Podstawowym powiązanym ustawieniem jest właściwość View.hapticFeedbackEnabled, która po ustawieniu wartości false wyłącza wszystkie wywołania wibracji w widoku, w tym domyślne. Metoda ta uwzględnia też ustawienie systemowe użytkownika dotyczące włączania reakcji dotykowej.

Jedynym aspektem zgodności jest poziom pakietu SDK dla konkretnej stałej działania.

Jeśli używasz właściwości HapticFeedbackConstants, nie musisz podawać zachowania rezerwowego.

Wykorzystanie: HapticsFeedbackConstants

Więcej informacji o używaniu HapticFeedbackConstants znajdziesz w artykule Dodawanie do zdarzeń informacji o odpowiedzi dotykowej.

Predefiniowany VibrationEffect

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

Zgodność i wymagania

Odtwarzanie dowolnego VibrationEffect wymaga uprawnienia VIBRATE w pliku manifestu aplikacji.

W przypadku korzystania z wstępnie zdefiniowanych stałych VibrationEffect nie trzeba podawać zachowania rezerwowego, ponieważ stałe, które nie mają implementacji zoptymalizowanej pod kątem urządzenia, wracają do standardowego zachowania rezerwowego platformy.

Interfejsy Vibrator.areEffectsSupported i Vibrator.areAllEffectsSupported służą do określania, czy istnieje implementacja zoptymalizowana pod kątem urządzenia. Wstępnie zdefiniowanych efektów można nadal używać bez zoptymalizowanej implementacji. W takim przypadku stosowana jest standardowa platforma zastępcza. W związku z tym te interfejsy APIareEffectsSupported są potrzebne tylko wtedy, gdy aplikacja ma uwzględniać, czy efekt jest zoptymalizowany pod kątem urządzenia.

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

Wartość UNKNOWN wskazuje, że interfejs API sprawdzania jest niedostępny, więc jest zwykle zwracana w przypadku wszystkich efektów lub żadnego z nich. Te urządzenia dynamicznie przełączają się na tryb awaryjny.

Wykorzystanie wstępnie zdefiniowanego VibrationEffect

Więcej informacji o używaniu predefiniowanego wzorca VibrationEffect znajdziesz w artykule Generowanie sygnałów dotykowych za pomocą predefiniowanego wzorca VibrationEffect.

Envelope VibrationEffect

Wibracje oparte na obwiedni umożliwiają precyzyjne sterowanie amplitudą i częstotliwością wibracji w czasie przez zdefiniowanie sekwencji punktów kontrolnych. Umożliwia to deweloperom tworzenie bogatszych i bardziej zniuansowanych wrażeń związanych z odpowiedzią dotykową. Te wibracje można tworzyć za pomocą klas BasicEnvelopeBuilder i WaveformEnvelopeBuilder.

Zgodność i wymagania

Aby odtwarzać efekty wibracji, aplikacja musi zadeklarować uprawnienie VIBRATE w pliku manifestu aplikacji.

Aby sprawdzić, czy efekt obwiedni jest obsługiwany, wywołaj funkcję Vibrator.areEnvelopeEffectsSupported().

Podstawowy kreator kopert

Aby zapewnić płynne i bezproblemowe wrażenia haptyczne, efekty obwiedni muszą zaczynać się i kończyć z intensywnością \( 0.0 \). Interfejs API wymusza to, ustawiając intensywność początkową na zero i zgłaszając wyjątek, jeśli intensywność końcowa nie jest zerowa. To ograniczenie zapobiega niepożądanym efektom dynamicznym w wibracjach spowodowanym przez nieciągłości w amplitudzie, które mogą negatywnie wpływać na percepcję haptyczną użytkownika.

Aby zapewnić spójne renderowanie efektu obwiedni na różnych urządzeniach, platforma wymaga, aby urządzenia obsługujące tę funkcję mogły obsługiwać minimalny czas 20 ms między punktami kontrolnymi i co najmniej 16 punktów dla efektów obwiedni.

Waveform Envelope Builder

Platforma nie modyfikuje żądanych wartości częstotliwości i amplitudy podanych przez dewelopera. Interfejs API ustala jednak amplitudę początkową na zero, aby zapewnić płynne przejścia.

Aby pomóc Ci zoptymalizować efekty obwiedni fali dźwiękowej w aplikacji i zapewnić zgodność z różnymi urządzeniami, Android udostępnia interfejsy API do sprawdzania ważnych funkcji urządzenia. Te metody dostarczają informacji o ograniczeniach urządzenia, takich jak maksymalny i minimalny czas przejścia między punktami kontrolnymi oraz maksymalna liczba punktów kontrolnych obsługiwanych w przypadku jednego efektu:

getMaxSize()
Pobiera maksymalną liczbę punktów kontrolnych obsługiwanych w przypadku efektu obwiedni.
getMinControlPointDurationMillis()
Pobiera minimalny obsługiwany czas trwania (w milisekundach) między dwoma punktami kontrolnymi w efekcie obwiedni.
getMaxControlPointDurationMillis()
Pobiera maksymalny obsługiwany czas trwania (w milisekundach) między dwoma punktami kontrolnymi w efekcie obwiedni.
getMaxDurationMillis()
Pobiera maksymalny czas trwania obsługiwany w przypadku efektu obwiedni (w milisekundach).

Jeśli efekt przekracza ograniczenia urządzenia, np. dopuszcza zbyt wiele punktów kontrolnych lub czas trwania przekracza maksymalną wartość, platforma automatycznie dostosowuje efekt do dopuszczalnych granic. Proces dostosowywania ma na celu jak największe zachowanie pierwotnego zamysłu i charakteru projektu.

Korzystanie z efektów wibracji koperty

Szczegółowe informacje o tworzeniu efektów kształtu fali obwiedni znajdziesz w artykule Tworzenie kształtu fali wibracji za pomocą obwiedni.

VibrationEffect kompozycja

Kompozycja VibrationEffect to efekt wibracji utworzony za pomocą interfejsu VibrationEffect.startComposition API. Ten interfejs API umożliwia tworzenie ekspresyjnych bogatych wibracji przez tworzenie sekwencji elementów pierwotnych z dostosowanymi opóźnieniami i intensywnościami. Zwróć jednak szczególną uwagę na to, czy urządzenie obsługuje łączone funkcje, aby uniknąć niespójności w działaniu.

Zgodność i wymagania

Odtwarzanie dowolnego VibrationEffect wymaga uprawnienia VIBRATE w pliku manifestu aplikacji.

Nie wszystkie urządzenia obsługują wszystkie funkcje interfejsu API kompozycji, dlatego ważne jest, aby upewnić się, że elementy podstawowe są dostępne.

Sprawdzanie obsługi podstawowych wzorców wibracji

Informacje o obsłudze poszczególnych typów można uzyskać za pomocą metody Vibrator.arePrimitivesSupported. Możesz też sprawdzić zestaw elementów pierwotnych, używając metody Vibrator.areAllPrimitivesSupported  – jest to równoważne z AND-owaniem obsługi poszczególnych elementów pierwotnych.

Korzystanie z VibrationEffect kompozycji

Szczegółowe informacje o korzystaniu z VibrationEffect kompozycji znajdziesz w artykule Tworzenie kompozycji wibracji.

Wibracje włączane i wyłączane, jednorazowe i o określonym kształcie

Najstarszą formą wibracji obsługiwaną na Androidzie są proste wzorce włączania i wyłączania wibratora z możliwością konfigurowania czasu trwania. Te interfejsy API zwykle nie są dobrze dopasowane do zasad projektowania haptyki, ponieważ mogą generować wibracje. Unikaj ich, chyba że nie masz innego wyjścia.

Najczęstszym zastosowaniem wibracji włączonych i wyłączonych są powiadomienia, w przypadku których zawsze pożądane są wibracje. Wibracje w formie fali umożliwiają też powtarzanie wzorca w nieskończoność, co jest przydatne np. w przypadku dzwonka.

Wzorzec jednorazowy to wibracja trwająca N milisekund.

Istnieją 2 rodzaje wzorców przebiegu:

  • Tylko czas Ten typ przebiegu to opis naprzemiennych okresów wyłączenia i włączenia. Czas zaczyna się od czasu wyłączenia. W związku z tym wzorce fal często zaczynają się od zera, co oznacza natychmiastowe rozpoczęcie wibracji.
  • Czas trwania i amplituda. Ten typ przebiegu ma dodatkową tablicę amplitud, które pasują do każdej wartości czasu, a nie do domyślnego włączania i wyłączania w pierwszej formie. Warto jednak sprawdzić, czy urządzenie obsługuje sterowanie amplitudą, aby mieć pewność, że można osiągnąć zamierzone skalowanie.

Zgodność i wymagania

Wibracje włączone/wyłączone to najstarsza forma wibracji, dlatego są obsługiwane na niemal wszystkich urządzeniach z wibratorem, o czym piszemy dalej na tej stronie.

Odtwarzanie połączeń VibrationEffect lub starszych połączeń vibrate wymaga uprawnienia VIBRATE w pliku manifestu aplikacji.

Jeśli używasz różnych wartości amplitudy w formie fali, zdecydowanie zalecamy sprawdzenie, czy urządzenie obsługuje sterowanie amplitudą.

Sprawdzanie obsługi sterowania amplitudą

Wartości amplitudy inne niż zero są zaokrąglane w górę do 100% na urządzeniach bez kontroli amplitudy, dlatego ważne jest, aby sprawdzić, czy jest ona obsługiwana za pomocą Vibrator.hasAmplitudeControl. Więcej informacji znajdziesz w sekcji kontrola amplitudy.

Zastanów się, czy efekt ma wystarczającą jakość bez kontroli amplitudy. Lepszym rozwiązaniem może być powrót do wibracji włączania i wyłączania zaprojektowanych w sposób jawny.

Używanie wibracji włączanych i wyłączanych

W nowszych wersjach pakietu SDK wszystkie tryby wibracji zostały połączone w jedną klasę VibrationEffect, w której te proste wibracje są tworzone za pomocą funkcji VibrationEffect.createOneshot lub VibrationEffect.createWaveform.

Interfejsy API powiadomień

Podczas dostosowywania powiadomień aplikacji możesz użyć jednego z tych interfejsów API, aby powiązać wzorzec z każdym kanałem powiadomień:

Wszystkie te formy mają podstawowy wzorzec fali włączania i wyłączania, jak opisano wcześniej. Pierwszy wpis to opóźnienie przed włączeniem wibratora.

Ogólne pojęcia

W przypadku opisanych powyżej interfejsów API obowiązuje kilka koncepcji.

Czy urządzenie ma wibrator?

Niepustą klasę Vibrator możesz uzyskać z context.getSystemService(Vibrator.class). Jeśli urządzenie nie ma wibratora, wywołania interfejsów API wibracji nie mają żadnego efektu, więc aplikacje nie muszą ograniczać wszystkich swoich haptycznych funkcji warunkiem. W razie potrzeby aplikacja może jednak wywołać funkcję hasVibrator(), aby sprawdzić, czy jest to prawdziwy wibrator (true), czy atrapa (false).

Czy użytkownik wyłączył haptyczne wibracje dotykowe?

Niektóre niestandardowe implementacje mogą wymagać ręcznego sprawdzenia, czy użytkownik całkowicie wyłączył ustawienie Odpowiedź dotykowa na Androidzie. W takim przypadku efekty odpowiedzi dotykowej powinny zostać wyłączone. To ustawienie można sprawdzić za pomocą klucza HAPTIC_FEEDBACK_ENABLED, gdzie wartość zero oznacza wyłączenie.

Atrybuty wibracji

Atrybuty wibracji (obecnie w formie AudioAttributes) mogą być podawane, aby informować system o celu wibracji. Jest to wymagane podczas inicjowania wibracji, gdy aplikacja działa w tle, ponieważ w takim przypadku obsługiwane są tylko haptyczne sygnały przyciągające uwagę.

Tworzenie obiektu AudioAttributes jest opisane w dokumentacji klasy. Należy go traktować jako wibrację, a nie dźwięk.

W większości przypadków typ treści to CONTENT_TYPE_SONIFICATION, a sposób użycia może mieć wartości takie jak USAGE_ASSISTANCE_SONIFICATION w przypadku reakcji na dotyk na pierwszym planie lub USAGE_ALARM w przypadku alarmu w tle. Flagi dźwiękowe nie mają wpływu na wibracje.

Regulacja amplitudy

Jeśli wibrator ma regulację amplitudy, może generować wibracje o różnym natężeniu. Jest to ważna funkcja, która umożliwia tworzenie bogatych wrażeń haptycznych, a także potencjalnie pozwala użytkownikom kontrolować domyślne intensywności haptyczne.

Obsługę sterowania amplitudą można sprawdzić, wywołując funkcję Vibrator.hasAmplitudeControl. Jeśli wibrator nie obsługuje amplitudy, wszystkie wartości amplitudy będą mapowane na włączone/wyłączone w zależności od tego, czy są zerowe/niezerowe. W związku z tym aplikacje korzystające z zaawansowanych wibracji o różnych amplitudach powinny rozważyć ich wyłączenie, jeśli urządzenie nie ma możliwości sterowania amplitudą.

Obsługa efektów koperty

Wibratory z efektami obwiedni obsługują i umożliwiają tworzenie bardziej dynamicznych i zniuansowanych wibracji, zapewniając dokładniejszą kontrolę nad intensywnością i ostrością, co przekłada się na bogatsze wrażenia dotykowe. Użyj Vibration.areEnvelopeEffectsSupported, aby sprawdzić, czy Twoje urządzenie obsługuje tę funkcję. W przeciwnym razie wibracje oparte na obwiedni są ignorowane.