Android Haptik API-Referenz

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

In diesem Abschnitt erhalten Sie eine Einführung in die verschiedenen Haptik-APIs, die in Android verfügbar sind. Außerdem erfahren Sie, wann und wie Sie prüfen können, ob die Geräte die haptischen Effekte unterstützen, damit sie wie gewünscht abgespielt werden.

Es gibt verschiedene Möglichkeiten, haptische Effekte zu erstellen. Bei der Auswahl sollten Sie die Designprinzipien für Haptik auf Android-Geräten berücksichtigen. In der folgenden Tabelle sind diese allgemeinen Attribute der einzelnen Ansätze zusammengefasst:

• Die Verfügbarkeit ist besonders wichtig bei der Planung des Verhaltens bei Ausfall und muss mit der Prüfung der Unterstützung einzelner Geräte kombiniert werden.
• Klare Haptik sind klare und saubere Empfindungen, die für Nutzer weniger irritierend sind.
• Ausdrucksstarke Haptik ist ausdrucksvoller und erfordert oft eine leistungsstärkere Hardware.

API-Oberfläche	Verfügbarkeit	Haptik löschen	Ausgefeilte Haptik
HapticFeedbackConstants	Android 1.5 und höher (pro Konstante)
Vordefinierter Vibrationseffekt	Android 10 oder höher
VibrationEffect-Zusammensetzung	Android 11 und höher (je nach Konstante)
Ein/Aus, einmalige Vibration und Wellenform	Android 1

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

Auf dieser Seite werden auch weitere Konzepte beschrieben, die für alle API-Oberflächen gelten:

• Hat das Gerät einen Vibrator?
• Die Amplitudensteuerung ermöglicht weichere, ausdrucksstärkere haptische Effekte, wird aber nicht von allen Geräten unterstützt.
• Mit VibrationAttributes() können Sie Vibrationen basierend auf ihrer Verwendung klassifizieren, sodass die entsprechenden Nutzereinstellungen angewendet werden und der Nutzer nicht überrascht wird.

HapticFeedbackConstants

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

Kompatibilität und Anforderungen

Für die Verwendung der Methode View.performHapticFeedback mit diesen Konstanten sind keine speziellen Berechtigungen für die App erforderlich. Sie unterliegt der Eigenschaft View.hapticFeedbackEnabled.Wenn diese auf false festgelegt ist, werden alle Aufrufe für haptisches Feedback in der Ansicht deaktiviert, einschließlich der Standardaufrufe.View.hapticFeedbackEnabledfalse Die Methode berücksichtigt auch die Systemeinstellung des Nutzers zum Aktivieren von Touchfeedback.

Die einzige Kompatibilitätsüberlegung ist die SDK-Ebene der jeweiligen 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 Ereignissen haptisches Feedback hinzufügen.

Vordefiniert VibrationEffect

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

Kompatibilität und Anforderungen

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

Bei der Verwendung vordefinierter VibrationEffect ist kein Fallback-Verhalten erforderlich, da Konstanten ohne eine für das Gerät optimierte Implementierung auf einen Standard-Plattform-Fallback zurückgreifen.

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

Die Methoden zur Wirkungsüberprüfung können einen der drei Werte zurückgeben:

• VIBRATION_EFFECT_SUPPORT_YES gibt an, dass das Gerät den Support für diesen Effekt optimiert hat.
• VIBRATION_EFFECT_SUPPORT_NO weist darauf hin, dass das Gerät nicht optimiert unterstützt wird, aber trotzdem der Plattform-Fallback verwendet wird.
• VIBRATION_EFFECT_SUPPORT_UNKNOWN gibt an, dass das System nicht weiß, ob die Implementierung optimiert ist oder nicht.

Da der Wert „UNKNOWN“ angibt, dass die API zur Überprüfung nicht verfügbar ist, wird er in der Regel für alle oder keine Effekte zurückgegeben. Bei diesen Geräten erfolgt ein dynamischer Rückfall.

Verwendung vordefinierter VibrationEffect

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

VibrationEffect Komposition

Eine VibrationEffect-Komposition ist ein Vibrationseffekt, der mit der VibrationEffect.startComposition API erstellt wurde. Diese API ermöglicht ausdrucksstarke Haptik, indem eine Sequenz von Primitivelementen mit benutzerdefinierten Verzögerungen und Intensitäten erstellt wird. Achten Sie jedoch darauf, dass das Gerät die kombinierten Funktionen unterstützt, um Inkonsistenzen 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 Primitiven verfügbar sind.

Unterstützung für Vibrationsprimitive prüfen

Unterstützung pro Primitive kann mit der Methode Vibrator.arePrimitivesSupported abgerufen werden. Alternativ können Sie mit der Methode Vibrator.areAllPrimitivesSupported mehrere Primitive gleichzeitig prüfen. Das entspricht dem AND-en der Unterstützung pro Primitive.

Verwendung von VibrationEffect-Kompositionen

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

Ein-/Aus-, One-Shot- und Wellenform-Vibrationen

Die älteste Form der Vibration, die auf Android unterstützt wird, sind einfache Ein-/Aus-Muster des Vibrators mit konfigurierbarer Dauer. Diese APIs sind in der Regel nicht gut mit den Designprinzipien für Haptik abgestimmt, da sie brummende Haptik erzeugen können. Verwenden Sie sie nur als letzten Ausweg.

