Documentation 7 min read

Simple Gesture Detector

Gesture Mobile Touch Screen

Published: April 21, 2025

Visão Geral

O Simple Gesture Detector é uma biblioteca JavaScript poderosa e flexível projetada para facilitar o reconhecimento e a manipulação de gestos de toque e mouse em elementos da web. Com suporte para uma ampla gama de gestos, incluindo toques, deslizes, pinçamentos, rotações, arrastos e muito mais, o Simple Gesture Detector permite que desenvolvedores criem interfaces de usuário interativas e responsivas de maneira eficiente.

Este plugin é altamente configurável, permitindo ajustes finos na sensibilidade dos gestos e na forma como eles são detectados. Além disso, ele suporta modificadores de teclado para interações mais complexas, tornando-o ideal para aplicações web modernas que exigem interações ricas e dinâmicas.

Recursos

  • Detecção de uma variedade de gestos de toque e mouse, incluindo swipe, tap, double tap, long press, pinch, rotate e drag.
  • Configuração personalizável para ajustar a sensibilidade e os parâmetros dos gestos.
  • Suporte para eventos com modificadores de teclado, permitindo interações complexas.
  • Mecanismo de eventos eficiente com throttling para otimizar o desempenho.
  • Compatibilidade com navegadores modernos e fallback para navegadores mais antigos.
  • Facilidade de integração com outras bibliotecas e frameworks.
  • API simples para adicionar e remover handlers de eventos de gestos.

Instalação

Para instalar o Simple Gesture Detector, siga os passos abaixo:

  • Inclua o script JavaScript no seu HTML antes do fechamento da tag </body>:
<script src="https://cdn.alphasystem.dev/plugins/simple-gesture-detector/latest/script-min.js"></script>
  • Adicione um elemento no qual os gestos serão detectados:
<div id="gesture-area">Interaja comigo com gestos!</div>
  • Inicialize o Simple Gesture Detector no seu script JavaScript, definindo as opções desejadas:
const gestureArea = document.getElementById('gesture-area');
const options = {
  swipe: {
    distance: 50,
    time: 400,
    flickVelocity: 0.8
  },
  doubleSwipe: {
    time: 300
  },
  drag: {
    distance: 15
  },
  throttleInterval: 20,
  passive: true
};
const gesture = SimpleGestureDetector(gestureArea, options);
gesture.on('swipeleft', (event) => {
  console.log('Swipe para a esquerda detectado!', event);
});
gesture.on('tap', (event) => {
  console.log('Tap detectado!', event);
});

Observação: O SimpleGestureDetector deve ser chamado como uma função, sem utilizar o operador new. Instanciar com new SimpleGestureDetector() pode causar erros de execução.

Uso

Após a instalação, você pode utilizar o Simple Gesture Detector para detectar e responder a diversos gestos. A seguir, alguns exemplos de como utilizar os principais recursos:

Detectar Swipes

Os nomes dos eventos são sensíveis a maiúsculas e minúsculas. Note que os eventos específicos de input (touch ou mouse) são gerados concatenando 'swipe' + o tipo de input + a direção, onde a direção inicia com letra maiúscula. Por exemplo, para um swipe para a esquerda com toque, o evento será swipetouchLeft.

gesture.on('swipeleft', function (e) {
  console.log('Swiped Left (All Inputs)', e);
});

// Eventos específicos de input com a capitalização correta:
gesture.on('swipetouchLeft', function (e) {
  console.log('Swiped Left (Touch)', e);
});
gesture.on('swipemouseLeft', function (e) {
  console.log('Swiped Left (Mouse)', e);
});

gesture.on('swiperight', function (e) {
  console.log('Swiped Right (All Inputs)', e);
});

gesture.on('swipetouchRight', function (e) {
  console.log('Swiped Right (Touch)', e);
});

gesture.on('swipemouseRight', function (e) {
  console.log('Swiped Right (Mouse)', e);
});

gesture.on('swipeup', function (e) {
  console.log('Swiped Up (All Inputs)', e);
});

