2 次元スクロール: scrollable2D、draggable2D

Jetpack Compose では、scrollable2D と draggable2D は、2 次元でポインタ入力を処理するように設計された低レベルの修飾子です。標準の 1D 修飾子 scrollable と draggable は単一の向きに制限されますが、2D バリアントは X 軸と Y 軸の両方の動きを同時に追跡します。

たとえば、既存の scrollable 修飾子は単一方向のスクロールとフリングに使用され、scrollable2d は 2D のスクロールとフリングに使用されます。これにより、スプレッドシートや画像ビューアなど、あらゆる方向に移動する複雑なレイアウトを作成できます。scrollable2d 修飾子は、2D シナリオでのネストされたスクロールもサポートしています。

図 1. 地図上の双方向パン。

`scrollable2D` または `draggable2D` を選択する

適切な API を選択するかどうかは、移動する UI 要素と、これらの要素の望ましい物理的動作によって異なります。

Modifier.scrollable2D: コンテナ内のコンテンツを移動するには、コンテナでこの修飾子を使用します。たとえば、地図、スプレッドシート、フォトビューアなど、コンテナのコンテンツを水平方向と垂直方向の両方にスクロールする必要がある場合に使用します。フリングのサポートが組み込まれているため、スワイプ後もコンテンツが移動し続け、ページ上の他のスクロールコンポーネントと連携します。

Modifier.draggable2D: この修飾子を使用して、コンポーネント自体を移動します。軽量な修飾子であるため、ユーザーの指が止まると同時に動きが止まります。フリングのサポートは含まれません。

コンポーネントをドラッグ可能にしたいが、フリングやネストされたスクロールのサポートは必要ない場合は、draggable2D を使用します。

2D 修飾子を実装する

以降のセクションでは、2D 修飾子の使用方法を示す例を示します。

`Modifier.scrollable2D` を実装する

この修飾子は、ユーザーがコンテンツを全方向に移動する必要があるコンテナに使用します。

2D 動作データをキャプチャする

この例では、未加工の 2D 動作データを取得して X、Y オフセットを表示する方法を示します。

@Composable
private fun Scrollable2DSample() {
    // 1. Manually track the total distance the user has moved in both X and Y directions
    var offset by remember { mutableStateOf(Offset.Zero) }

    Box(
        modifier = Modifier
            .fillMaxSize()
            // ...
        contentAlignment = Alignment.Center
    ) {
        Box(
            modifier = Modifier
                .size(200.dp)
                // 2. Attach the 2D scroll logic to capture XY movement deltas
                .scrollable2D(
                    state = rememberScrollable2DState { delta ->
                        // 3. Update the cumulative offset state with the new movement delta
                        offset += delta

                        // Return the delta to indicate the entire movement was handled by this box
                        delta
                    }
                )
                // ...
            contentAlignment = Alignment.Center
        ) {
            Column(horizontalAlignment = Alignment.CenterHorizontally) {
                // 4. Display the current X and Y values from the offset state in real-time
                Text(
                    text = "X: ${offset.x.roundToInt()}",
                    // ...
                )
                Spacer(modifier = Modifier.height(8.dp))
                Text(
                    text = "Y: ${offset.y.roundToInt()}",
                    // ...
                )
            }
        }
    }
}TwoDimensionalScrollSnippets.kt

図 2. ユーザーがポインタをサーフェス上でドラッグすると、現在の X 座標と Y 座標のオフセットを追跡して表示する紫色のボックス。

上記のスニペットは次の処理を行います。

ユーザーがスクロールした合計距離を保持する状態として offset を使用します。
rememberScrollable2DState 内で、ユーザーの指によって生成されたすべてのデルタを処理するラムダ関数が定義されます。コード offset.value += delta は、新しい位置で手動状態を更新します。
Text コンポーネントには、その offset 状態の現在の X 値と Y 値が表示されます。これらの値は、ユーザーがドラッグするとリアルタイムで更新されます。

大きなビューポートをパンする

この例では、キャプチャした 2D スクロール可能なデータを使用して、親コンテナよりも大きいコンテンツに translationX と translationY を適用する方法を示します。

@Composable
private fun Panning2DImage() {

    // Manually track the total distance the user has moved in both X and Y directions
    val offset = remember { mutableStateOf(Offset.Zero) }

    // Define how gestures are captured. The lambda is called for every finger movement
    val scrollState = rememberScrollable2DState { delta ->
        offset.value += delta
        delta
    }

    // The Viewport (Container): A fixed-size box that acts as a window into the larger content
    Box(
        modifier = Modifier
            .size(600.dp, 400.dp) // The visible area dimensions
            // ...
            // Hide any parts of the large content that sit outside this container's boundaries
            .clipToBounds()
            // Apply the 2D scroll modifier to intercept touch and fling gestures in all directions
            .scrollable2D(state = scrollState),
        contentAlignment = Alignment.Center,
    ) {
        // The Content: An image given a much larger size than the container viewport
        Image(
            painter = painterResource(R.drawable.cheese_5),
            contentDescription = null,
            modifier = Modifier
                .requiredSize(1200.dp, 800.dp)
                // Manual Scroll Effect: Since scrollable2D doesn't move content automatically,
                // we use graphicsLayer to shift the drawing position based on the tracked offset.
                .graphicsLayer {
                    translationX = offset.value.x
                    translationY = offset.value.y
                },
            contentScale = ContentScale.FillBounds
        )
    }
}TwoDimensionalScrollSnippets.kt

