Android Haptik API-Referenz

In diesem Abschnitt werden die verschiedenen Haptik-APIs in Android vorgestellt. Außerdem wird beschrieben, wann und wie Sie prüfen können, ob Ihr Gerät die erforderliche Unterstützung bietet, damit Ihre haptischen Effekte wie gewünscht wiedergegeben werden.

Es gibt verschiedene Möglichkeiten, haptische Effekte zu erstellen. Bei der Auswahl ist es wichtig, die Designprinzipien für haptische Effekte unter Android zu berücksichtigen. In der folgenden Tabelle sind diese Attribute auf hoher Ebene für die einzelnen Ansätze zusammengefasst:

  • Die Verfügbarkeit ist besonders wichtig, wenn Sie ein Fallback-Verhalten planen. Sie muss mit der Prüfung der Unterstützung für einzelne Geräte kombiniert werden.
  • Deutliche Haptik sind klare und saubere Empfindungen, die für Nutzer weniger störend sind.
  • Umfangreiche Haptik ist ausdrucksstärker und erfordert oft eine Hardware mit mehr Funktionen.
API-Oberfläche Verfügbarkeit Haptisches Feedback löschen Umfassende Haptik
HapticFeedbackConstants Android 1.5+
(per constant)
Vordefinierter VibrationEffect Android 10 und höher
VibrationEffect-Zusammensetzung Android 11 und höher (über Konstante)
Vibrationen für Ein/Aus, einmalige und Wellenform-Vibrationen Android 1

Außerdem können Sie mit den Benachrichtigungs-APIs, die auf dieser Seite beschrieben werden, die haptischen Effekte anpassen, die bei eingehenden Benachrichtigungen wiedergegeben werden.

Auf dieser Seite werden auch zusätzliche Konzepte beschrieben, die sich über die API-Oberflächen erstrecken:

HapticFeedbackConstants

Die Klasse HapticFeedbackConstants bietet aktionsbasierte Konstanten, mit denen Apps haptisches Feedback hinzufügen können, das auf allen Geräten einheitlich ist. So hat nicht jede App unterschiedliche Effekte für gängige Aktionen.

Kompatibilität und Anforderungen

Für die Verwendung der Methode View.performHapticFeedback mit diesen Konstanten sind keine besonderen Berechtigungen für die App erforderlich. Sie unterliegt der Eigenschaft View.hapticFeedbackEnabled. Wenn diese auf false gesetzt ist, werden alle Haptik-Feedback-Aufrufe für die Ansicht deaktiviert, einschließlich der Standardaufrufe. Die primäre zugehörige Einstellung ist die Eigenschaft View.hapticFeedbackEnabled. Wenn diese auf false gesetzt ist, werden alle Haptik-Feedback-Aufrufe für die Ansicht deaktiviert, einschließlich der Standardaufrufe. Die Methode berücksichtigt auch die Systemeinstellung des Nutzers zum Aktivieren von Touch-Feedback.

Die einzige Kompatibilitätsüberlegung ist die SDK-Ebene der spezifischen Konstante für die Aktion.

Bei Verwendung von HapticFeedbackConstants ist kein Fallback-Verhalten erforderlich.

Nutzung von HapticsFeedbackConstants

Weitere Informationen zur Verwendung von HapticFeedbackConstants finden Sie unter Haptisches Feedback zu Ereignissen hinzufügen.

Vordefinierte VibrationEffect

Die Klasse VibrationEffect bietet mehrere vordefinierte Konstanten wie CLICK, TICK und DOUBLE_CLICK. Diese Effekte sind möglicherweise für das Gerät optimiert.

Kompatibilität und Anforderungen

Für die Wiedergabe von VibrationEffect ist die Berechtigung VIBRATE im App-Manifest erforderlich.

Wenn Sie vordefinierte VibrationEffect verwenden, müssen Sie kein Fallback-Verhalten angeben, da Konstanten ohne geräteoptimierte Implementierung auf ein Standard-Plattform-Fallback zurückgreifen.

Mit den APIs Vibrator.areEffectsSupported und Vibrator.areAllEffectsSupported lässt sich ermitteln, ob eine für das Gerät optimierte Implementierung vorhanden ist. Vordefinierte Effekte können weiterhin ohne optimierte Implementierung verwendet werden. Dabei wird der Standard-Plattform-Fallback verwendet. Folglich sind diese areEffectsSupported-APIs nur erforderlich, wenn eine Anwendung berücksichtigen möchte, ob der Effekt für das Gerät optimiert ist oder nicht.

