Dokumentacja interfejsu API reakcji haptycznych na Androida

W tej sekcji znajdziesz wprowadzenie do różnych interfejsów API haptycznych dostępnych w Androidzie. Dowiesz się też, kiedy i jak sprawdzić, czy urządzenie obsługuje efekty haptyczne, aby mieć pewność, że będą działać zgodnie z oczekiwaniami.

Efekty haptyczne można tworzyć na kilka różnych sposobów. Podczas wyboru efektu należy wziąć pod uwagę zasady projektowania haptycznego na Androidzie. Tabela poniżej zawiera podsumowanie tych ogólnych atrybutów poszczególnych metod:

  • Dostępność jest szczególnie ważna podczas planowania zachowania zastępczego i musi być połączona z sprawdzaniem obsługi poszczególnych urządzeń.
  • Czysty haptyczny odzew to wyraźne i czyste wrażenia, które są mniej drażliwe dla użytkowników.
  • Zaawansowane funkcje haptyczne zapewniają większą ekspresję i często wymagają bardziej zaawansowanego sprzętu.
Interfejs API Dostępność Wyczyść haptyczne Bogaty system haptyczny
HapticFeedbackConstants Android 1.5 lub nowszy
(na podstawie stałej wartości)
Wstępnie zdefiniowany efekt wibracji Android 10 lub nowszy
Kompozycja wibracji Android 11 i nowsze (według stałej)
Włączanie i wyłączanie wibracji, wibracje jednorazowe i wibracje w formie fali Android 1

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

Na tej stronie opisano też dodatkowe pojęcia dotyczące interfejsów API:

  • Czy urządzenie ma wibrator?
  • Regulacja amplitudy umożliwia płynniejsze i bogatsze efekty haptyczne, ale nie jest obsługiwana na wszystkich urządzeniach.
  • VibrationAttributes() pomaga klasyfikować wibracje na podstawie ich zastosowania, co zapewnia stosowanie odpowiednich ustawień użytkownika, dzięki czemu można uniknąć niespodzianek.

HapticFeedbackConstants

Klasa HapticFeedbackConstants udostępnia stałe wartości dla poszczególnych działań, aby aplikacje mogły dodawać wibracje, które będą spójne na wszystkich urządzeniach, zamiast tego, aby każda aplikacja miała inne efekty dla tych samych działań.

Zgodność i wymagania

Użycie metody View.performHapticFeedback z tymi stałymi wartościami nie wymaga żadnych specjalnych uprawnień aplikacji. Jest ono zależne od właściwości View.hapticFeedbackEnabled, która po ustawieniu na false wyłączy wszystkie wywołania haptycznych informacji zwrotnych w widoku, w tym domyślne.Głównym ustawieniem związanym z tą właściwością jest View.hapticFeedbackEnabled, która po ustawieniu na false wyłączy wszystkie wywołania haptycznych informacji zwrotnych w widoku, w tym domyślne. Metoda uwzględnia też ustawienie systemu użytkownika dotyczące włączenia informacji zwrotnych z dotyku.

Jedynym czynnikiem, który należy wziąć pod uwagę, jest wersja pakietu SDK, w której znajduje się dana stała.

W przypadku korzystania z elementu HapticFeedbackConstants nie trzeba podawać zachowania zastępczego.

Wykorzystanie: HapticsFeedbackConstants

Szczegółowe informacje o używaniu HapticFeedbackConstants znajdziesz w artykule Dodawanie wibracji do zdarzeń.

Wstępnie zdefiniowane 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.

Nie trzeba określać zachowania zastępczego podczas używania wstępnie zdefiniowanych wartości VibrationEffect, ponieważ stałe, które nie mają implementacji zoptymalizowanej pod kątem urządzenia, wracają do standardowego zastępczego zachowania na platformie.

Interfejsy API Vibrator.areEffectsSupported i Vibrator.areAllEffectsSupported służą do określania, czy istnieje implementacja zoptymalizowana pod kątem urządzenia. Zdefiniowane wstępnie efekty można nadal używać bez zoptymalizowanej implementacji. Korzystają one ze standardowych zastępczych efektów na platformie. W konsekwencji te interfejsy APIareEffectsSupported są potrzebne tylko wtedy, gdy aplikacja ma uwzględniać to, czy efekt jest zoptymalizowany pod kątem danego urządzenia.

Metody sprawdzania efektu mogą zwracać jedną z 3 wartości:

Wartość UNKNOWN wskazuje, że interfejs API do sprawdzania jest niedostępny, dlatego zazwyczaj zwraca on wszystkie efekty lub żadne. Te urządzenia dynamicznie przechodzą na tryb awaryjny.

Wykorzystanie zdefiniowanej wstępnie wartości VibrationEffect

Szczegółowe informacje o używaniu wstępnie zdefiniowanego VibrationEffect znajdziesz w artykule Generowanie informacji zwrotnych haptycznych za pomocą wstępnie zdefiniowanego VibrationEffect.

VibrationEffect kompozycja

Kompozycja VibrationEffect to efekt wibracji utworzony za pomocą interfejsu VibrationEffect.startComposition API. Ten interfejs API umożliwia tworzenie bogatych haptycznych efektów przez tworzenie sekwencji prymitywów z indywidualizowanymi opóźnieniami i intensywnością. Upewnij się jednak, że urządzenie obsługuje funkcje, które mają być połączone, aby uniknąć niespójności.

Zgodność i wymagania

Odtwarzanie dowolnego VibrationEffect wymaga uprawnienia VIBRATE w pliku manifestu aplikacji.

