동작

Compose는 사용자 상호작용에서 생성된 동작을 감지하는 데 도움이 되는 다양한 API를 제공합니다. 이 API는 광범위하게 사용됩니다.

  • 그중 일부는 상위 수준이며 가장 일반적으로 사용되는 동작을 처리하도록 설계되었습니다. 예를 들어 clickable 수정자를 사용하면 클릭을 쉽게 감지할 수 있으며 접근성 기능도 이용할 수 있고 탭할 경우 시각적 표시기도 표시됩니다(예: 물결).

  • 또한 PointerInputScope.detectTapGestures 또는 PointerInputScope.detectDragGestures와 같이 하위 수준에서 더 유연하게 작동하지만 추가 기능이 포함되지 않은 덜 일반적으로 사용되는 동작 감지기도 있습니다.

탭하기 및 누르기

clickable 수정자를 사용하면 수정자가 적용되는 요소에서 앱이 클릭을 감지할 수 있습니다.

@Composable
fun ClickableSample() {
    val count = remember { mutableStateOf(0) }
    // content that you want to make clickable
    Text(
        text = count.value.toString(),
        modifier = Modifier.clickable { count.value += 1 }
    )
}

탭에 응답하는 UI 요소의 예

유연성이 더 필요한 경우 pointerInput 수정자를 통해 탭 동작 감지기를 제공할 수 있습니다.

Modifier.pointerInput(Unit) {
    detectTapGestures(
        onPress = { /* Called when the gesture starts */ },
        onDoubleTap = { /* Called on Double Tap */ },
        onLongPress = { /* Called on Long Press */ },
        onTap = { /* Called on Tap */ }
    )
}

스크롤

스크롤 수정자

verticalScrollhorizontalScroll 수정자는 콘텐츠의 경계가 최대 크기 제약 조건보다 클 때 사용자가 요소를 스크롤할 수 있는 가장 간단한 방법을 제공합니다. verticalScrollhorizontalScroll 수정자를 사용하면 콘텐츠를 변환하거나 오프셋할 필요가 없습니다.

@Composable
fun ScrollBoxes() {
    Column(
        modifier = Modifier
            .background(Color.LightGray)
            .size(100.dp)
            .verticalScroll(rememberScrollState())
    ) {
        repeat(10) {
            Text("Item $it", modifier = Modifier.padding(2.dp))
        }
    }
}

스크롤 동작에 응답하는 간단한 세로 목록

ScrollState를 사용하면 스크롤 위치를 변경하거나 현재 상태를 가져올 수 있습니다. 기본 매개변수를 사용하여 만들려면 rememberScrollState()를 사용하세요.

@Composable
private fun ScrollBoxesSmooth() {

    // Smoothly scroll 100px on first composition
    val state = rememberScrollState()
    LaunchedEffect(Unit) { state.animateScrollTo(100) }

    Column(
        modifier = Modifier
            .background(Color.LightGray)
            .size(100.dp)
            .padding(horizontal = 8.dp)
            .verticalScroll(state)
    ) {
        repeat(10) {
            Text("Item $it", modifier = Modifier.padding(2.dp))
        }
    }
}

스크롤 가능한 수정자

scrollable 수정자는 스크롤 수정자와는 다릅니다. 즉, scrollable은 스크롤 동작을 감지하지만 콘텐츠를 오프셋하지 않습니다. 이 수정자가 올바르게 작동하려면 ScrollableController가 필요합니다. ScrollableController를 구성할 때는 각 스크롤 단계에서 픽셀 단위 델타를 사용하여 (동작 입력, 부드러운 스크롤 또는 플링으로) 호출할 consumeScrollDelta 함수를 제공해야 합니다. 적절한 이벤트 전파를 보장하기 위해 이 함수에서 사용된 스크롤 길이를 반환해야 합니다.

다음 스니펫은 동작을 감지하고 오프셋의 숫자 값을 표시하지만 아무 요소도 오프셋하지 않습니다.

