Recomposed
Gesture

Detectando Entrada de Toque no Compose: Gestos de Tap, Drag e Transform

Oct 26, 2026 · 4 min read

Detectando Entrada de Toque no Compose: Gestos de Tap, Drag e Transform

A intuição

Todo gesto de toque no Compose começa da mesma forma: um bloco Modifier.pointerInput e uma função suspend que você passa para ele. O que muda é qual função, porque cada uma é um loop feito sob medida sobre o mesmo fluxo bruto de eventos de ponteiro, moldado para um tipo específico de gesto.

Escolha a errada e você acaba brigando com a API (fazendo parsing manual de offsets brutos para detectar um tap) ou recebe dados que você nem pediu (valores de rotação para um gesto que é só um drag).

  • detectTapGestures para um único ponto que não se move: tap, double-tap, long-press.
  • detectDragGestures (e seus parentes horizontal/vertical) para um único ponto que se move, uma direção por vez.
  • detectTransformGestures para dois ou mais dedos ao mesmo tempo: pinch, pan, rotate.

Tap, double-tap, long-press: detectTapGestures

Modifier.pointerInput(Unit) {
    detectTapGestures(
        onTap = { /* tap único */ },
        onDoubleTap = { /* segundo tap dentro da janela do double-tap */ },
        onLongPress = { /* mantido além do limiar do long-press */ },
        onPress = { /* disparado a cada press down, antes do Compose saber
                       em qual gesto isso vai se resolver */ }
    )
}

onPress é uma lambda de PressGestureScope, então ela recebe awaitRelease() e tryAwaitRelease(), detecção de liberação sem bloquear os outros callbacks, útil para um feedback do tipo "pressionar e manter".

Apenas os callbacks que você passar são conectados. Passar só onTap significa que o Compose nunca se preocupa em esperar a janela do double-tap, então um tap isolado se resolve imediatamente em vez de esperar para ver se um segundo tap vem a seguir.

Use isso em vez de Modifier.clickable quando precisar de algo que ele não expõe: double-tap para curtir, um menu de contexto por long-press, uma escala ou mudança de cor no estado de pressão que você controla por conta própria.

Não empilhe isso sobre o clickable

Adicionar detectTapGestures a um nó que já tem Modifier.clickable/combinedClickable instala dois detectores de gesto concorrentes no mesmo fluxo de ponteiro, e você perde o ripple e a semântica de acessibilidade que o clickable te dá de graça. Escolha um.

Drag de eixo único: detectDragGestures e seu par horizontal/vertical

Modifier.pointerInput(Unit) {
    detectDragGestures(
        onDragStart = { offset -> /* dedo se moveu além do touch slop */ },
        onDrag = { change, dragAmount -> change.consume() /* dragAmount: Offset, ambos os eixos */ },
        onDragEnd = { /* dedo levantado */ },
        onDragCancel = { /* gesto interrompido, ex.: outro ponteiro assumiu */ }
    )
}

onDrag te entrega um PointerInputChange mais um dragAmount: Offset, o delta desde o último evento, não a distância total do drag. Você mesmo chama change.consume(); o detectDragGestures não reivindica o gesto por você.

Um drag não consumido vaza para o pai

Pular o change.consume() não só faz o gesto parecer lento. Um scrollable/verticalScroll pai mais acima na árvore nunca fica sabendo que o ponteiro já foi reivindicado, e rola ao mesmo tempo que o seu drag.

detectHorizontalDragGestures e detectVerticalDragGestures têm o mesmo formato, menos uma dimensão: onHorizontalDrag/onVerticalDrag te entregam um delta Float em vez de um Offset, e só o daquele eixo precisa ser superado para iniciar o gesto. Use essas versões em vez da versão de dois eixos sempre que o gesto for genuinamente unidirecional (uma linha deslizável, um slider vertical), para que um movimento diagonal do dedo não ganhe o gesto no eixo errado, e para que uma lista vertical acima dela ainda consiga rolar normalmente.

Pinch, pan, rotate: detectTransformGestures

Modifier.pointerInput(Unit) {
    detectTransformGestures(
        panZoomLock = false
    ) { centroid, pan, zoom, rotation ->
        /* centroid: Offset, ponto médio entre os ponteiros ativos
           pan: Offset, deslocamento desde o último evento
           zoom: Float, fator de escala desde o último evento (1f = inalterado)
           rotation: Float, graus desde o último evento */
    }
}

é o motivo pelo qual detectTransformGestures recebe um único callback em vez de quatro: pan, zoom e rotation não são gestos separados, são três números que o Compose deriva do mesmo evento multi-ponteiro a cada frame, então não há nada a resolver como existe entre um tap e um long-press.

panZoomLock = true faz o oposto do que o nome sugere: ele trava a rotação, não o pan ou o zoom. Qualquer limiar que o gesto cruzar primeiro decide seu formato para o resto do gesto; pan/zoom primeiro significa que a rotação permanece em 0f a partir daí. Útil para um visualizador de imagem ou mapa com pinch-to-zoom, onde você quer pan e zoom mas não quer que dois dedos pinçando também sejam lidos como uma rotação acidental. Uma ferramenta de recorte que combina os três em um único gesto é o caso para deixar como false.

zoom e rotation são deltas, não totais

zoom e rotation são a mudança desde o último evento, não o total acumulado do gesto. Multiplique no seu próprio acumulador (scale *= zoom), não atribua (scale = zoom), ou sua transformação reinicia a cada frame em vez de acumular.

Escolhendo entre elas

FunçãoPonteirosCallbacksFormato do delta
detectTapGestures1, fica paradoonTap, onDoubleTap, onLongPress, onPressnenhum, só posição
detectDragGestures1, se moveonDragStart, onDrag, onDragEnd, onDragCancelOffset por evento
detectHorizontalDragGestures / detectVerticalDragGestures1, se move em um eixomesmo formato, onHorizontalDrag/onVerticalDragFloat por evento
detectTransformGestures2+um callback onGesturecentroid, pan: Offset; zoom, rotation: Float

Combinando detectores, e a primitiva por baixo

Um único bloco Modifier.pointerInput só pode executar uma chamada de detect*Gestures, porque cada uma é um loop infinito (construído sobre awaitEachGesture) que nunca retorna enquanto o bloco estiver vivo. Escrever detectTapGestures(...) seguido de detectDragGestures(...) no mesmo bloco não faz os dois competirem, a segunda chamada é simplesmente código inalcançável. Precisar de um tap e um drag no mesmo nó significa dar a cada um seu próprio modifier pointerInput, o Compose executa os dois em paralelo, cada um observando o mesmo fluxo bruto de forma independente.

Qual ponteiro permanece disponível para o segundo detector depende do touch slop e de qual PointerInputChange é consumido primeiro, mecânicas que este blog cobre separadamente.

Cada uma dessas funções é um loop escrito em termos de awaitPointerEventScope/awaitEachGesture, a primitiva de nível mais baixo que o PointerInputScope de fato expõe. Você desce até ela diretamente só quando nenhuma das quatro acima se encaixa, um gesto customizado de múltiplos estágios, por exemplo, que precisa trocar o que está observando no meio do fluxo.

Chaveie o pointerInput no que a lambda de fato lê

Todas as quatro são instaladas através de Modifier.pointerInput(key). Chaveie-a em Unit enquanto a lambda captura um estado que muda, e o bloco nunca é reinstalado, então ele continua lendo o que aquele estado era na primeira composição. Chaveie-a no estado que o callback lê, ou leia aquele estado através de rememberUpdatedState em vez disso.

Keep reading

Related reads

Receba novos posts no seu e-mail