gesture.on('swipetouchUp', function (e) {
  console.log('Swiped Up (Touch)', e);
});

gesture.on('swipemouseUp', function (e) {
  console.log('Swiped Up (Mouse)', e);
});

gesture.on('swipedown', function (e) {
  console.log('Swiped Down (All Inputs)', e);
});

gesture.on('swipetouchDown', function (e) {
  console.log('Swiped Down (Touch)', e);
});

gesture.on('swipemouseDown', function (e) {
  console.log('Swiped Down (Mouse)', e);
});

gesture.on('doubleswipeleft', function (e) {
  console.log('Double Swiped Left', e);
});

gesture.on('doubleswiperight', function (e) {
  console.log('Double Swiped Right', e);
});

gesture.on('swipeleftwithmodifiers', function (e) {
  console.log('Swiped Left with Modifiers:', e.modifiers);
});

gesture.on('swiperightwithmodifiers', function (e) {
  console.log('Swiped Right with Modifiers:', e.modifiers);
});

Detectar Flick

gesture.on('flickleft', function (e) {
  console.log('Flicked Left', e);
});

gesture.on('flickright', function (e) {
  console.log('Flicked Right', e);
});

gesture.on('flickup', function (e) {
  console.log('Flicked Up', e);
});

gesture.on('flickdown', function (e) {
  console.log('Flicked Down', e);
});

Detectar Pinch e Rotate

gesture.on('pinch', (event) => {
  console.log('Pinch detectado! Escala:', event.scale);
});

gesture.on('rotate', (event) => {
  console.log('Rotação detectada! Ângulo:', event.rotation);
});

Detectar Tap e Double Tap

gesture.on('tap', function (e) {
  console.log('Tap', e);
});

gesture.on('doubletap', function (e) {
  console.log('Double Tap', e);
});

gesture.on('longpress', function (e) {
  console.log('Long Press', e);
});

Detectar Drag

gesture.on('dragstart', (event) => {
  console.log('Início do drag!', event);
});

gesture.on('drag', (event) => {
  console.log('Drag em andamento:', event.x, event.y);
});

gesture.on('dragend', (event) => {
  console.log('Drag finalizado!', event);
});

Configuração

O Simple Gesture Detector pode ser configurado para atender às necessidades específicas do seu projeto. As opções de configuração permitem ajustar a sensibilidade dos gestos, definir intervalos de throttling e controlar o comportamento de eventos passivos.

Opções Disponíveis

  • swipe: Define os parâmetros para detecção de swipes.
    • distance: Distância mínima em pixels para considerar um swipe.
    • time: Tempo máximo em milissegundos para detectar um swipe.
    • flickVelocity: Velocidade mínima para considerar um gesto como flick.
  • doubleSwipe: Define o intervalo de tempo para detectar double swipes.
    • time: Tempo máximo em milissegundos entre dois swipes para considerar um double swipe.
  • drag: Define a sensibilidade para detecção de drag.
    • distance: Distância mínima em pixels para iniciar um drag.
  • throttleInterval: Intervalo de throttling em milissegundos para otimizar o desempenho dos eventos.
  • passive: Define se os eventos de toque devem ser passivos, melhorando a performance.

Exemplo de Configuração

const options = {
  swipe: {
    distance: 50,
    time: 400,
    flickVelocity: 0.8
  },
  doubleSwipe: {
    time: 300
  },
  drag: {
    distance: 15
  },
  throttleInterval: 20,
  passive: true
};
const gesture = SimpleGestureDetector(element, options);

Referência da API

O Simple Gesture Detector expõe uma API simples para inicializar a detecção de gestos e manipular eventos associados. A seguir, detalhes das funções principais disponíveis:

Função: SimpleGestureDetector

Inicializa a detecção de gestos em um elemento específico.

Parâmetros

  • element: Element - O elemento DOM no qual os gestos serão detectados. Se não for fornecido ou inválido, o documento inteiro será usado.
  • options: Object (opcional) - Objeto de configuração para ajustar a sensibilidade e comportamento dos gestos.