@Composable
fun ScrollableSample() {
    // actual composable state
    var offset by remember { mutableStateOf(0f) }
    Box(
        Modifier
            .size(150.dp)
            .scrollable(
                orientation = Orientation.Vertical,
                // Scrollable state: describes how to consume
                // scrolling delta and update offset
                state = rememberScrollableState { delta ->
                    offset += delta
                    delta
                }
            )
            .background(Color.LightGray),
        contentAlignment = Alignment.Center
    ) {
        Text(offset.toString())
    }
}

손가락 누르기를 감지하고 손가락 위치의 숫자 값을 표시하는 UI 요소

중첩 스크롤

Compose는 여러 요소가 단일 스크롤 동작에 반응하는 중첩 스크롤을 지원합니다. 중첩 스크롤의 일반적인 예는 다른 목록 안에 있는 목록이며 더 복잡한 경우는 접기 방식 툴바입니다.

자동 중첩 스크롤

단순한 중첩 스크롤의 경우 사용자가 아무 조치를 취하지 않아도 됩니다. 스크롤 작업을 시작하는 동작은 하위 요소에서 상위 요소로 자동 전파됩니다. 따라서 하위 요소가 더 이상 스크롤할 수 없는 경우 상위 요소에 의해 동작이 처리됩니다.

다음 예에서는 verticalScroll 수정자가 적용된 컨테이너 내부에 있는 verticalScroll 수정자가 적용된 요소를 보여줍니다.

val gradient = Brush.verticalGradient(0f to Color.Gray, 1000f to Color.White)
Box(
    modifier = Modifier
        .background(Color.LightGray)
        .verticalScroll(rememberScrollState())
        .padding(32.dp)
) {
    Column {
        repeat(6) {
            Box(
                modifier = Modifier
                    .height(128.dp)
                    .verticalScroll(rememberScrollState())
            ) {
                Text(
                    "Scroll here",
                    modifier = Modifier
                        .border(12.dp, Color.DarkGray)
                        .background(brush = gradient)
                        .padding(24.dp)
                        .height(150.dp)
                )
            }
        }
    }
}

내부 요소 안팎의 동작에 반응하는 두 개의 중첩된 세로 스크롤 UI 요소

nestedScroll 수정자 사용

여러 요소 간에 조정된 고급 스크롤을 만들어야 하는 경우 nestedScroll 수정자를 사용하면 중첩된 스크롤 계층 구조를 정의하여 더 유연하게 만들 수 있습니다.

드래그

draggable 수정자는 동작을 한 방향으로 드래그하는 상위 수준 진입점이며 드래그 거리를 픽셀 단위로 보고합니다.

이 수정자는 동작만 감지한다는 점에서 scrollable과 유사합니다. 예를 들어 offset 수정자를 통해 요소를 이동하여 상태를 유지하고 화면에 표시해야 합니다.

var offsetX by remember { mutableStateOf(0f) }
Text(
    modifier = Modifier
        .offset { IntOffset(offsetX.roundToInt(), 0) }
        .draggable(
            orientation = Orientation.Horizontal,
            state = rememberDraggableState { delta ->
                offsetX += delta
            }
        ),
    text = "Drag me!"
)

전체 드래그 동작을 제어해야 하는 경우 대신 pointerInput 수정자를 통해 드래그 동작 감지기를 사용해 보세요.

Box(modifier = Modifier.fillMaxSize()) {
    var offsetX by remember { mutableStateOf(0f) }
    var offsetY by remember { mutableStateOf(0f) }

    Box(
        Modifier
            .offset { IntOffset(offsetX.roundToInt(), offsetY.roundToInt()) }
            .background(Color.Blue)
            .size(50.dp)
            .pointerInput(Unit) {
                detectDragGestures { change, dragAmount ->
                    change.consumeAllChanges()
                    offsetX += dragAmount.x
                    offsetY += dragAmount.y
                }
            }
    )
}

