Recomposed
Gesture

Compose에서 터치 입력 감지하기: 탭, 드래그, 트랜스폼 제스처

Oct 26, 2026 · 1 min read

Compose에서 터치 입력 감지하기: 탭, 드래그, 트랜스폼 제스처

직관적으로 이해하기

Compose의 모든 터치 제스처는 동일한 방식으로 시작한다. Modifier.pointerInput 블록과 거기에 건네는 suspend 함수다. 달라지는 것은 어떤 함수를 쓰느냐인데, 각 함수는 같은 원시 포인터 이벤트 스트림을 순회하도록 만들어진 전용 루프이며, 한 가지 종류의 제스처에 맞춰 설계되어 있기 때문이다.

잘못된 함수를 고르면 API와 씨름하게 되거나(탭을 감지하기 위해 원시 오프셋을 직접 파싱하는 식으로), 요청하지도 않은 데이터를 건네받게 된다(드래그에 불과한 제스처에 회전 값이 딸려 오는 식으로).

  • detectTapGestures: 움직이지 않는 하나의 포인트, 즉 탭, 더블탭, 롱프레스를 위한 함수.
  • detectDragGestures(그리고 수평/수직 버전): 움직이는 하나의 포인트를 한 번에 한 방향씩 다루는 함수.
  • detectTransformGestures: 동시에 둘 이상의 손가락, 즉 핀치, 팬, 회전을 위한 함수.

탭, 더블탭, 롱프레스: detectTapGestures

Modifier.pointerInput(Unit) {
    detectTapGestures(
        onTap = { /* 단일 탭 */ },
        onDoubleTap = { /* 더블탭 윈도우 내의 두 번째 탭 */ },
        onLongPress = { /* 롱프레스 임계값을 넘겨 유지됨 */ },
        onPress = { /* 매 프레스 다운마다 발생하며, Compose가 이 제스처가
                       무엇으로 판정될지 알기 전에 호출됨 */ }
    )
}

onPress는 PressGestureScope 람다이기 때문에 awaitRelease()와 tryAwaitRelease()를 사용할 수 있다. 다른 콜백을 블로킹하지 않고 릴리스를 감지할 수 있어, 눌렀다 떼는 동안의 피드백 같은 용도에 유용하다.

전달한 콜백만 실제로 연결된다. onTap만 전달하면 Compose는 더블탭 윈도우가 끝나기를 기다릴 필요가 없어지므로, 단독 탭은 두 번째 탭이 뒤따르는지 기다리지 않고 즉시 처리된다.

이 함수가 노출하지 않는 기능이 필요할 때는 Modifier.clickable 대신 이쪽을 선택한다. 더블탭으로 좋아요 표시하기, 롱프레스 컨텍스트 메뉴, 직접 제어하는 프레스 상태의 스케일·색상 변화 같은 경우다.

clickable 위에 겹쳐 쓰지 말 것

이미 Modifier.clickable/combinedClickable이 적용된 노드에 detectTapGestures를 추가하면 같은 포인터 스트림 위에 서로 경쟁하는 제스처 디텍터 두 개가 설치되고, clickable이 무료로 제공하는 리플과 접근성 시맨틱을 잃게 된다. 둘 중 하나만 선택하라.

단일 축 드래그: detectDragGestures와 수평/수직 버전

Modifier.pointerInput(Unit) {
    detectDragGestures(
        onDragStart = { offset -> /* 손가락이 터치 슬롭을 넘어 움직임 */ },
        onDrag = { change, dragAmount -> change.consume() /* dragAmount: Offset, 두 축 모두 */ },
        onDragEnd = { /* 손가락이 떨어짐 */ },
        onDragCancel = { /* 제스처가 중단됨, 예: 다른 포인터가 가져감 */ }
    )
}

onDrag은 PointerInputChange와 함께 dragAmount: Offset을 건네주는데, 이는 드래그의 전체 이동 거리가 아니라 마지막 이벤트 이후의 변화량(델타)이다. change.consume()은 직접 호출해야 한다. detectDragGestures가 대신 제스처를 가로채 주지 않는다.

소비되지 않은 드래그는 부모로 새어 나간다

change.consume()을 생략하면 단순히 제스처가 끊기는 느낌만 드는 게 아니다. 트리 위쪽의 부모 scrollable/verticalScroll은 포인터가 이미 점유되었다는 사실을 전혀 알지 못해, 드래그와 동시에 스크롤까지 일어나게 된다.

detectHorizontalDragGestures와 detectVerticalDragGestures는 모양은 같지만 차원이 하나 줄어든 버전이다. onHorizontalDrag/onVerticalDrag은 Offset 대신 Float 델타를 건네주며, 제스처를 시작하는 데는 해당 축의 만 넘으면 된다. 제스처가 본질적으로 한 방향인 경우(스와이프 가능한 행, 수직 슬라이더 등)에는 두 축 버전 대신 이쪽을 선택한다. 그러면 대각선 방향의 손가락 움직임이 엉뚱한 축으로 제스처를 가로채지 않고, 위에 있는 수직 리스트도 정상적으로 스크롤될 수 있다.

