Animações orientadas por gestos com use-gesture

@use-gesture/react é uma biblioteca de reconhecimento de gestos projetada para funcionar perfeitamente com react-spring. Ela reconhece gestos de arrastar, pinçar, rolar, passar o cursor, mover e girar a roda, fornecendo um estado de gesto normalizado que pode ser encaminhado diretamente às funções de atualização da mola para criar interações fluidas baseadas em física.

O gancho useDrag dispara uma função de retorno de chamada a cada evento de arrastar. A função recebe um objeto de estado do gesto com propriedades principais: movement (deslocamento total desde o início do arrasto), velocity (velocidade atual), direction (1 ou -1 em cada eixo), first (true no início do arrasto), last (true no fim do arrasto) e event (o evento bruto do DOM).

Todos os ganchos de use-gesture retornam uma função bind(). Chamar bind() retorna um objeto de propriedades de manipuladores de eventos (onPointerDown, onTouchStart etc.) que você expande no elemento que deseja tornar interativo. Esse é o ponto de ligação entre o reconhecedor de gestos e o seu elemento do DOM.

O padrão comum é criar uma mola com a API imperativa ([springs, api] = useSpring(...)) e então usar useDrag para chamar api.start({ x: movement[0], y: movement[1] }) a cada evento de arrasto. A mola acompanha suavemente o movimento do arrasto, adicionando uma física natural ao que, de outra forma, seria um rastreamento rígido do cursor.

Quando um arrasto termina (last: true no estado do gesto), normalmente você faz o elemento voltar à origem. Chame api.start({ x: 0, y: 0 }) dentro de uma verificação if (last). O react-spring anima o retorno com física de mola — um salto suave em vez de uma redefinição instantânea — proporcionando uma sensação física agradável à interação.

O valor de velocity no estado do gesto permite criar um comportamento de arremesso. Quando o usuário solta o elemento com alta velocidade, você pode lançá-lo na direção do arrasto em vez de fazê-lo voltar. Verifique if (last && velocity[0] > threshold) e então anime o elemento até sua posição final fora da tela. Isso é essencial para interações de deslizar para dispensar.

Para restringir o movimento de arrasto dentro de um contêiner, limite os valores de movimento antes de passá-los à mola: x: Math.max(-maxX, Math.min(maxX, movement[0])). Como alternativa, use a opção bounds integrada ao use-gesture: useDrag(handler, { bounds: { left: -100, right: 100 } }) para limitar automaticamente o estado do gesto.

Uma implementação móvel de deslizar para dispensar: use useDrag para acompanhar o movimento horizontal. Se o usuário soltar o elemento com velocidade acima de um limite OR tiver percorrido mais da metade da largura da tela, anime o cartão para fora da tela (api.start({ x: window.innerWidth })) e depois remova-o da lista. Caso contrário, faça-o voltar ao centro.

usePinch reconhece gestos de pinça com dois dedos em telas sensíveis ao toque e Ctrl+roda do mouse no computador. O estado do gesto inclui scale (nível atual de ampliação em relação ao início da pinça) e origin (ponto central da pinça). Conecte-o a uma mola que acompanhe a escala para criar interações de ampliação suaves e limitadas em imagens ou mapas.

useHover é acionado quando o ponteiro entra ou sai de um elemento, fornecendo um valor booleano active. useMove acompanha a posição do mouse dentro de um elemento, fornecendo coordenadas normalizadas. Ambos são úteis para efeitos magnéticos ao passar o cursor, nos quais os elementos se deslocam sutilmente em direção ao cursor conforme ele se aproxima.

Os ganchos de use-gesture podem ser compostos. Você pode usar useDrag e usePinch no mesmo elemento: const bindDrag = useDrag(...); const bindPinch = usePinch(...) e então expandir as duas funções bind: ...bindDrag() ...bindPinch(). O use-gesture diferencia automaticamente os tipos de gesto.

@use-gesture/react fornece useDrag, usePinch, useScroll, useHover e useMove. Cada gancho retorna uma função bind(), cuja expansão conecta os eventos de gesto aos elementos do DOM. O estado do gesto fornece movement, velocity, direction, first e last. Combine-o com a função imperativa api.start() do react-spring para criar animações interativas baseadas em física. Use velocity para arremessos e dispensas e bounds para limitar o movimento.