Dokumentacja interfejsu API reakcji haptycznych na Androida

W tym dokumencie przedstawiamy różne interfejsy API haptyki dostępne w Androidzie. Wyjaśniamy, jak tworzyć różne efekty haptyczne i jak sprawdzać, czy urządzenie obsługuje niezbędne funkcje. keywords_public: > Android, haptyka, interfejsy API, wibracje, HapticFeedbackConstants, VibrationEffect, haptyka kopertowa, haptyczne informacje zwrotne, powiadomienia, kontrola amplitudy

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

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, a także musi być połączona ze sprawdzaniem obsługi na poszczególnych urządzeniach.
  • Wyraźne wibracje to czyste i wyraźne odczucia, które nie są tak uciążliwe dla użytkowników.
  • Zaawansowane wibracje są bardziej ekspresyjne 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
VibrationEffect kompozycja (preferowana) Android 16+ (IV kwartał 2026 r.)
VibrationEffect kompozycja elementów podstawowych 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, które obejmują interfejsy API:

  • Czy urządzenie ma wibrator?
  • Kontrola amplitudy umożliwia płynniejsze i bogatsze efekty haptyczne, ale nie jest obsługiwana przez wszystkie urządzenia.
  • VibrationAttributes() pomaga klasyfikować wibracje na podstawie sposobu użycia, dzięki czemu można zastosować odpowiednie ustawienia użytkownika, aby uniknąć zaskoczenia.

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żywanie 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 reakcji haptycznej w widoku, w tym domyślne.Głównym powiązanym ustawieniem jest właściwość View.hapticFeedbackEnabled, która po ustawieniu wartości false wyłącza wszystkie wywołania reakcji haptycznej w widoku, w tym domyślne. Metoda ta uwzględnia też ustawienie systemowe użytkownika dotyczące włączania reakcji dotykowej.

Jedynym aspektem, który należy wziąć pod uwagę, jest poziom pakietu SDK dla konkretnej stałej działania.

Jeśli używasz funkcji HapticFeedbackConstants, nie musisz podawać zachowania rezerwowego.

Wykorzystanie: HapticsFeedbackConstants

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

Predefiniowany VibrationEffect

Klasa VibrationEffect udostępnia 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

Odtwarzanie dowolnego VibrationEffect wymaga uprawnienia VIBRATE w pliku manifestu aplikacji.

W przypadku korzystania z wstępnie zdefiniowanych stałych VibrationEffect nie trzeba podawać zachowania zastępczego, ponieważ stałe, które nie mają implementacji zoptymalizowanej pod kątem urządzenia, wracają do standardowego zachowania zastępczego 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, a w takim przypadku stosowana jest standardowa platforma zastępcza. W związku z tym teareEffectsSupported interfejsy API 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, dlatego zwykle jest zwracany w przypadku wszystkich efektów lub żadnego z nich. Te urządzenia dynamicznie przełączają się na inne ustawienia.

Użycie wstępnie zdefiniowanego VibrationEffect

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

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 reakcją haptyczną. 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 efekty obwiedni są obsługiwane, zadzwoń pod numer Vibrator.areEnvelopeEffectsSupported().

Kreator podstawowych 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.

Kreator obwiedni fali

Platforma nie modyfikuje 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 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 maksimum, platforma automatycznie dostosowuje efekt do dopuszczalnych granic. Ten proces dostosowywania ma na celu jak największe zachowanie pierwotnego charakteru projektu.

Korzystanie z efektów wibracji Envelope

Szczegółowe informacje o tworzeniu efektów kształtu fali obwiedni znajdziesz w artykule Tworzenie kształtu fali wibracji z obwiedniami.

VibrationEffect kompozycja

Od Androida 16 (26Q4) preferowanym interfejsem API do tworzenia bogatych, wyrazistych efektów haptycznych przez sekwencjonowanie wielu elementów haptycznych wzdłuż zaprojektowanej osi czasu jest VibrationEffect.Builder. Zastępuje VibrationEffect.Composition, ponieważ oferuje planowanie oparte na osi czasu, atomowe hermetyzowanie, obsługę zdarzeń mieszanych (łączących ustawienia wstępne i obwiednie) oraz wbudowane automatyczne przywracanie.