Nie wszystkie urządzenia obsługują wszystkie funkcje interfejsu Composition API, dlatego ważne jest, aby elementy składowe były dostępne.

Sprawdzanie obsługi wibracji

Obsługę na poziomie prymitywu można pobrać za pomocą metody Vibrator.arePrimitivesSupported. Można też sprawdzić razem zestaw prymitywów, używając metody Vibrator.areAllPrimitivesSupported. Jest to równoznaczne z użyciem funkcji AND dla każdego prymitywu.

Korzystanie z kompozycji VibrationEffect

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

Wibracje włącz/wyłącz, jednokrotne i z amplitudometrem.

Najstarsza forma wibracji obsługiwana na Androidzie to proste wzorce włączania i wyłączania wibracji z możliwością konfiguracji czasu trwania. Te interfejsy API zwykle nie są dobrze dopasowane do zasad projektowania haptyki, ponieważ mogą generować szum haptyczny. Unikaj ich, chyba że jest to ostateczność.

Najczęstszym zastosowaniem wibracji włączania i wyłączania jest wyświetlanie powiadomień, w których przypadku zawsze potrzebne jest wibrowanie. Wibracje w formie fali umożliwiają powtarzanie w nieskończoność wzoru, który można wykorzystać np. w przypadku dzwonka.

Wzorzec jednorazowy oznacza wibrowanie raz przez N milisekund.

Istnieją 2 typy wzorów fal:

  • Tylko czasy trwania. Ten typ przebiegu fali to opis naprzemiennie włączonych i wyłączonych okresów. Czasy trwania zaczynają się od czasu spędzonego poza ekranem. W związku z tym wzorce fali często zaczynają się od wartości 0, aby wskazać, że wibracje mają się rozpocząć natychmiast.
  • Czas trwania i amplituda. Ten typ przebiegu ma dodatkową tablicę amplitud, które pasują do każdej wartości czasu, a nie do niejawnego włączania i wyłączania pierwszego typu. Należy jednak sprawdzić, czy urządzenie obsługuje kontrolę amplitudy, aby upewnić się, że można uzyskać pożądane skalowanie.

Zgodność i wymagania

Wibracje włącz/wyłącz są najstarszą formą wibracji i są obsługiwane na niemal wszystkich urządzeniach z wibratorem, jak opisano dalej na tej stronie.

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

Jeśli używasz różnych wartości amplitudy w fazie, zdecydowanie zalecamy, aby urządzenie obsługiwało kontrolę amplitudy.

Sprawdzanie obsługi kontroli amplitudy

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

Uważnie rozważ, czy efekt ma odpowiednią jakość bez kontroli amplitudy. Lepiej jest wrócić do wyraźnie zaprojektowanego wibrowania.

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

W nowszych poziomach pakietu SDK wszystkie tryby wibracji zostały scalone 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ń w aplikacji możesz użyć jednego z tych interfejsów API, aby powiązać wzór z każdym kanałem powiadomień:

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

Pojęcia ogólne

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

Czy urządzenie ma wibrator?

Z context.getSystemService(Vibrator.class) możesz uzyskać niezerową klasę Vibrator. 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 funkcji haptycznych do określonego warunku. W razie potrzeby aplikacja może jednak wywołać funkcję hasVibrator(), aby określić, czy jest to prawdziwy wibrator (true) czy stub (false).

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

Niektóre niestandardowe implementacje mogą wymagać ręcznego sprawdzenia, czy użytkownik całkowicie wyłączył ustawienie Informacje zwrotne dotykowe w Androidzie. W takim przypadku efekty informacji zwrotnych dotykowych powinny zostać stłumione. To ustawienie można zapytać za pomocą klucza HAPTIC_FEEDBACK_ENABLED, gdzie wartość 0 oznacza, że jest wyłączone.

Atrybuty wibracji

Aby poinformować system o celu wibracji, możesz podać atrybuty wibracji (obecnie w formie AudioAttributes). Jest to wymagane, gdy aplikacja jest aktywna w tle i wyzwala wibracje, ponieważ w przypadku korzystania z aplikacji w tle obsługiwane są tylko dźwięki haptyczne zwracające uwagę.

Tworzenie AudioAttributes jest opisane w dokumentacji klasy i powinno być traktowane jako wibracje, a nie dźwięk.

W większości przypadków typ treści to CONTENT_TYPE_SONIFICATION, a użyteczność może mieć wartości takie jak USAGE_ASSISTANCE_SONIFICATION dla informacji zwrotnej dotykowej na pierwszym planie lub USAGE_ALARM dla alarmu w tle. Flagi dźwięku nie mają wpływu na wibracje.

Regulacja amplitudy

Jeśli wibrator ma kontrolę amplitudy, może generować wibracje o zmiennej intensywności. Jest to ważna funkcja do tworzenia bogatych haptycznych efektów, a także umożliwia użytkownikom kontrolowanie domyślnych intensywności haptycznych.

Aby sprawdzić, czy Amplitude obsługuje kontrolę, zadzwoń pod numer Vibrator.hasAmplitudeControl. Jeśli wibrator nie obsługuje amplitudy, wszystkie wartości amplitudy będą mapowane na wyłączone/włączone w zależności od tego, czy są równe 0/nierówne 0. Dlatego aplikacje korzystające z bogatych haptycznych efektów z różnymi amplitudami powinny rozważyć ich wyłączenie, jeśli urządzenie nie ma kontroli amplitudy.