図 3. Modifier.scrollable2D で作成された双方向パンニング画像ビューポート。

図 4. Modifier.scrollable2D で作成された双方向のパンニングテキストビューポート。

上記のスニペットには、次のものが含まれています。

コンテナは固定サイズ（600x400dp）に設定され、コンテンツは親のサイズに合わせてサイズ変更されないように、はるかに大きなサイズ（1200x800dp）に設定されています。
コンテナの clipToBounds() 修飾子により、600x400 ボックスの外にある大きなコンテンツの一部が非表示になります。
LazyColumn などの上位コンポーネントとは異なり、scrollable2D はコンテンツを自動的に移動しません。代わりに、graphicsLayer 変換またはレイアウトオフセットを使用して、トラッキングされた offset をコンテンツに適用する必要があります。
graphicsLayer ブロック内では、translationX = offset.value.x と translationY = offset.value.y が指の動きに基づいて画像やテキストの描画位置を移動させ、スクロールの視覚効果を生み出します。

scrollable2D を使用してネストされたスクロールを実装する

この例では、双方向コンポーネントを、縦型のニュースフィードなどの標準的な 1 次元の親に統合する方法を示します。

ネストされたスクロールを実装する際は、次の点に注意してください。

rememberScrollable2DState のラムダは、子リストが上限に達したときに親リストが自然に引き継ぐように、使用された差分のみを返す必要があります。
ユーザーが斜め方向にフリングすると、2D 速度が共有されます。アニメーション中に子が境界に達すると、残りの勢いが親に伝播され、スクロールが自然に続行されます。

@Composable
private fun NestedScrollable2DSample() {
    var offset by remember { mutableStateOf(Offset.Zero) }
    val maxScrollDp = 250.dp
    val maxScrollPx = with(LocalDensity.current) { maxScrollDp.toPx() }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .verticalScroll(rememberScrollState())
            .background(Color(0xFFF5F5F5)),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Text(
            "Scroll down to find the 2D Box",
            modifier = Modifier.padding(top = 100.dp, bottom = 500.dp),
            style = TextStyle(fontSize = 18.sp, color = Color.Gray)
        )

        // The Child: A 2D scrollable box with nested scroll coordination
        Box(
            modifier = Modifier
                .size(250.dp)
                .scrollable2D(
                    state = rememberScrollable2DState { delta ->
                        val oldOffset = offset

                        // Calculate new potential offset and clamp it to our boundaries
                        val newX = (oldOffset.x + delta.x).coerceIn(-maxScrollPx, maxScrollPx)
                        val newY = (oldOffset.y + delta.y).coerceIn(-maxScrollPx, maxScrollPx)

                        val newOffset = Offset(newX, newY)

                        // Calculate exactly how much was consumed by the child
                        val consumed = newOffset - oldOffset

                        offset = newOffset

                        // IMPORTANT: Return ONLY the consumed delta.
                        // The remaining (unconsumed) delta propagates to the parent Column.
                        consumed
                    }
                )
                // ...
            contentAlignment = Alignment.Center
        ) {
            Column(horizontalAlignment = Alignment.CenterHorizontally) {
                val density = LocalDensity.current
                Text("2D Panning Zone", color = Color.White.copy(alpha = 0.7f), fontSize = 12.sp)
                Spacer(Modifier.height(8.dp))
                Text("X: ${with(density) { offset.x.toDp().value.roundToInt() }}dp", color = Color.White, fontWeight = FontWeight.Bold)
                Text("Y: ${with(density) { offset.y.toDp().value.roundToInt() }}dp", color = Color.White, fontWeight = FontWeight.Bold)
            }
        }

        Text(
            "Once the Purple Box hits Y: 250 or -250,\nthis parent list will take over the vertical scroll.",
            textAlign = TextAlign.Center,
            modifier = Modifier.padding(top = 40.dp, bottom = 800.dp),
            style = TextStyle(fontSize = 14.sp, color = Color.Gray)
        )
    }
}TwoDimensionalScrollSnippets.kt

図 5. 縦方向にスクロールするリスト内の紫色のボックス。内部で 2D 移動が可能ですが、ボックスの内部 Y オフセットが 300 ピクセルの上限に達すると、縦方向のスクロール制御が親リストに渡されます。