Die Methoden zur Überprüfung von Effekten können einen von drei Werten zurückgeben:

Da der Wert UNKNOWN angibt, dass die Prüf-API nicht verfügbar ist, wird er in der Regel für alle oder keine Effekte zurückgegeben. Diese Geräte werden dynamisch zurückgesetzt.

Verwendung vordefinierter VibrationEffect

Weitere Informationen zur Verwendung eines vordefinierten VibrationEffect finden Sie unter Vordefiniertes VibrationEffect zum Generieren von haptischem Feedback verwenden.

Envelope VibrationEffect

Mit envelopebasierten Vibrationen lässt sich die Amplitude und Frequenz der Vibration im Zeitverlauf präzise steuern, indem eine Sequenz von Kontrollpunkten definiert wird. So können Entwickler reichhaltigere und differenziertere haptische Feedback-Erlebnisse schaffen. Diese Vibrationen können mit den Klassen BasicEnvelopeBuilder und WaveformEnvelopeBuilder erstellt werden.

Kompatibilität und Anforderungen

Wenn Ihre App Vibrations-Effekte wiedergeben soll, muss sie die Berechtigung VIBRATE im App-Manifest deklarieren.

Rufen Sie Vibrator.areEnvelopeEffectsSupported() auf, um zu prüfen, ob Envelope-Effekte unterstützt werden.

Basic Envelope Builder

Damit die Haptik reibungslos und nahtlos ist, müssen Envelope-Effekte mit einer Intensität von \( 0.0 \)beginnen und enden. Die API erzwingt dies, indem sie die Startintensität auf null festlegt und eine Ausnahme auslöst, wenn die Endintensität nicht null ist. Diese Einschränkung verhindert unerwünschte dynamische Effekte bei den Vibrationen aufgrund von Diskontinuitäten in der Amplitude, die sich negativ auf die haptische Wahrnehmung des Nutzers auswirken können.

Damit der Hüllkurveneffekt auf allen Geräten einheitlich gerendert wird, müssen Geräte, die diese Funktion unterstützen, eine Mindestdauer von 20 ms zwischen den Kontrollpunkten und mindestens 16 Punkte für Hüllkurveneffekte verarbeiten können.

Wellenform-Hüllkurven-Generator

Das Framework ändert die vom Entwickler angegebenen Werte für Frequenz und Amplitude nicht. Die API setzt die Startamplitude jedoch auch auf null, um für einen reibungslosen Übergang zu sorgen.

Damit du die Wellenform-Envelope-Effekte deiner App optimieren und die Kompatibilität auf verschiedenen Geräten sicherstellen kannst, bietet Android APIs zum Abfragen wichtiger Gerätefunktionen. Diese Methoden liefern Informationen zu den Einschränkungen des Geräts, z. B. die maximale und minimale Übergangsdauer zwischen Kontrollpunkten und die maximale Anzahl der Kontrollpunkte, die für einen einzelnen Effekt unterstützt werden:

getMaxSize()
Ruft die maximale Anzahl von Kontrollpunkten ab, die für einen Envelope-Effekt unterstützt werden.
getMinControlPointDurationMillis()
Ruft die unterstützte Mindestdauer in Millisekunden zwischen zwei Kontrollpunkten innerhalb eines Hüllkurven-Effekts ab.
getMaxControlPointDurationMillis()
Ruft die maximal unterstützte Dauer in Millisekunden zwischen zwei Kontrollpunkten innerhalb eines Envelope-Effekts ab.
getMaxDurationMillis()
Ruft die maximale Dauer ab, die für einen Hüllkurveneffekt unterstützt wird, in Millisekunden.

Wenn ein Effekt die Einschränkungen des Geräts überschreitet, z. B. zu viele Kontrollpunkte oder eine Dauer, die das Maximum überschreitet, passt das Framework den Effekt automatisch an die zulässigen Grenzen an. Bei diesem Anpassungsprozess wird versucht, die ursprüngliche Intention und das ursprüngliche Design so weit wie möglich beizubehalten.

Verwendung von Envelope-Vibrationseffekten

Weitere Informationen zum Erstellen von Hüllkurven-Wellenformeinblendungen finden Sie unter Vibrationswellenform mit Hüllkurven erstellen.