Elementy składowe

Narzędzie do tworzenia umożliwia sekwencjonowanie tych elementów haptycznych:

  • VibrationEffect.Preset: wstępnie zdefiniowane odczucia haptyczne reprezentujące typowe krótkie impulsy, takie jak PRESET_CLICK, PRESET_TICK i PRESET_LOW_TICK. Gotowe ustawienia zastępują krótkie elementy pierwotne z interfejsu VibrationEffect.Composition API. W przypadku dłuższych, ciągłych lub narastających efektów (wcześniej obsługiwanych przez funkcje rise, fall i inne) używaj obwiedni (PWLE). Gotowe ustawienia można skalować od 0.0f do 1.0f za pomocą funkcji Preset.create(presetId, scale).
  • VibrationEffect.Envelope: Koperty liniowe odcinkami (PWLE) utworzone za pomocą funkcji BasicEnvelopeBuilder (z intensywnością i ostrością) lub WaveformEnvelopeBuilder (z częstotliwością i amplitudą). Koperty są tworzone za pomocą Envelope.create(builder).
  • VibrationEffect.Event: zdarzenia na osi czasu pobrane z istniejącegoVibrationEffect za pomocą getEvents(). Można je dodawać z przesunięciem osi czasu za pomocą addEvents(startTimeShiftMillis, events).

Planowanie i weryfikacja osi czasu

Każdy element jest dodawany do narzędzia do tworzenia z symbolem startTimeMillis, który reprezentuje przesunięcie czasowe (w milisekundach) od początku kompozycji:

  • Weryfikacja w czasie kompilacji: elementy muszą być dodawane w ściśle rosnącej kolejności czasów rozpoczęcia. Podczas tworzenia kompilator przeprowadza weryfikację w najlepszy możliwy sposób, sprawdzając minimalny czas trwania (np. 1 ms w przypadku ustawień wstępnych lub znane czasy trwania w przypadku obwiedni). Jeśli w czasie kompilacji zostanie wykryta zbieżność, zostanie zgłoszony błąd IllegalArgumentException.
  • Dopasowanie czasu odtwarzania: platforma zapewnia najlepsze możliwe dopasowanie czasu podczas odtwarzania. Jeśli poprzednie zdarzenie nadal jest wykonywane, gdy nadejdzie czas rozpoczęcia następnego zaplanowanego zdarzenia, platforma automatycznie przesunie kolejne zdarzenie na najbliższy dostępny termin. Zapobiega to nakładaniu się zdarzeń podczas odtwarzania fizycznego, a jednocześnie gwarantuje, że żadne zdarzenia haptyczne nie zostaną pominięte.

Powtarzające się efekty

Powtarzający się efekt można dodać do kompozycji za pomocą polecenia setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). Po skonfigurowaniu efektu powtarzania nie można dodawać do narzędzia do tworzenia żadnych dodatkowych elementów.

Obsługa zastępcza

Automatyczne wsparcie rezerwowe na poziomie platformy jest domyślnie włączone w przypadku wibracji utworzonych przez VibrationEffect.Builder:

  • Przejrzyste zastępowanie platformy: jeśli urządzenie nie obsługuje żądanego Preset ani podstawowego Envelope, platforma automatycznie zastępuje nieobsługiwany element odpowiednim obsługiwanym wibratorem w czasie działania. Aplikacja nie musi ręcznie sprawdzać możliwości urządzenia (np. isPresetSupported) przed odtwarzaniem kompozycji utworzonych za pomocą VibrationEffect.Builder.
  • Wyjątek dla WaveformEnvelopeBuilder: efekty obwiedni utworzone przez WaveformEnvelopeBuilder (które określają bezwzględne częstotliwości fizyczne w hercach i amplitudy w jednostkach G) nie mają automatycznej obsługi rezerwowej. Zaawansowane PWLE opierają się na konkretnych krzywych częstotliwości sprzętu (FOAM), więc ich automatyczne zastępowanie naruszałoby zamierzony projekt. Jeśli urządzenie nie obsługuje efektów PWLE lub żądanych częstotliwości, takie wibracje nie będą odtwarzane. Aby zapewnić uniwersalną zgodność, wybierz BasicEnvelopeBuilder.