上記のスニペットでは:

2D コンポーネントは、X 軸の動きを内部でパンするために使用できます。同時に、子コンポーネントの垂直方向の境界に達すると、Y 軸の動きを親リストにディスパッチします。
システムは、ユーザーを 2D サーフェス内に閉じ込めるのではなく、消費されたデルタを計算し、残りを階層に渡します。これにより、ユーザーは指を離すことなく、ページの残りの部分をスクロールし続けることができます。

`Modifier.draggable2D` を実装する

個々の UI 要素を移動するには、draggable2D 修飾子を使用します。

コンポーザブル要素をドラッグする

この例は、draggable2D の最も一般的なユースケースを示しています。ユーザーが UI 要素を選択して、親コンテナ内の任意の場所に再配置できるようにします。

@Composable
private fun DraggableComposableElement() {
    // 1. Track the position of the floating window
    var offset by remember { mutableStateOf(Offset.Zero) }

    Box(modifier = Modifier.fillMaxSize().background(Color(0xFFF5F5F5))) {
        Box(
            modifier = Modifier
                // 2. Apply the offset to the box's position
                .offset { IntOffset(offset.x.roundToInt(), offset.y.roundToInt()) }
                // ...
                // 3. Attach the 2D drag logic
                .draggable2D(
                    state = rememberDraggable2DState { delta ->
                        // 4. Update the position based on the movement delta
                        offset += delta
                    }
                ),
            contentAlignment = Alignment.Center
        ) {
            Text("Video Preview", color = Color.White, fontSize = 12.sp)
        }
    }
}TwoDimensionalScrollSnippets.kt

図 6. 灰色の背景上で小さな紫色のボックスが再配置されている様子。ユーザーが指を離すと同時に要素の移動が停止する、直接的な 2D ドラッグのデモ。

上記のコードスニペットには、次のものが含まれています。

offset 状態を使用してボックスの位置を追跡します。
offset 修飾子を使用して、ドラッグのデルタに基づいてコンポーネントの位置を移動します。
フリングがサポートされていないため、ユーザーが指を離すとすぐにボックスの移動が停止します。

親のドラッグエリアに基づいて子コンポーザブルをドラッグする

この例では、draggable2D を使用して、セレクタノブが特定のサーフェス内に制約される 2D 入力領域を作成する方法を示します。コンポーネント自体を移動するドラッグ可能な要素の例とは異なり、この実装では 2D デルタを使用して、カラー選択ツール全体で子コンポーザブル「セレクタ」を移動します。

@Composable
private fun ExampleColorSelector(
    // ...
)  {
    // 1. Maintain the 2D position of the selector in state.
    var selectorOffset by remember { mutableStateOf(Offset.Zero) }

    // 2. Track the size of the background container.
    var containerSize by remember { mutableStateOf(IntSize.Zero) }

    Box(
        modifier = Modifier
            .size(300.dp, 200.dp)
            // Capture the actual pixel dimensions of the container when it's laid out.
            .onSizeChanged { containerSize = it }
            .clip(RoundedCornerShape(12.dp))
            .background(
                brush = remember(hue) {
                    // Create a simple gradient representing Saturation and Value for the given Hue.
                    Brush.linearGradient(listOf(Color.White, Color.hsv(hue, 1f, 1f)))
                }
            )
    ) {
        Box(
            modifier = Modifier
                .size(24.dp)
                .graphicsLayer {
                    // Center the selector on the finger by subtracting half its size.
                    translationX = selectorOffset.x - (24.dp.toPx() / 2)
                    translationY = selectorOffset.y - (24.dp.toPx() / 2)
                }
                // ...
                // 3. Configure 2D touch dragging.
                .draggable2D(
                    state = rememberDraggable2DState { delta ->
                        // 4. Calculate the new position and clamp it to the container bounds
                        val newX = (selectorOffset.x + delta.x)
                            .coerceIn(0f, containerSize.width.toFloat())
                        val newY = (selectorOffset.y + delta.y)
                            .coerceIn(0f, containerSize.height.toFloat())

                        selectorOffset = Offset(newX, newY)
                    }
                )
        )
    }
}TwoDimensionalScrollSnippets.kt

図 7. 白い円形のセレクタノブが付いたカラーグラデーション。任意の方向にドラッグできます。2D デルタがコンテナの境界にクランプされ、選択したカラー値が更新される様子を示しています。

上記のスニペットには、次のものが含まれています。

onSizeChanged 修飾子を使用して、グラデーションコンテナの実際の寸法を取得します。セレクタはエッジの位置を正確に把握しています。
graphicsLayer 内では、ドラッグ中にセレクタが中央に留まるように translationX と translationY を調整します。

ネストされたスクロール修飾子

2 次元スクロール: scrollable2D、draggable2D コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

scrollable2D または draggable2D を選択する