VibrationEffect Komposition

Eine VibrationEffect-Komposition ist ein Vibrationseffekt, der mit der VibrationEffect.startComposition-API erstellt wurde. Mit dieser API können Sie umfangreiche Haptik erstellen, indem Sie eine Sequenz von Primitiven mit benutzerdefinierten Verzögerungen und Intensitäten erstellen. Achten Sie jedoch darauf, dass das Gerät die kombinierten Funktionen unterstützt, um eine inkonsistente Gesamtnutzung zu vermeiden.

Kompatibilität und Anforderungen

Für die Wiedergabe von VibrationEffect ist die Berechtigung VIBRATE im App-Manifest erforderlich.

Nicht alle Geräte unterstützen alle Funktionen der Composition API. Es ist wichtig, dass die Grundelemente verfügbar sind.

Unterstützung von Vibrationsprimitiven prüfen

Die Unterstützung pro Primitiv kann mit der Methode Vibrator.arePrimitivesSupported abgerufen werden. Alternativ kann eine Reihe von Primitiven mit der Methode Vibrator.areAllPrimitivesSupported gemeinsam geprüft werden. Dies entspricht der AND-Methode für die Unterstützung der einzelnen Primitiven.

Verwendung von VibrationEffect-Kompositionen

Weitere Informationen zur Verwendung von VibrationEffect-Kompositionen finden Sie unter Vibrationskompositionen erstellen.

Vibrationen für Ein/Aus, einmalige und Wellenform-Vibrationen

Die älteste Form der Vibration, die auf Android unterstützt wird, sind einfache Vibrator-Ein/Aus-Muster mit konfigurierbaren Dauern. Diese APIs entsprechen in der Regel nicht den Designprinzipien für Haptik, da sie vibrationsartige Haptik erzeugen können. Vermeiden Sie sie, es sei denn, es gibt keine andere Möglichkeit.

Der häufigste Anwendungsfall für das Ein-Aus-Vibrieren sind Benachrichtigungen, bei denen in jedem Fall eine Vibration gewünscht ist. Wellenform-Vibrationen ermöglichen es außerdem, ein Muster unendlich oft zu wiederholen, wie es bei einem Klingelton der Fall ist.

Ein One-Shot-Muster bezieht sich auf ein einmaliges Vibrieren für N Millisekunden.

Es gibt zwei Arten von Wellenformmustern:

  • Nur Zeitangaben: Diese Art von Wellenform beschreibt abwechselnde Zeiträume, in denen das Gerät aus- und eingeschaltet ist. Die Zeitangaben beginnen mit der Dauer, in der das Gerät nicht vibriert. Daher beginnen Wellenformmuster oft mit dem Wert „0“, um anzuzeigen, dass das Gerät sofort mit dem Vibrieren beginnen soll.
  • Zeitpunkte und Amplituden: Diese Art von Wellenform hat ein zusätzliches Array von Amplituden, die mit jeder Zeitangabe übereinstimmen, anstatt des impliziten Ein/Aus der ersten Form. Es ist jedoch wichtig, zu prüfen, ob das Gerät die Amplitudensteuerung unterstützt, damit die beabsichtigte Skalierung erreicht werden kann.

Kompatibilität und Anforderungen

Da das Ein-Aus-Vibrieren die älteste Form des Vibrierens ist, wird es auf nahezu allen Geräten mit Vibrator unterstützt, wie später auf dieser Seite beschrieben.

Für die Wiedergabe von VibrationEffect- oder vibrate-Anrufen ist die Berechtigung VIBRATE im App-Manifest erforderlich.

Wenn Sie in einer Wellenform unterschiedliche Amplitudenwerte verwenden, empfehlen wir dringend, dass das Gerät Amplitudensteuerung unterstützt.

Unterstützung für die Amplitudensteuerung prüfen

Amplitude-Werte ungleich null werden auf Geräten ohne Amplitude-Steuerung auf 100% aufgerundet. Daher ist es wichtig, mit Vibrator.hasAmplitudeControl zu prüfen, ob die Unterstützung vorhanden ist. Weitere Informationen finden Sie unter Amplitudensteuerung.

Sie sollten sorgfältig prüfen, ob Ihr Effekt ohne Amplitudenkontrolle von ausreichender Qualität ist. Es kann besser sein, auf eine explizit entwickelte Ein-/Aus-Vibration zurückzugreifen.

