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).
detectTapGesturespara 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.detectTransformGesturespara 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ção | Ponteiros | Callbacks | Formato do delta |
|---|---|---|---|
detectTapGestures | 1, fica parado | onTap, onDoubleTap, onLongPress, onPress | nenhum, só posição |
detectDragGestures | 1, se move | onDragStart, onDrag, onDragEnd, onDragCancel | Offset por evento |
detectHorizontalDragGestures / detectVerticalDragGestures | 1, se move em um eixo | mesmo formato, onHorizontalDrag/onVerticalDrag | Float por evento |
detectTransformGestures | 2+ | um callback onGesture | centroid, 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.