손가락 누르기로 드래그 중인 UI 요소

스와이프

swipeable 수정자를 사용하여 손을 떼면 한 방향으로 정의된 두 개 이상의 앵커 포인트를 향해 애니메이션 처리되는 요소를 드래그할 수 있습니다. 일반적인 용도는 '스와이프하여 닫기' 패턴을 구현하는 것입니다.

이 수정자는 요소를 이동하지 않으며 동작만 감지합니다. 예를 들어 offset 수정자를 통해 요소를 이동하여 상태를 유지하고 화면에 표시해야 합니다.

스와이프 가능 상태는 swipable 수정자에 필요하며 rememberSwipeableState()를 사용하여 만들고 저장할 수 있습니다. 이 상태는 또한 프로그래매틱 방식으로 앵커에 애니메이션 처리하는 데 유용한 메서드(snapTo, animateTo, performFling, performDrag 참고) 및 드래그 진행 상태를 확인할 수 있는 속성을 제공합니다.

스와이프 동작은 FixedThreshold(Dp)FractionalThreshold(Float)와 같은 다양한 기준점 유형을 갖도록 구성할 수 있으며 앵커 포인트 시작-끝 조합마다 다를 수 있습니다.

더 유연하게 작동하도록 경계를 지나 스와이프할 때 resistance를 구성할 수 있으며 또한 위치 thresholds에 도달하지 않은 경우에도 스와이프를 다음 상태로 애니메이션 처리하는 velocityThreshold도 구성할 수 있습니다.

@Composable
fun SwipeableSample() {
    val width = 96.dp
    val squareSize = 48.dp

    val swipeableState = rememberSwipeableState(0)
    val sizePx = with(LocalDensity.current) { squareSize.toPx() }
    val anchors = mapOf(0f to 0, sizePx to 1) // Maps anchor points (in px) to states

    Box(
        modifier = Modifier
            .width(width)
            .swipeable(
                state = swipeableState,
                anchors = anchors,
                thresholds = { _, _ -> FractionalThreshold(0.3f) },
                orientation = Orientation.Horizontal
            )
            .background(Color.LightGray)
    ) {
        Box(
            Modifier
                .offset { IntOffset(swipeableState.offset.value.roundToInt(), 0) }
                .size(squareSize)
                .background(Color.DarkGray)
        )
    }
}

스와이프 동작에 응답하는 UI 요소

멀티터치: 화면 이동, 확대/축소, 회전

화면 이동, 확대/축소, 회전에 사용되는 멀티터치 동작을 감지하려면 transformable 수정자를 사용하세요. 이 수정자는 자체적으로 요소를 변환하지 않으며 동작만 감지합니다.

@Composable
fun TransformableSample() {
    // set up all transformation states
    var scale by remember { mutableStateOf(1f) }
    var rotation by remember { mutableStateOf(0f) }
    var offset by remember { mutableStateOf(Offset.Zero) }
    val state = rememberTransformableState { zoomChange, offsetChange, rotationChange ->
        scale *= zoomChange
        rotation += rotationChange
        offset += offsetChange
    }
    Box(
        Modifier
            // apply other transformations like rotation and zoom
            // on the pizza slice emoji
            .graphicsLayer(
                scaleX = scale,
                scaleY = scale,
                rotationZ = rotation,
                translationX = offset.x,
                translationY = offset.y
            )
            // add transformable to listen to multitouch transformation events
            // after offset
            .transformable(state = state)
            .background(Color.Blue)
            .fillMaxSize()
    )
}

멀티터치 동작(화면 이동, 확대/축소, 회전)에 응답하는 UI 요소

확대/축소, 화면 이동, 회전을 다른 동작과 결합해야 하는 경우 PointerInputScope.detectTransformGestures 감지기를 사용할 수 있습니다.