Der häufigste Anwendungsfall für die Vibrationsfunktion „An/Aus“ sind Benachrichtigungen, bei denen unabhängig von der Situation eine gewisse Vibration gewünscht ist. Bei Wellenformvibrationen kann ein Muster auch unendlich wiederholt werden, wie Sie sich vielleicht für einen Klingelton vorstellen können.

Ein Einmal-Muster bedeutet, dass das Gerät einmal für N Millisekunden vibriert.

Es gibt zwei Arten von Wellenformmustern:

• Nur Zeitangaben Dieser Wellenformtyp beschreibt abwechselnde Zeiten, in denen das Gerät aus- und eingeschaltet ist. Die Zeitangaben beginnen mit der Dauer, in der das Gerät ausgeschaltet ist. Daher beginnen Wellenformmuster oft mit dem Wert „0“, um anzugeben, dass sofort vibriert werden soll.
• Timings und Amplituden Dieser Wellenformtyp hat ein zusätzliches Array von Amplituden, die mit jeder Zeitfigur übereinstimmen, anstatt das implizite Ein-/Aus der ersten Form. Es ist jedoch wichtig, zu prüfen, ob das Gerät die Amplitudenregelung unterstützt, damit die gewünschte Skalierung erreicht werden kann.

Kompatibilität und Anforderungen

Da das Ein-/Ausschalten von Vibrationen die älteste Form von Vibrationen ist, wird diese Funktion auf nahezu allen Geräten mit einem Vibrator unterstützt, wie weiter unten auf dieser Seite beschrieben.

Für die Wiedergabe von VibrationEffect- oder vibrate-Aufrufen des älteren Typs ist die Berechtigung VIBRATE im App-Manifest erforderlich.

Wenn Sie unterschiedliche Amplitudenwerte in einer Wellenform verwenden, empfehlen wir Ihnen dringend, ein Gerät zu verwenden, das die Amplitudenregelung unterstützt.

Unterstützung der Amplitudenregelung prüfen

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

Du solltest sorgfältig überlegen, ob dein Effekt ohne Amplitudenregelung eine ausreichende Qualität hat. Es ist möglicherweise besser, auf eine explizit für das Ein- und Ausschalten konzipierte Vibration zurückzugreifen.

Verwendung von Ein-/Aus-Vibrationen

In neueren SDK-Levels wurden alle Vibrationsmodi in einer einzigen ausdrucksstarken VibrationEffect-Klasse zusammengefasst, in der diese einfachen Vibrationen mit VibrationEffect.createOneshot oder VibrationEffect.createWaveform erstellt werden.

Benachrichtigungs-APIs

Wenn Sie Ihre App-Benachrichtigungen anpassen, können Sie mit einer der folgenden APIs ein Muster mit jedem Benachrichtigungskanal verknüpfen:

• AndroidX
  • NotificationChannelCompat.Builder.setVibrationPattern
  • NotificationCompat.setVibrate
• Android
  • NotificationChannel.setVibrationPattern
  • (veraltet) NotificationBuilder.setVibrate

Alle diese Formen haben ein einfaches An-/Aus-Wellenformmuster, wie oben beschrieben, wobei der erste Eintrag die Verzögerung vor dem Einschalten des Vibrators ist.

Allgemeine Konzepte

Für die oben beschriebenen API-Oberflächen gelten mehrere Konzepte.

Hat das Gerät einen Vibrator?

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

Hat der Nutzer die Haptik deaktiviert?

Bei einigen benutzerdefinierten Implementierungen muss möglicherweise manuell geprüft werden, ob der Nutzer die Einstellung Touch-Feedback von Android 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 „deaktiviert“.

Vibrationsattribute

Vibrationsattribute (derzeit in Form von AudioAttributes) können angegeben werden, um das System über den Zweck der Vibration zu informieren. Dies ist erforderlich, wenn eine Vibration gestartet werden soll, während Ihre App im Hintergrund ausgeführt wird, da für die Hintergrundnutzung nur haptisches Feedback zur Aufmerksamkeitssteigerung unterstützt wird.

Die Erstellung von AudioAttributes wird in der Klassendokumentation behandelt und sollte als Vibration und nicht 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 Touch-Feedback im Vordergrund oder USAGE_ALARM für einen Wecker im Hintergrund haben. Audio-Flags haben keine Auswirkungen auf Vibrationen.

Amplitudensteuerung

Wenn ein Vibrator eine Amplitudenregelung hat, kann er Vibrationen mit unterschiedlicher Intensität ausführen. Dies ist eine wichtige Funktion für die Erzeugung von ausdrucksstarker Haptik und ermöglicht möglicherweise auch die Nutzersteuerung der Standardhaptikintensitäten.

Ob die Amplitudensteuerung unterstützt wird, kannst du mit Vibrator.hasAmplitudeControl prüfen. Wenn ein Vibrator keine Amplitude unterstützt, werden alle Amplitudenwerte als „Aus“ oder „An“ zugeordnet, je nachdem, ob sie null oder nicht null sind. Daher sollten Apps, die eine umfassende Haptik mit unterschiedlichen Amplituden verwenden, diese deaktivieren, wenn das Gerät keine Amplitudensteuerung hat.