操作

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Compose には、ユーザー インタラクションによって生成された操作の検出に役立つさまざまな API が用意されています。幅広いユースケースに対応する API があります。

  • その一部は高レベルの API で、よく使われる操作をカバーできるように設計されています。たとえば、clickable 修飾子を使用すると、クリックの検出が容易になり、タップ時にユーザー補助機能を提供するとともに、視覚的インジケーター(リップルなど)を表示できます。

  • また、PointerInputScope.detectTapGesturesPointerInputScope.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 */ }
    )
}

スクロール

Scroll 修飾子

verticalScroll 修飾子と horizontalScroll 修飾子は、コンテンツの境界が最大サイズ制約より大きい場合にユーザーが要素をスクロールできるようにする最も簡単な方法を提供します。verticalScroll 修飾子と horizontalScroll 修飾子では、コンテンツを変換またはオフセットする必要はありません。

@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 修飾子が scroll 修飾子と異なる点は、scrollable はスクロール操作を検出するが、そのコンテンツをオフセットしないことです。この修飾子が正しく動作するためには、ScrollableState が必要です。ScrollableState を作成する際は、各スクロール ステップで(操作入力、スムーズ スクロール、またはフリングによって)呼び出される consumeScrollDelta 関数をピクセル単位のデルタで提供する必要があります。 この関数は、scrollable 修飾子を持つネスト要素がある場合にイベントが適切に伝播されるように、消費したスクロール距離の量を返します。

次のスニペットは、操作を検出してオフセットの数値を表示しますが、要素のオフセットは行いません。

@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 は、複数の要素が単一のスクロール操作に反応する「ネスト スクロール」をサポートしています。ネスト スクロールの一般的な例としては、別のリストに含まれるリストがあります。より複雑なケースとしては、折りたたみツールバーがあります。

自動ネスト スクロール

シンプルなネスト スクロールでは、アプリ側のアクションは必要ありません。スクロール アクションを開始する操作は、子から親に自動的に伝播されます。これにより、子がそれ以上スクロールできなくなると、親要素によって操作が処理されます。

自動ネスト スクロールは Compose のいくつかのコンポーネントと修飾子(verticalScrollhorizontalScrollscrollableLazy API および TextField)によってサポートされており、すぐに利用できます。つまり、ユーザーがネストされたコンポーネントの内部の子をスクロールすると、以前の修飾子によって、ネスト スクロールをサポートする親にスクロール差分が伝播されます。

次の例では、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)
                )
            }
        }
    }
}

内部要素の内側と外側の操作に応答する、2 つの垂直方向のネスト スクロールの UI 要素

nestedScroll 修飾子を使用する

複数の要素の間で高度に調整されたスクロールを作成する必要がある場合は、nestedScroll 修飾子を使用すると、ネスト スクロール階層を定義することにより柔軟性を高めることができます。前のセクションで説明したように、一部のコンポーネントには、ネスト スクロールのサポートが組み込まれています。ただし、自動的にスクロールできないコンポーザブル(BoxColumn など)の場合、そのようなコンポーネントのスクロールのデルタは、ネスト スクロール システム内で伝播せず、デルタは NestedScrollConnection にも親コンポーネントにも到達しません。このための対応策として、nestedScroll を使用すると、カスタム コンポーネントを含む他のコンポーネントでもそのようなサポートを利用できるようになります。

ネスト スクロールの相互運用(試験運用版)

スクロール可能なコンポーザブルにスクロール可能な View 要素をネストしようとした場合、またはその逆を行おうとした場合、問題が発生することがあります。特に想定されるのが、子をスクロールしてその開始位置または終了位置に到達し、親にスクロールが引き継がれることを期待している場合です。この期待される動作が発生しないか、期待どおりに動作しない可能性があります。

この問題は、スクロール可能なコンポーザブルに組み込まれている前提の結果です。スクロール可能なコンポーザブルには「デフォルトでネスト スクロール」というルールがあります。つまり、スクロール可能なコンテナはすべて、ネスト スクロール チェーンに、NestedScrollConnection を介して親として参加し、NestedScrollDispatcher を介して子として参加する必要があります。そうすることで、子が境界にあるときに、子が親のネスト スクロールを行います。このようなルールにより、たとえば Compose の Pager と Compose の LazyRow が適切に連携します。ただし、相互運用スクロールが ViewPager2 または RecyclerView で行われている場合、これらは NestedScrollingParent3 を実装していないため、子から親への連続スクロールはできません。

スクロール可能な View 要素とスクロール可能なコンポーザブルが両方向でネストされており、それらの間でネスト スクロールの相互運用 API を有効にする場合、以下のシナリオでネスト スクロールの相互運用 API を使用することで、このような問題を軽減できます。

子 ComposeView を含んでいる連携する親 View

