Cette section présente les différentes API haptiques disponibles dans Android. Il explique également quand et comment vérifier la compatibilité de l'appareil pour vous assurer que les effets haptiques fonctionnent comme prévu.
Il existe plusieurs façons de créer des effets haptiques. Il est important de tenir compte des principes de conception haptiques d'Android lorsque vous choisissez l'un d'entre eux. Le tableau suivant récapitule les attributs généraux de chaque approche:
- La disponibilité est particulièrement importante lorsque vous planifiez un comportement de remplacement. Elle doit être combinée à la vérification de la compatibilité de chaque appareil.
- Des retours haptiques clairs génèrent des sensations claires et propres qui sont moins troublantes pour les utilisateurs.
- Les retours haptiques enrichis sont plus expressifs et nécessitent souvent du matériel plus riche en fonctionnalités.
| Surface d'API | Disponibilité | Effacer le retour haptique | Retour haptique enrichi |
|---|---|---|---|
| HapticFeedbackConstants | Android 1.5 ou version ultérieure (par constante) |
||
| VibrationEffect prédéfini | Android 10 ou version ultérieure | ||
| Composition VibrationEffect | Android 11 ou version ultérieure (par constante) | ||
| Vibreur des modes Marche/Arrêt, one-shot et de la forme d'onde | Android 1 |
De plus, les API de notification, décrites sur cette page, vous permettent de personnaliser les effets haptiques des notifications entrantes.
Cette page décrit également d'autres concepts qui couvrent les surfaces de l'API:
- L'appareil est-il équipé d'un vibreur ?
- Le contrôle de l'amplitude permet des effets haptiques plus fluides et plus riches, mais n'est pas compatible avec tous les appareils.
VibrationAttributes()vous aide à classer les vibrations en fonction de leur utilisation. Cela permet de garantir que les paramètres utilisateur appropriés leur seront appliqués et d'éviter ainsi les surprises à l'utilisateur.
HapticFeedbackConstants
La classe HapticFeedbackConstants fournit des constantes basées sur les actions pour permettre aux applications d'ajouter un retour haptique cohérent sur l'ensemble de l'expérience sur l'appareil, plutôt que d'avoir des effets différents pour les actions courantes de chaque application.
Compatibilité et configuration requise
L'utilisation de la méthode View.performHapticFeedback avec ces constantes ne nécessite aucune autorisation spéciale pour l'application. Elle est soumise à la propriété View.hapticFeedbackEnabled, qui, si elle est définie sur false, désactive tous les appels de retour haptique sur la vue, y compris les appels par défaut.Le paramètre principal lié à la propriété View.hapticFeedbackEnabled, qui est défini sur false désactive tous les appels de retour haptique sur la vue, y compris les appels par défaut. Cette méthode respecte également le paramètre système de l'utilisateur concernant l'activation du retour tactile.
La seule considération de compatibilité est le niveau de SDK de la constante spécifique pour l'action.
Il n'est pas nécessaire de fournir un comportement de remplacement lorsque vous utilisez HapticFeedbackConstants.
Utilisation de HapticsFeedbackConstants
Pour en savoir plus sur l'utilisation de HapticFeedbackConstants, consultez la section Ajouter un retour haptique aux événements.
VibrationEffect prédéfini
La classe VibrationEffect fournit plusieurs constantes prédéfinies telles que CLICK, TICK et DOUBLE_CLICK. Ces effets peuvent être optimisés pour l'appareil.
Compatibilité et configuration requise
Pour lire un VibrationEffect, vous devez disposer de l'autorisation VIBRATE dans le fichier manifeste de l'application.
Il n'est pas nécessaire de fournir un comportement de remplacement lorsque vous utilisez des VibrationEffect prédéfinis, car les constantes sans implémentation optimisée pour les appareils reviennent à une plate-forme de remplacement standard.
Les API Vibrator.areEffectsSupported et Vibrator.areAllEffectsSupported permettent de déterminer s'il existe une implémentation optimisée pour les appareils.
Les effets prédéfinis peuvent toujours être utilisés sans implémentation optimisée et utilisent la plate-forme de remplacement standard. Par conséquent, ces API areEffectsSupported ne sont nécessaires que si une application souhaite déterminer si l'effet est optimisé pour l'appareil ou non.
Les méthodes de vérification d'effet peuvent renvoyer l'une des trois valeurs suivantes:
VIBRATION_EFFECT_SUPPORT_YESindique que l'appareil est compatible avec cet effet.VIBRATION_EFFECT_SUPPORT_NOindique que l'appareil n'a pas la compatibilité optimisée, mais qu'il utilise tout de même la plate-forme de remplacement.VIBRATION_EFFECT_SUPPORT_UNKNOWNindique que le système ne sait pas si l'implémentation est optimisée ou non.
Comme la valeur UNKNOWN indique que l'API de vérification n'est pas disponible, elle est généralement renvoyée pour tous les effets ou aucun d'entre eux. Ces appareils se rabattent de façon dynamique.
Utilisation des VibrationEffect prédéfinis
Pour en savoir plus sur l'utilisation d'un VibrationEffect prédéfini, consultez Utiliser un VibrationEffect prédéfini pour générer un retour haptique.
Composition de VibrationEffect
Une composition VibrationEffect est un effet de vibration créé à l'aide de l'API VibrationEffect.startComposition. Cette API permet un haptique enrichi expressif en créant une séquence de primitives avec des délais et des intensités personnalisés. Toutefois, assurez-vous que l'appareil est compatible avec les fonctionnalités combinées afin d'éviter une expérience globale incohérente.
Compatibilité et configuration requise
Pour lire un VibrationEffect, vous devez disposer de l'autorisation VIBRATE dans le fichier manifeste de l'application.
Tous les appareils ne sont pas compatibles avec toutes les fonctionnalités de l'API Composition. Il est important de s'assurer que les primitives sont disponibles.
Vérifier la compatibilité des primitives de vibration
La compatibilité par primitive peut être obtenue à l'aide de la méthode Vibrator.arePrimitivesSupported. Il est également possible de vérifier ensemble un ensemble de primitives à l'aide de la méthode Vibrator.areAllPrimitivesSupported. Cela équivaut à appliquer AND à la prise en charge par primitive.
Utilisation de VibrationEffect compositions
Pour en savoir plus sur l'utilisation des compositions VibrationEffect, consultez Créer des compositions vibreurs.
Vibration lors de la désactivation, de l'action one-shot et de la forme d'onde
La forme la plus ancienne de vibration compatible avec Android est les motifs simples d'activation et de désactivation du vibreur dont la durée est configurable. Ces API ne sont généralement pas adaptées aux principes de conception haptique, car elles peuvent générer des retours haptiques. Évitez-les, sauf en dernier recours.
Le cas d'utilisation le plus courant des vibrations est le suivant : les notifications, quoi qu'il en soit, un certain nombre de vibrations sont souhaités. Les vibrations de la forme d'onde permettent également de répéter un schéma indéfiniment, comme vous pouvez l'imaginer pour une sonnerie.
Un schéma one-shot consiste à vibrer une fois pendant N millisecondes.
Il existe deux types de formes d'onde:
- Durée uniquement. Ce type de forme d'onde décrit les durées alternées passées et les durées passées en pause. Les codes temporels commencent souvent par la durée passée. Par conséquent, les motifs de forme d'onde commencent souvent par une valeur nulle pour indiquer qu'il faut immédiatement commencer à vibrer.
- Chronologies et amplitudes. Ce type de forme d'onde dispose d'un tableau supplémentaire d'amplitudes à faire correspondre à chaque valeur de durée, plutôt que l'activation/la désactivation implicite de la première forme. Toutefois, il est important de vérifier que l'appareil est compatible avec le contrôle de l'amplitude afin de s'assurer que le scaling prévu peut être réalisé.
Compatibilité et configuration requise
Les vibrations marche/arrêt étant la forme la plus ancienne de vibrations, elles sont compatibles avec presque tous les appareils avec vibreur, comme décrit plus loin sur cette page.
Pour lire des appels de VibrationEffect ou de l'ancien style vibrate, vous devez disposer de l'autorisation VIBRATE dans le fichier manifeste de l'application.
Lorsque vous utilisez différentes valeurs d'amplitude dans une forme d'onde, nous vous recommandons vivement d'utiliser le contrôle de l'amplitude sur l'appareil.
Vérifier si le contrôle de l'amplitude est pris en charge
Les valeurs d'amplitude non nulles sont arrondies à 100% sur les appareils sans contrôle de l'amplitude. Il est donc important de vérifier si la compatibilité est présente à l'aide de Vibrator.hasAmplitudeControl. Pour en savoir plus, consultez la section sur la commande d'amplitude.
Vous devez soigneusement déterminer si la qualité de votre effet est suffisante sans contrôle de l'amplitude. Il peut être préférable de revenir à une vibration explicitement activée/désactivée.
Utilisation du vibreur
Dans les niveaux de SDK plus récents, tous les modes de vibration ont été regroupés en une seule classe VibrationEffect expressive, dans laquelle ces vibrations simples sont créées à l'aide de VibrationEffect.createOneshot ou VibrationEffect.createWaveform.
API de notification
Lorsque vous personnalisez les notifications de votre application, vous pouvez utiliser l'une des API suivantes pour associer un schéma à chaque canal de notification:
- AndroidX
- Android
Toutes ces formes suivent un schéma de forme d'onde marche/arrêt de base, comme décrit précédemment, dans lequel la première entrée correspond au délai d'activation du vibreur.
Concepts généraux
Plusieurs concepts s'appliquent aux surfaces de l'API décrites ci-dessus.
L'appareil est-il équipé d'un vibreur ?
Vous pouvez obtenir une classe Vibrator non nulle à partir de context.getSystemService(Vibrator.class). Si l'appareil n'a pas de vibreur, les appels aux API de vibration n'ont aucun effet. Les applications n'ont donc pas besoin de bloquer tous leurs retours haptiques en fonction d'une condition. Toutefois, si nécessaire, une application peut appeler hasVibrator() pour déterminer s'il s'agit d'un véritable vibreur (true) ou d'un bouchon (false).
L'utilisateur a-t-il désactivé les retours haptiques tactiles ?
Certaines implémentations personnalisées peuvent nécessiter de vérifier manuellement si l'utilisateur a entièrement désactivé le paramètre Retour tactile d'Android. Dans ce cas, les effets de retour tactile doivent être supprimés. Ce paramètre peut être interrogé à l'aide de la clé HAPTIC_FEEDBACK_ENABLED, où la valeur zéro signifie désactivée.
Attributs de vibration
Des attributs de vibration (actuellement sous la forme AudioAttributes) peuvent être fournis pour aider le système à déterminer l'objet de la vibration. Cela est nécessaire lorsque vous déclenchez une vibration lorsque votre application est en arrière-plan, car seuls le retour haptique attentionnel sont pris en charge pour l'utilisation en arrière-plan.
La création de AudioAttributes est décrite dans la documentation sur les classes et doit être considérée comme une vibration plutôt qu'un son.
À titre indicatif, dans la plupart des cas, le type de contenu est CONTENT_TYPE_SONIFICATION, et l'utilisation peut être des valeurs telles que USAGE_ASSISTANCE_SONIFICATION pour le retour tactile au premier plan ou USAGE_ALARM pour une alarme en arrière-plan. Les indicateurs audio n'ont aucun effet sur les vibrations.
Contrôle de l'amplitude
Si un vibreur dispose d'un contrôle de l'amplitude, il peut transmettre des vibrations avec différentes intensités. Cette fonctionnalité est importante pour produire des retours haptiques riches et permettre potentiellement à l'utilisateur de contrôler les intensités haptiques par défaut.
Vous pouvez vérifier la compatibilité du contrôle de l'amplitude en appelant Vibrator.hasAmplitudeControl. Si un vibreur n'est pas compatible avec l'amplitude, toutes les valeurs d'amplitude seront mappées à "désactivé/activé" selon qu'elles sont nulles ou non nulles. Par conséquent, les applications utilisant des technologies haptiques riches avec des amplitudes variables doivent envisager de les désactiver si l'appareil n'a pas le contrôle de l'amplitude.