핀치, 팬, 회전: detectTransformGestures

Modifier.pointerInput(Unit) {
    detectTransformGestures(
        panZoomLock = false
    ) { centroid, pan, zoom, rotation ->
        /* centroid: Offset, 활성 포인터들 사이의 중간점
           pan: Offset, 마지막 이벤트 이후의 이동량
           zoom: Float, 마지막 이벤트 이후의 배율 (1f = 변화 없음)
           rotation: Float, 마지막 이벤트 이후의 회전 각도 */
    }
}

가 바로 detectTransformGestures가 네 개가 아닌 하나의 콜백만 받는 이유다. 팬, 줌, 회전은 서로 별개의 제스처가 아니라, Compose가 매 프레임 동일한 멀티포인터 이벤트로부터 도출하는 세 개의 숫자일 뿐이다. 그래서 탭과 롱프레스 사이에 있는 것과 같은 판별 과정이 여기엔 필요 없다.

panZoomLock = true는 이름이 암시하는 것과 반대로 동작한다. 이 옵션은 팬이나 줌이 아니라 회전을 잠근다. 제스처 도중 어느 임계값을 먼저 넘느냐가 그 제스처의 남은 전체 형태를 결정하는데, 팬/줌 임계값을 먼저 넘으면 그 이후로 회전 값은 계속 0f로 고정된다. 핀치로 확대/축소하는 이미지 뷰어나 지도처럼 팬과 줌은 원하지만 두 손가락 핀치가 의도치 않은 회전으로 읽히는 것은 원치 않는 경우에 유용하다. 세 가지를 한 제스처 안에서 모두 결합하는 크롭 도구라면 false로 두는 편이 맞는 경우다.

zoom과 rotation은 총량이 아니라 델타다

zoom과 rotation은 제스처의 누적 총량이 아니라 마지막 이벤트 이후의 변화량이다. 자신만의 누산기에는 곱셈으로 반영해야 하며(scale *= zoom), 대입해서는 안 된다(scale = zoom). 그렇지 않으면 트랜스폼이 누적되지 않고 매 프레임 초기화된다.

함수 선택하기

함수포인터 수콜백델타 형태
detectTapGestures1개, 고정onTap, onDoubleTap, onLongPress, onPress없음, 위치만
detectDragGestures1개, 이동onDragStart, onDrag, onDragEnd, onDragCancel이벤트당 Offset
detectHorizontalDragGestures / detectVerticalDragGestures1개, 한 축으로 이동동일한 형태, onHorizontalDrag/onVerticalDrag이벤트당 Float
detectTransformGestures2개 이상onGesture 콜백 하나centroid, pan: Offset; zoom, rotation: Float

디텍터 조합하기, 그리고 그 밑바닥의 기본 요소

하나의 Modifier.pointerInput 블록은 detect*Gestures 호출을 단 하나만 실행할 수 있다. 각각이 (awaitEachGesture 위에 구축된) 무한 루프이며, 블록이 살아 있는 동안 절대 반환되지 않기 때문이다. 같은 블록 안에서 detectTapGestures(...)를 쓰고 이어서 detectDragGestures(...)를 쓴다고 해서 둘이 경쟁하는 게 아니라, 두 번째 호출은 그냥 도달 불가능한 코드가 된다. 같은 노드에 탭과 드래그가 모두 필요하다면 각각에 별도의 pointerInput 모디파이어를 주어야 한다. 그러면 Compose가 둘을 병렬로 실행하며, 각각이 같은 원시 스트림을 독립적으로 관찰한다.

두 번째 디텍터에 포인터가 계속 넘어가느냐는 터치 슬롭과 어느 PointerInputChange가 먼저 소비되느냐에 달려 있는데, 이 메커니즘은 이 블로그에서 따로 다룬다.

이 함수들은 모두 PointerInputScope가 실제로 노출하는 더 저수준의 기본 요소인 awaitPointerEventScope/awaitEachGesture로 작성된 루프다. 위 네 가지 중 어느 것도 맞지 않을 때, 예를 들어 스트림 도중에 무엇을 감지할지 전환해야 하는 커스텀 다단계 제스처가 필요할 때만 이 저수준 요소로 직접 내려가면 된다.

람다가 실제로 읽는 값을 기준으로 pointerInput의 key를 잡을 것

위 네 가지 모두 Modifier.pointerInput(key)를 통해 설치된다. 람다가 변하는 상태를 클로저로 캡처하는데 key를 Unit으로 두면, 블록이 다시 설치되지 않아 최초 컴포지션 시점의 상태 값을 계속 읽게 된다. 콜백이 읽는 상태를 key로 잡거나, 대신 rememberUpdatedState를 통해 그 상태를 읽어야 한다.

Keep reading

Related reads

새 글을 이메일로 받아보세요