連携する親 View とは、すでに NestedScrollingParent3 を実装しているため、連携するネストされた子コンポーザブルからスクロールのデルタを受け取ることができる View です。この場合、ComposeView は子となるので、(間接的に)NestedScrollingChild3 を実装する必要があります。連携する親の例には androidx.coordinatorlayout.widget.CoordinatorLayout があります。

スクロール可能な View である親コンテナとネストされたスクロール可能な子コンポーザブルの間にネスト スクロールの相互運用が必要な場合は、rememberNestedScrollInteropConnection() を使用できます。

rememberNestedScrollInteropConnection() により、NestedScrollingParent3 を実装する親 View と子 Compose との間でネスト スクロールの相互運用を有効にする NestedScrollConnection の許可と保存が可能になります。これは nestedScroll 修飾子と組み合わせて使用する必要があります。ネスト スクロールは Compose 側でデフォルトで有効になっているため、この接続を使用すると、View 側でネスト スクロールの両方を有効にし、Views とコンポーザブルの間に必要なグルーロジックを追加できます。

頻繁に使用されるユースケースでは、以下の例のように、CoordinatorLayoutCollapsingToolbarLayout、子コンポーザブルを使用します。

<androidx.coordinatorlayout.widget.CoordinatorLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.google.android.material.appbar.AppBarLayout
        android:id="@+id/app_bar"
        android:layout_width="match_parent"
        android:layout_height="100dp"
        android:fitsSystemWindows="true">

            <com.google.android.material.appbar.CollapsingToolbarLayout
            android:id="@+id/collapsing_toolbar_layout"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:fitsSystemWindows="true"
            app:layout_scrollFlags="scroll|exitUntilCollapsed">

             <!--...-->

        </com.google.android.material.appbar.CollapsingToolbarLayout>

    </com.google.android.material.appbar.AppBarLayout>

    <androidx.compose.ui.platform.ComposeView
        android:id="@+id/compose_view"
        app:layout_behavior="@string/appbar_scrolling_view_behavior"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

</androidx.coordinatorlayout.widget.CoordinatorLayout>

次のように、アクティビティまたはフラグメントで、子コンポーザブルと必要な NestedScrollConnection をセットアップする必要があります。

@ExperimentalComposeUiApi
open class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        findViewById<ComposeView>(R.id.compose_view).apply {
            setContent {
                val nestedScrollInterop = rememberNestedScrollInteropConnection()
                // Add the nested scroll connection to your top level @Composable element
                // using the nestedScroll modifier.
                LazyColumn(modifier = Modifier.nestedScroll(nestedScrollInterop)) {
                    items(20) { item ->
                        Box(
                            modifier = Modifier
                                .padding(16.dp)
                                .height(56.dp)
                                .fillMaxWidth()
                                .background(Color.Gray),
                            contentAlignment = Alignment.Center
                        ) {
                            Text(item.toString())
                        }
                    }
                }
            }
        }
    }
}

子 AndroidView を含んでいる親コンポーザブル

このシナリオでは、子 AndroidView を含んでいる親コンポーザブルがある場合の Compose 側のネスト スクロールの相互運用 API の実装を扱います。AndroidView は、スクロールにおける親である Compose に対しては子になるので NestedScrollDispatcher を実装し、スクロールにおける子である View に対しては親になるので NestedScrollingParent3 を実装します。すると、Compose である親は、ネストされたスクロール可能な子 View からネスト スクロールの差分を受け取ることができるようになります。

次の例は、このシナリオでネスト スクロールの相互運用を、Compose の折りたたみツールバーとともに実現する方法を示しています。

@Composable
private fun NestedScrollInteropComposeParentWithAndroidChildExample() {
    val toolbarHeightPx = with(LocalDensity.current) { ToolbarHeight.roundToPx().toFloat() }
    val toolbarOffsetHeightPx = remember { mutableStateOf(0f) }

    // Sets up the nested scroll connection between the Box composable parent
    // and the child AndroidView containing the RecyclerView
    val nestedScrollConnection = remember {
        object : NestedScrollConnection {
            override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
                // Updates the toolbar offset based on the scroll to enable
                // collapsible behaviour
                val delta = available.y
                val newOffset = toolbarOffsetHeightPx.value + delta
                toolbarOffsetHeightPx.value = newOffset.coerceIn(-toolbarHeightPx, 0f)
                return Offset.Zero
            }
        }
    }

    Box(
        Modifier
            .fillMaxSize()
            .nestedScroll(nestedScrollConnection)
    ) {
        TopAppBar(
            modifier = Modifier
                .height(ToolbarHeight)
                .offset { IntOffset(x = 0, y = toolbarOffsetHeightPx.value.roundToInt()) }
        )

        AndroidView(
            { context ->
                LayoutInflater.from(context)
                    .inflate(R.layout.view_in_compose_nested_scroll_interop, null).apply {
                        with(findViewById<RecyclerView>(R.id.main_list)) {
                            layoutManager = LinearLayoutManager(context, VERTICAL, false)
                            adapter = NestedScrollInteropAdapter()
                        }
                    }.also {
                        // Nested scrolling interop is enabled when
                        // nested scroll is enabled for the root View
                        ViewCompat.setNestedScrollingEnabled(it, true)
                    }
            },
            // ...
        )
    }
}

