Android Haptik API-Referenz

In diesem Dokument werden die verschiedenen in Android verfügbaren Haptik-APIs vorgestellt. Außerdem wird erläutert, wie Sie verschiedene Haptikeffekte erstellen und wie Sie prüfen, ob die erforderliche Geräteunterstützung vorhanden ist. keywords_public: > Android, Haptik, APIs, Vibration, HapticFeedbackConstants, VibrationEffect, Haptik mit Hüllkurve, haptisches Feedback, Benachrichtigung, Amplitudensteuerung

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 beabsichtigt 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.
  • Klare Haptik sind präzise 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 Haptik löschen Umfangreiche Haptik
HapticFeedbackConstants Android 1.5+
(per constant)
Vordefinierter VibrationEffect Android 10 und höher
VibrationEffect Komposition (bevorzugt) Android 16 und höher (4. Quartal 2026)
Zusammensetzung von VibrationEffect-Primitiven Android 11 und höher (pro 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 auf die API-Oberflächen beziehen:

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 View.performHapticFeedback-Methode mit diesen Konstanten sind keine besonderen Berechtigungen für die App erforderlich. Sie unterliegt der Eigenschaft View.hapticFeedbackEnabled. Wenn diese auf false festgelegt 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 festgelegt 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 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 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 Standardplattform-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. In diesem Fall 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 Auswirkungen 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.

Hüllkurven-Vibrationseffekt

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 haptische Wahrnehmung reibungslos und nahtlos ist, müssen Umschlagseffekte 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 sanfte Übergänge zu sorgen.

Damit Sie die Wellenform-Hüllkurven-Effekte Ihrer App optimieren und die Kompatibilität auf verschiedenen Geräten gewährleisten können, 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 Stützpunkten ab, die für einen Envelope-Effekt unterstützt werden.
getMinControlPointDurationMillis()
Ruft die unterstützte Mindestdauer in Millisekunden zwischen zwei Kontrollpunkten innerhalb eines Hüllkurveneffekts ab.
getMaxControlPointDurationMillis()
Ruft die maximal unterstützte Dauer in Millisekunden zwischen zwei Kontrollpunkten in einem Envelope-Effekt 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 Gefühl des Designs so weit wie möglich beizubehalten.

Verwendung von „Envelope VibrationEffects“

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

VibrationEffect-Komposition

Ab Android 16 (4. Quartal 2025) ist VibrationEffect.Builder die bevorzugte API zum Erstellen komplexer, ausdrucksstarker haptischer Effekte durch die Sequenzierung mehrerer haptischer Elemente entlang einer entworfenen Zeitachse. Sie ersetzt VibrationEffect.Composition und bietet eine zeitachsenbasierte Planung, atomare Kapselung, Unterstützung für gemischte Ereignisse (Kombination von Presets und Envelopes) sowie ein integriertes automatisches Fallback.

Bausteine

Mit dem Builder können Sie die folgenden haptischen Elemente sequenzieren:

  • VibrationEffect.Preset: Vordefinierte haptische Empfindungen, die häufige kurze Impulse darstellen, z. B. PRESET_CLICK, PRESET_TICK und PRESET_LOW_TICK. Voreinstellungen ersetzen die kurzen Primitiven aus der VibrationEffect.Composition API. Für längere, kontinuierliche oder ansteigende Effekte (die zuvor mit „rise“, „fall“ und anderen Primitiven behandelt wurden) verwenden Sie stattdessen Umschläge (PWLE). Voreinstellungen können mit Preset.create(presetId, scale) von 0.0f bis 1.0f skaliert werden.
  • VibrationEffect.Envelope: Stückweise lineare Hüllkurven (Piecewise Linear Envelopes, PWLEs), die entweder mit BasicEnvelopeBuilder (mit Intensität und Schärfe) oder WaveformEnvelopeBuilder (mit Frequenz und Amplitude) erstellt wurden. Umschläge werden mit Envelope.create(builder) erstellt.
  • VibrationEffect.Event: Zeitachse-Ereignisse, die mit getEvents() aus einem vorhandenen VibrationEffect abgerufen wurden. Sie können mit addEvents(startTimeShiftMillis, events) einen Zeitachsen-Offset hinzufügen.

Zeitachse planen und validieren

Jedes Element wird dem Builder mit einem startTimeMillis hinzugefügt, das den zeitlichen Versatz (in Millisekunden) seit Beginn der Komposition darstellt:

  • Validierung zur Build-Zeit:Elemente müssen in streng aufsteigender Reihenfolge ihrer Startzeiten hinzugefügt werden. Der Builder führt zur Build-Zeit eine Best-Effort-Validierung durch, indem er die Mindestdauer prüft (z. B. 1 ms für Presets oder bekannte Dauern für Hüllkurven). Wenn zur Build-Zeit eine Überschneidung erkannt wird, wird eine IllegalArgumentException ausgelöst.
  • Wiedergabe-Timing-Abstimmung:Das Framework bietet während der Wiedergabe eine bestmögliche Unterstützung für das Timing. Wenn ein vorheriges Ereignis noch ausgeführt wird, wenn die Startzeit des nächsten geplanten Ereignisses erreicht ist, verschiebt das Framework das nachfolgende Ereignis automatisch auf den nächsten frühestmöglichen Zeitraum. So wird verhindert, dass sich Ereignisse bei der physischen Wiedergabe überschneiden, und gleichzeitig dafür gesorgt, dass keine haptischen Ereignisse verloren gehen.

Wiederholte Effekte

Mit setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis) kann der Komposition ein sich wiederholender Effekt hinzugefügt werden. Sobald ein sich wiederholender Effekt konfiguriert ist, dürfen dem Builder keine zusätzlichen Elemente mehr hinzugefügt werden.