Verwendung von Ein-/Aus-Vibrationen

In neueren SDK-Versionen wurden alle Vibrationsmodi in einer einzigen ausdrucksstarken Klasse VibrationEffect zusammengefasst. Diese einfachen Vibrationen werden mit VibrationEffect.createOneshot oder VibrationEffect.createWaveform erstellt.

Benachrichtigungs-APIs

Wenn Sie Ihre App-Benachrichtigungen anpassen, können Sie eine der folgenden APIs verwenden, um jedem Benachrichtigungskanal ein Muster zuzuweisen:

Alle diese Formen haben ein einfaches Ein/Aus-Wellenformmuster, wie oben beschrieben. Der erste Eintrag ist die Verzögerung, bevor der Vibrator eingeschaltet wird.

Allgemeine Konzepte

Mehrere Konzepte gelten für die oben beschriebenen API-Oberflächen.

Hat das Gerät einen Vibrationsmotor?

Sie können eine Vibrator-Klasse, die nicht null ist, aus context.getSystemService(Vibrator.class) abrufen. Wenn das Gerät keinen Vibrator hat, haben Aufrufe der Vibrations-APIs keine Auswirkungen. Apps müssen also nicht alle Haptikfunktionen an eine Bedingung knüpfen. Bei Bedarf kann eine Anwendung jedoch hasVibrator() aufrufen, um festzustellen, ob es sich um einen echten Vibrator (true) oder einen Stub (false) handelt.

Hat der Nutzer die Touch-Haptik deaktiviert?

Bei einigen benutzerdefinierten Implementierungen muss manuell geprüft werden, ob der Nutzer die Android-Einstellung Touch-Feedback vollständig deaktiviert hat. In diesem Fall sollten Touch-Feedback-Effekte unterdrückt werden. Diese Einstellung kann mit dem Schlüssel HAPTIC_FEEDBACK_ENABLED abgefragt werden. Ein Wert von null bedeutet, dass sie deaktiviert ist.

Vibrationsattribute

Vibrationsattribute (derzeit in Form von AudioAttributes) können angegeben werden, um dem System den Zweck der Vibration mitzuteilen. Dies ist erforderlich, wenn Sie eine Vibration auslösen möchten, während sich Ihre App im Hintergrund befindet, da nur aufmerksamkeitsstarke Haptik für die Hintergrundnutzung unterstützt wird.

Die Erstellung von AudioAttributes wird in der Klassendokumentation behandelt und sollte eher als Vibration als als Ton betrachtet werden.

In den meisten Fällen ist der Inhaltstyp CONTENT_TYPE_SONIFICATION und die Verwendung kann Werte wie USAGE_ASSISTANCE_SONIFICATION für die haptische Rückmeldung im Vordergrund oder USAGE_ALARM für einen Alarm im Hintergrund haben. Audio-Flags haben keine Auswirkungen auf Vibrationen.

Amplitudensteuerung

Wenn ein Vibrator über eine Amplitudensteuerung verfügt, kann er Vibrationen mit unterschiedlichen Intensitäten ausführen. Dies ist eine wichtige Funktion für die Erstellung von umfangreichen haptischen Signalen und ermöglicht möglicherweise die Nutzersteuerung der standardmäßigen haptischen Intensitäten.

Die Unterstützung der Amplitudensteuerung kann durch Aufrufen von Vibrator.hasAmplitudeControl geprüft werden. Wenn ein Vibrator keine Unterstützung für die Amplitude bietet, werden alle Amplitudenwerte basierend darauf, ob sie null oder ungleich null sind, auf „Aus“ oder „Ein“ abgebildet. Daher sollten Anwendungen, die Rich Haptics mit unterschiedlichen Amplituden verwenden, diese deaktivieren, wenn das Gerät keine Amplitudensteuerung bietet.

Unterstützung von Envelope-Effekten

Vibratoren mit Envelope-Effekten unterstützen und ermöglichen die Erstellung dynamischerer und nuancierterer Vibrationen. Sie bieten eine präzisere Steuerung von Intensität und Schärfe für ein besseres haptisches Erlebnis. Verwende Vibration.areEnvelopeEffectsSupported, um herauszufinden, ob dein Gerät diese Funktion unterstützt. Andernfalls werden envelope-basierte Vibrationen ignoriert.