private class NestedScrollInteropAdapter :
    Adapter<NestedScrollInteropAdapter.NestedScrollInteropViewHolder>() {
    val items = (1..10).map { it.toString() }

    override fun onCreateViewHolder(
        parent: ViewGroup,
        viewType: Int
    ): NestedScrollInteropViewHolder {
        return NestedScrollInteropViewHolder(
            LayoutInflater.from(parent.context)
                .inflate(R.layout.list_item, parent, false)
        )
    }

    override fun onBindViewHolder(holder: NestedScrollInteropViewHolder, position: Int) {
        // ...
    }

    class NestedScrollInteropViewHolder(view: View) : ViewHolder(view) {
        fun bind(item: String) {
            // ...
        }
    }
    // ...
}

次の例は、scrollable 修飾子で、この API を使用する方法を示しています。

@Composable
fun ViewInComposeNestedScrollInteropExample() {
    Box(
        Modifier
            .fillMaxSize()
            .scrollable(rememberScrollableState {
                // View component deltas should be reflected in Compose
                // components that participate in nested scrolling
                it
            }, Orientation.Vertical)
    ) {
        AndroidView(
            { context ->
                LayoutInflater.from(context)
                    .inflate(android.R.layout.list_item, null)
                    .apply {
                        // Nested scrolling interop is enabled when
                        // nested scroll is enabled for the root View
                        ViewCompat.setNestedScrollingEnabled(this, true)
                    }
            }
        )
    }
}

次にある最後の例では、ネスト スクロールの相互運用 API を BottomSheetDialogFragment で使用して、ドラッグして閉じる動作を実現する方法を示しています。

@OptIn(ExperimentalComposeUiApi::class)
class BottomSheetFragment : BottomSheetDialogFragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        val rootView: View = inflater.inflate(R.layout.fragment_bottom_sheet, container, false)

        rootView.findViewById<ComposeView>(R.id.compose_view).apply {
            setContent {
                val nestedScrollInterop = rememberNestedScrollInteropConnection()
                LazyColumn(
                    Modifier
                        .nestedScroll(nestedScrollInterop)
                        .fillMaxSize()
                ) {
                    item {
                        Text(text = "Bottom sheet title")
                    }
                    items(10) {
                        Text(
                            text = "List item number $it",
                            modifier = Modifier.fillMaxWidth()
                        )
                    }
                }
            }
            return rootView
        }
    }
}

rememberNestedScrollInteropConnection() がアタッチ先の要素に NestedScrollConnection をインストールします。NestedScrollConnection は、デルタを Compose レベルから View レベルに送信します。これにより、その要素はネスト スクロールに参加できるようになりますが、要素のスクロールは自動的には有効になりません。自動的にスクロールできないコンポーザブル(BoxColumn など)には、そのようなコンポーネントのスクロールのデルタは、ネスト スクロール システム内で伝播せず、デルタは rememberNestedScrollInteropConnection() が提供する NestedScrollConnection にも到達しないため、それらのデルタは親である View コンポーネントにも到達しません。この問題を解決するには、scrollable 修飾子をこれらのタイプのネストされたコンポーザブルにも設定します。詳細については、ネスト スクロールに関する前のセクションをご覧ください。

子 ComposeView を含んでいる連携しない親 View

連携しない View とは、View 側で必要な NestedScrolling インターフェースを実装していない View のことです。つまり、こうした Views とのネスト スクロールの相互運用は、そのままでは機能しません。連携しない Views は、RecyclerViewViewPager2 です。

ドラッグ

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 修飾子を使用すると、要素を離したときに、通常は 1 つの方向に定義された 2 つ以上のアンカー ポイントに向かって移動するアニメーションが表示されるような方法で、要素をドラッグできます。この修飾子は、「スワイプして閉じる」パターンを実装するためによく使用されます。

この修飾子は要素を移動せず、操作の検出のみを行う点に注意してください。たとえば、offset 修飾子を使用して要素を移動することにより、状態を保持して画面上で表現する必要があります。

スワイプ可能な状態は swipeable 修飾子で必須であり、rememberSwipeableState() で作成し、記憶することができます。この状態では、プログラムでアンカーへの移動のアニメーションを表示する便利なメソッドのセット(snapToanimateToperformFlingperformDrag を参照)と、ドラッグの進行状況を観測するためのプロパティも利用できます。

スワイプ操作は、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 検出機能を使用できます。