Wykorzystanie: VibrationEffect.Builder

Przykłady kodu dotyczące tworzenia efektów za pomocą VibrationEffect.Builder znajdziesz w artykule Tworzenie kompozycji zakotwiczonych na osi czasu za pomocą VibrationEffect.Builder.

VibrationEffect kompozycja elementów podstawowych,

Kompozycja elementów podstawowych VibrationEffect to efekt wibracji utworzony za pomocą interfejsu VibrationEffect.startComposition API. Ten interfejs API umożliwia tworzenie sekwencji elementów podstawowych.

Zgodność i wymagania

Odtwarzanie dowolnego VibrationEffect wymaga uprawnienia VIBRATE w pliku manifestu aplikacji.

Sprawdzanie obsługi typów prostych

.

Dlatego podczas korzystania z interfejsu VibrationEffect.Composition API przed odtworzeniem musisz sprawdzić obsługę poszczególnych elementów za pomocą funkcji Vibrator.arePrimitivesSupported lub Vibrator.areAllPrimitivesSupported.

Informacje o obsłudze poszczególnych elementó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ównoznaczne z AND-owaniem obsługi poszczególnych elementów pierwotnych.

Używanie kompozycji elementów podstawowych VibrationEffect

Szczegółowe informacje o używaniu kompozycji elementów podstawowych VibrationEffect znajdziesz w artykule Tworzenie kompozycji elementów podstawowych wibracji.

Wibracje włączone/wyłączone, jednorazowe i w formie fali

Najstarszą formą wibracji obsługiwaną na Androidzie są proste wzorce włączania i wyłączania wibratora z konfigurowalnym czasem 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 oparte na kształcie fali umożliwiają też powtarzanie wzorca w nieskończoność, co jest przydatne w przypadku dzwonka.

Wzorzec jednorazowy to wibracja trwająca N milisekund.

Istnieją 2 rodzaje wzorów fal:

  • Tylko czas Ten typ przebiegu to opis naprzemiennych okresów wyłączenia i włączenia. Czas trwania zaczyna się od czasu, przez jaki urządzenie było wyłączone. W związku z tym wzorce fal często zaczynają się od wartości zerowej, 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 niejawne włączanie i wyłączanie 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 praktycznie wszystkich urządzeniach z wibratorem, jak opisano dalej na tej stronie.

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

Jeśli używasz różnych wartości amplitudy w przebiegu 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 Notification API

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.

Pojęcia ogólne

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

Czy urządzenie ma wibrator?

Klasę Vibrator o wartości innej niż null możesz uzyskać z poziomu 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 sprawdzania, czy użytkownik całkowicie wyłączył ustawienie Odpowiedź dotykowa na Androidzie. W takim przypadku efekty odpowiedzi dotykowej powinny być pomijane. O to ustawienie można wysłać zapytanie za pomocą klucza HAPTIC_FEEDBACK_ENABLED. Wartość zero oznacza, że jest ono wyłączone.

Atrybuty wibracji

Możesz podać atrybuty wibracji (obecnie w formie AudioAttributes), aby pomóc systemowi określić cel 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.

Sterowanie amplitudą

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ę kontroli amplitudy można sprawdzić, wywołując funkcję Vibrator.hasAmplitudeControl. Jeśli wibrator nie obsługuje amplitudy, wszystkie wartości amplitudy będą mapowane na wyłączone lub włączone w zależności od tego, czy są zerowe czy 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 obwiedni

Wibratory z efektami obwiedni obsługują i umożliwiają tworzenie bardziej dynamicznych i zniuansowanych wibracji, zapewniając precyzyjniejszą kontrolę nad intensywnością i ostrością, co pozwala uzyskać bogatsze wrażenia dotykowe. Sprawdź, czy Twoje urządzenie obsługuje tę funkcję, korzystając z Vibration.areEnvelopeEffectsSupported. Jeśli nie, wibracje oparte na obwiedni są ignorowane.