Exemplo de Uso

const gesture = SimpleGestureDetector(document.getElementById('gesture-area'), options);

Métodos

on

Adiciona um handler para um gesto específico.

Parâmetros
  • gesture: String - Nome do gesto para o qual adicionar o handler (e.g., 'swipeleft', 'tap', 'pinch'). Pode incluir um namespace opcional separado por ponto (e.g., 'swipeleft.myNamespace').
  • handler: Function - Função a ser chamada quando o gesto é detectado.

off

Remove um handler para um gesto específico.

Parâmetros
  • gesture: String - Nome do gesto do qual remover o handler. Pode incluir um namespace opcional separado por ponto (e.g., 'swipeleft.myNamespace').
  • handler: Function (opcional) - Função específica a ser removida. Se não for fornecida, todos os handlers para o gesto e namespace especificados serão removidos.

Exemplo de Uso

// Adicionar handler
gesture.on('tap', handleTap);

// Adicionar handler com namespace
gesture.on('swipeleft.myNamespace', handleSwipeLeft);

// Remover handler específico
gesture.off('tap', handleTap);

// Remover todos os handlers para 'swipeleft' com namespace 'myNamespace'
gesture.off('swipeleft.myNamespace');

// Remover todos os handlers para 'swipeleft' independente do namespace
gesture.off('swipeleft');

Eventos Suportados

A seguir, uma lista de todos os eventos que podem ser manipulados usando os métodos on e off. Além dos eventos genéricos, o detector dispara eventos específicos de input (touch e mouse) com nomenclatura sensível a maiúsculas e minúsculas, por exemplo, swipetouchLeft ou swipemouseRight.

  • Swipe Gestures: swipeleft, swiperight, swipeup, swipedown
  • Eventos específicos de input: swipetouchLeft, swipemouseLeft, swipetouchRight, swipemouseRight, swipetouchUp, swipemouseUp, swipetouchDown, swipemouseDown
  • Flick Gestures: flickleft, flickright, flickup, flickdown
  • Double Swipe Gestures: doubleswipeleft, doubleswiperight
  • Swipe com Modificadores: swipeleftwithmodifiers, swiperightwithmodifiers
  • Tap Gestures: tap, doubletap, longpress
  • Drag Gestures: dragstart, drag, dragend
  • Pinch e Rotate: pinch, rotate

Cada evento fornece um objeto de evento com propriedades detalhadas sobre a interação, como posição, velocidade, ângulo, tipo de entrada e modificadores de teclado ativos.

Solução de Problemas

Se você encontrar problemas ao usar o Simple Gesture Detector, considere as seguintes etapas de solução de problemas:

  • Gestos não estão sendo detectados: Verifique se o script foi incluído corretamente e se o elemento alvo está correto. Utilize o console do navegador para identificar possíveis erros.
  • Handlers de eventos não estão sendo acionados: Assegure-se de que os handlers foram adicionados corretamente e que os nomes dos gestos estão escritos com a capitalização correta. Lembre-se de que os nomes são sensíveis a maiúsculas e minúsculas. Por exemplo, se o evento disparado for swipetouchLeft, registrá-lo como swipetouchleft não funcionará.
  • Desempenho lento: Ajuste o throttleInterval nas opções de configuração para otimizar o desempenho. Valores menores podem aumentar a responsividade, mas consumir mais recursos.
  • Compatibilidade com navegadores: Certifique-se de que você está usando um navegador compatível e que as APIs necessárias estão suportadas. A biblioteca inclui um polyfill para Object.assign, mas outros recursos podem variar.
  • Eventos com modificadores não funcionam corretamente: Verifique se as teclas modificadoras estão sendo capturadas corretamente e se os handlers estão implementados conforme esperado. Lembre-se de que apenas Shift, Ctrl, Alt e Meta são reconhecidos como modificadores.
  • Inicialização incorreta: Assegure-se de chamar o SimpleGestureDetector como uma função sem o operador new. Utilizar new SimpleGestureDetector() pode causar erros de execução.