Adicionar retorno tátil a eventos

Um dos casos de uso mais básicos do retorno tátil é fornecer feedback para interações do usuário. Os seletores de tempo, o pressionamento de tecla em um teclado virtual e a seleção de texto são exemplos comuns de bons casos de uso para o retorno tátil. Para mais informações sobre quando e como aplicar o retorno tátil, leia os Princípios de design tátil.

Nesta página, descrevemos três maneiras de fornecer retorno tátil.

Esses métodos usam primitivos definidos no nível do dispositivo para fornecer feedback de alta qualidade adaptado ao dispositivo em questão.

Por padrão, todos os métodos de retorno tátil respeitam as configurações de feedback de toque do usuário.

Usar componentes View para gerar retorno tátil

Use o método View.performHapticFeedback para gerar retorno tátil. As constantes hápticas definidas pelo HapticFeedbackConstants se concentram na funcionalidade em um aplicativo, não no tipo de efeito háptico realizado.

A implementação subjacente pode variar dependendo do dispositivo e dos recursos de hardware, mas o app só precisa considerar o tipo de feedback a ser fornecido em um contexto específico. Ao se concentrar na funcionalidade, você pode ativar o feedback háptico para interações semelhantes. Com o tempo, os usuários aprendem a associar diferentes significados a diferentes sensações táteis.

Pré-requisitos: ativar o feedback tátil

Enquanto o View estiver visível, o retorno tátil poderá ser usado para os eventos dele. Alguns eventos, como tocar e pressionar, têm retorno tátil padrão que são acionados se um listener na visualização processar o evento (retornar true).

Um View do Android pode desativar o retorno tátil definindo a propriedade View.hapticFeedbackEnabled como false. Desativar essa propriedade resulta em feedback padrão.

O método performHapticFeedback também respeita a configuração do sistema HAPTIC_FEEDBACK_ENABLED, que permite ao usuário desativá-las para todo o sistema.

Ao contrário de outras APIs hápticas, o uso de HapticFeedbackConstants com um View não exige a permissão VIBRATE.

Escolha um HapticFeedbackConstant

Ao usar componentes View com HapticFeedbackConstants, não é necessário avaliar o suporte a dispositivos específicos, já que essas constantes terão um comportamento de substituição, se necessário. A única consideração é o nível do SDK da constante desejada.

Exemplo 1: pressionamento de tecla

Este é um exemplo de como adicionar um retorno tátil a uma entrada por toque em View usando listeners de toque. Os efeitos simulam a sensação de pressionar e soltar um botão.

Kotlin

class HapticTouchListener : View.OnTouchListener {
  override fun onTouch(View view, MotionEvent event) : Boolean {
    when (event.actionMasked) {
      MotionEvent.ACTION_DOWN ->
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY)
      MotionEvent.ACTION_UP ->
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY_RELEASE)
    }
    return true
  }
}

Java

class HapticTouchListener implements View.OnTouchListener {
  @Override
  public boolean onTouch(View view, MotionEvent event) {
    switch (event.getAction()) {
      case MotionEvent.ACTION_DOWN:
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY);
        break;
      case MotionEvent.ACTION_UP:
        view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY_RELEASE);
        break;
    }
    return true;
  }
}

Exemplo 2: botão "Enviar"

Os casos de uso de retorno tátil vão além da simulação de uma interação física com o dispositivo. Eles também podem ser usados para transmitir um significado abstrato. Por exemplo, a expectativa geral para um efeito CONFIRM é uma vibração curta e leve, enquanto um REJECT pode ser um feedback mais forte para sinalizar uma falha. Isso é ilustrado no exemplo a seguir para um feedback de botão de envio.

Kotlin

submitButton.setOnClickListener { view ->
  val successful = performSubmit()
  if (successful) {
    view.performHapticFeedback(HapticFeedbackConstants.CONFIRM)
  } else {
    view.performHapticFeedback(HapticFeedbackConstants.REJECT)
  }
}

Java

submitButton.setOnClickListener(view -> {
  boolean successful = performSubmit();
  if (successful) {
    view.performHapticFeedback(HapticFeedbackConstants.CONFIRM);
  } else {
    view.performHapticFeedback(HapticFeedbackConstants.REJECT);
  }
});

Usar um VibrationEffect predefinido para gerar retorno tátil

Usar a abordagem baseada em View se concentra na interação do usuário. Portanto, prefira essa opção para manter a consistência em todo o sistema. No entanto, também é possível invocar APIs VibrationEffect predefinidas específicas para efeitos de retorno tátil personalizados.

Os efeitos predefinidos estão disponíveis como VibrationEffect constantes e podem ser verificados para suporte e reproduzidos com o serviço Vibrator, conforme mostrado nos exemplos a seguir.

Entender o suporte a dispositivos das APIs VibrationEffect

No uso básico, não é necessário verificar a compatibilidade de APIs VibrationEffect individuais. As APIs, como Vibrator.areEffectsSupported e Vibrator.areAllEffectsSupported, são usadas para determinar se o dispositivo tem uma implementação personalizada da constante. Se um efeito personalizado não estiver presente, o app ainda poderá reproduzir os efeitos e usar uma implementação de substituição definida pela plataforma.

Para mais detalhes, consulte Predefinido VibrationEffect.

Pré-requisitos: carregar o vibrador e a permissão VIBRATE

A maioria das vibrações pode ser reproduzida com o serviço Vibrator, que pode ser carregado da seguinte maneira:

Kotlin

import android.os.Vibrator

val vibrator = context.getSystemService(Vibrator::class.java)

Java

import android.os.Vibrator;

Vibrator vibrator = context.getSystemService(Vibrator.class);

Seu app precisa ter a permissão VIBRATE para vibrar o dispositivo usando esse serviço. É possível adicionar essa permissão ao arquivo de manifesto do aplicativo:

<uses-permission android:name="android.permission.VIBRATE"/>

Tocar um VibrationEffect predefinido

Os efeitos predefinidos podem ser preparados usando VibrationEffect.createPredefined e reproduzidos com um dos métodos vibrate em Vibrator.

Este exemplo reproduz um efeito de clique.

Kotlin

val vibrator = context.getSystemService(Vibrator::class.java)
...
// Requires VIBRATE permission
vibrator.vibrate(VibrationEffect.createPredefined(VibrationEffect.EFFECT_CLICK))

Java

Vibrator vibrator = context.getSystemService(Vibrator.class);
...
// Requires VIBRATE permission
vibrator.vibrate(VibrationEffect.createPredefined(VibrationEffect.EFFECT_CLICK));

Use VibrationEffect.Builder para criar composições

A partir do Android 16 (4º trimestre de 2026), a API VibrationEffect.Builder oferece a maneira mais flexível e expressiva de criar retorno tátil personalizado sequenciando predefinições, envelopes e outros elementos de vibração discretos ao longo de uma linha do tempo. Além disso, as composições criadas com VibrationEffect.Builder têm suporte de substituição automática integrado em todos os elementos compatíveis.

A criação de efeitos táteis com VibrationEffect.Builder (e a API VibrationEffect.Composition) é discutida em mais detalhes em Criação de efeitos táteis personalizados.