Adicionar retorno tátil a eventos

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

Esta página descreve três maneiras de fornecer retorno tátil.

• Use um View (recomendado). Essa abordagem é orientada para a ação, tem o maior suporte e não requer a permissão VIBRATE.
• Use um VibrationEffect predefinido. Essa abordagem tem mais flexibilidade, mas com algumas desvantagens.
• Usar composições avançadas com primitivas Esse método é mais novo e ainda mais flexível, mas exige suporte específico ao dispositivo.

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

Cuidado: não é recomendável usar métodos Vibrator mais antigos que empregam createOneshot ou createWaveform, mesmo que pareçam ter suporte do dispositivo. Esses modos geralmente são muito altos para o retorno tátil normal. Use-os somente como substitutos se precisar destacar uma ação extremamente importante.

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

Usar componentes View para gerar o retorno tátil

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

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

Pré-requisitos: ativar o retorno tátil

Se o View estiver visível, o retorno tátil poderá ser usado para os eventos. Alguns eventos, como o pressionamento longo, têm retorno tátil padrão que será acionado se um listener na visualização processar o evento (retornar true).

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

O método performHapticFeedback também respeita a configuração HAPTIC_FEEDBACK_ENABLED do sistema, o que permite que o usuário as desative em todo o sistema.

Ao contrário de outras APIs táteis, o uso de HapticFeedbackConstants com um View não requer 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 comportamento de substituição, se necessário. A única consideração é o nível do SDK da constante desejada.

Exemplo 1: pressionamento de tecla

Esse é um exemplo de como adicionar um retorno tátil a uma entrada por toque no View usando listeners de toque. Os efeitos simulam a sensação de pressionar e liberar 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 feedback tátil vão além de simular 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 uma REJECT pode ser um feedback mais forte para sinalizar falhas. Confira no exemplo a seguir o exemplo de um feedback do botão "Enviar".

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 o retorno tátil

A abordagem baseada em View se concentra na interação do usuário. É preferível para manter a consistência em todo o sistema. No entanto, APIs VibrationEffect predefinidas específicas também podem ser invocadas para efeitos personalizados de retorno tátil.

Os efeitos predefinidos estão disponíveis como constantes VibrationEffect. Eles podem ser verificados e usados com o serviço Vibrator, conforme mostrado nos exemplos abaixo.

Entender o suporte do dispositivo às APIs VibrationEffect

No uso básico, não é necessário verificar o suporte a 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, seu app ainda poderá reproduzi-lo e usar uma implementação de substituto definida pela plataforma.

Para mais detalhes, consulte VibrationEffect predefinido.

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

A maioria das vibrações pode ser tocada com o serviço Vibrator, que pode ser carregado desta forma:

Kotlin

import android.os.Vibrator

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

Java

import android.os.Vibrator;

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

O app precisa ter a permissão VIBRATE para vibrar o dispositivo usando esse serviço. A permissão pode ser adicionada ao arquivo de manifesto do aplicativo:

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

Tocar uma VibrationEffect predefinida

Atenção: seguindo as diretrizes, os efeitos precisam ser claros, e os pontos fortes deles precisam corresponder à importância. Se um efeito não estiver disponível, considere voltar a nada, em vez de uma alternativa discordante.

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

Este exemplo executa 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));

Usar composições avançadas com primitivos

A API VibrationEffect.Composition oferece mais possibilidades para o retorno tátil. No entanto, ao contrário dos efeitos, esses primitivos não têm substitutos no nível do sistema, o que significa que é preciso dar atenção especial aos primitivos e a outros recursos com suporte do dispositivo.

O uso dessas APIs é discutido em mais detalhes em Como criar efeitos táteis personalizados.