Fallback-Unterstützung

Die automatische Fallback-Unterstützung auf Framework-Ebene ist standardmäßig für Vibrationen aktiviert, die von VibrationEffect.Builder erstellt werden:

  • Transparenter Plattform-Fallback:Wenn ein Gerät eine angeforderte Preset oder eine einfache Envelope nicht unterstützt, ersetzt das Framework das nicht unterstützte Element zur Laufzeit automatisch durch eine geeignete unterstützte Vibration. Ihre App muss die Gerätefunktionen (z. B. isPresetSupported) nicht manuell prüfen, bevor sie mit VibrationEffect.Builder erstellte Kompositionen wiedergibt.
  • Ausnahme für WaveformEnvelopeBuilder:Für Hüllkurven-Effekte, die durch WaveformEnvelopeBuilder erstellt wurden (mit absoluten physischen Frequenzen in Hertz und Amplituden in G), gibt es keine automatische Fallback-Unterstützung. Da erweiterte PWLEs auf bestimmten Hardware-Frequenzkurven (FOAM) basieren, würde ein automatischer Ersatz die Designabsicht beeinträchtigen. Wenn das Gerät keine PWLE-Effekte oder die angeforderten Frequenzen unterstützt, werden solche Vibrationen nicht wiedergegeben. Für universelle Kompatibilität empfiehlt sich BasicEnvelopeBuilder.

Nutzung von VibrationEffect.Builder

Codebeispiele zum Erstellen von Effekten mit VibrationEffect.Builder finden Sie unter Mit VibrationEffect.Builder zeitachsenbasierte Kompositionen erstellen.

VibrationEffect Zusammensetzung von Primitiven

Eine Komposition von VibrationEffect-Primitiven ist ein Vibrationseffekt, der mit der VibrationEffect.startComposition API erstellt wurde. Mit dieser API können Sie eine Sequenz von Primitiven erstellen.

Kompatibilität und Anforderungen

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

Unterstützung von Primitiven prüfen

Wenn Sie die VibrationEffect.Composition API verwenden, müssen Sie daher vor dem Abspielen die Unterstützung pro Primitiv mit Vibrator.arePrimitivesSupported oder Vibrator.areAllPrimitivesSupported prüfen.

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

Verwendung von VibrationEffect-Primitivkompositionen

Weitere Informationen zur Verwendung von VibrationEffect-Primitivkompositionen finden Sie unter Vibrationsprimitivkompositionen erstellen.

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

Die älteste Form der Vibration, die unter Android unterstützt wird, sind einfache Vibrator-Ein/Aus-Muster mit konfigurierbaren Dauern. Diese APIs sind in der Regel nicht gut auf die Designprinzipien für Haptik abgestimmt, 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- und Ausschalten von Vibrationen sind Benachrichtigungen, bei denen in jedem Fall eine Vibration gewünscht wird. Wellenform-Vibrationen ermöglichen es außerdem, ein Muster unendlich oft zu wiederholen, was sich für einen Klingelton anbietet.

Ein One-Shot-Muster bezieht sich auf eine einmalige Vibration für N Millisekunden.

Es gibt zwei Arten von Wellenform-Mustern:

  • 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 ausgeschaltet ist. Daher beginnen Wellenformmuster oft mit dem Wert „0“, um anzuzeigen, dass das Gerät sofort vibrieren soll.
  • Zeitabläufe 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- und Ausschalten von Vibrationen die älteste Form von Vibrationen 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-Aufrufen im alten Stil 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.

Prüfen, ob die Amplitudensteuerung unterstützt wird

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.

Vibrationsmuster für Ein/Aus verwenden

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 Benachrichtigungschannel 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 abrufen, die nicht null ist, indem Sie context.getSystemService(Vibrator.class) verwenden. 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 möglicherweise manuell geprüft werden, ob der Nutzer die Android-Einstellung Haptisches Feedback vollständig deaktiviert hat. In diesem Fall sollten die Effekte für haptisches Feedback unterdrückt werden. Diese Einstellung kann mit dem Schlüssel HAPTIC_FEEDBACK_ENABLED abgefragt werden. Ein Wert von null bedeutet, dass die Einstellung 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 zugehörigen 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 haptisches Feedback 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 unterschiedlicher Stärke ausführen. Dies ist eine wichtige Funktion für die Erzeugung von taktilen Rückmeldungen und ermöglicht möglicherweise auch die Nutzersteuerung der standardmäßigen Intensitäten.

Die Unterstützung der Amplitudensteuerung kann durch Aufrufen von Vibrator.hasAmplitudeControl geprüft werden. Wenn ein Vibrator keine Amplituden unterstützt, werden alle Amplitudenwerte je nach dem, 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 Hüllkurven-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 auf der Hüllkurve basierende Vibrationen ignoriert.