Compose には、ユーザー インタラクションによって生成された操作の検出に役立つさまざまな API が用意されています。幅広いユースケースに対応する 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 }
)
}
もっと柔軟性が必要な場合は、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())
}
}
ネスト スクロール
Compose は、複数の要素が単一のスクロール操作に反応する「ネスト スクロール」をサポートしています。ネスト スクロールの一般的な例としては、別のリストに含まれるリストがあります。より複雑なケースとしては、折りたたみツールバーがあります。
自動ネスト スクロール
シンプルなネスト スクロールでは、アプリ側のアクションは必要ありません。スクロール アクションを開始する操作は、子から親に自動的に伝播されます。これにより、子がそれ以上スクロールできなくなると、親要素によって操作が処理されます。
自動ネスト スクロールは Compose のいくつかのコンポーネントと修飾子(verticalScroll
、horizontalScroll
、scrollable
、Lazy
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)
)
}
}
}
}
nestedScroll 修飾子を使用する
複数の要素の間で高度に調整されたスクロールを作成する必要がある場合は、nestedScroll
修飾子を使用すると、ネスト スクロール階層を定義することにより柔軟性を高めることができます。前のセクションで説明したように、一部のコンポーネントには、ネスト スクロールのサポートが組み込まれています。ただし、自動的にスクロールできないコンポーザブル(Box
や Column
など)の場合、そのようなコンポーネントのスクロールのデルタは、ネスト スクロール システム内で伝播せず、デルタは NestedScrollConnection
にも親コンポーネントにも到達しません。このための対応策として、nestedScroll
を使用すると、カスタム コンポーネントを含む他のコンポーネントでもそのようなサポートを利用できるようになります。
ネストされたスクロールの相互運用(Compose 1.2.0 以降)
スクロール可能なコンポーザブルにスクロール可能な 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
とコンポーザブルの間に必要なグルーロジックを追加できます。
頻繁に使用されるユースケースでは、以下の例のように、CoordinatorLayout
、CollapsingToolbarLayout
、子コンポーザブルを使用します。
<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
をセットアップする必要があります。
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
で使用して、ドラッグして閉じる動作を実現する方法を示しています。
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
レベルに送信します。これにより、その要素はネスト スクロールに参加できるようになりますが、要素のスクロールは自動的には有効になりません。自動的にスクロールできないコンポーザブル(Box
や Column
など)には、そのようなコンポーネントのスクロールのデルタは、ネスト スクロール システム内で伝播せず、デルタは rememberNestedScrollInteropConnection()
が提供する NestedScrollConnection
にも到達しないため、それらのデルタは親である View
コンポーネントにも到達しません。この問題を解決するには、scrollable 修飾子をこれらのタイプのネストされたコンポーザブルにも設定します。詳細については、ネスト スクロールに関する前のセクションをご覧ください。
子 ComposeView を含んでいる連携しない親 View
連携しない View とは、View
側で必要な NestedScrolling
インターフェースを実装していない View のことです。つまり、こうした Views
とのネスト スクロールの相互運用は、そのままでは機能しません。連携しない Views
は、RecyclerView
と ViewPager2
です。
ドラッグ
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
}
}
)
}
スワイプ
swipeable
修飾子を使用すると、要素を離したときに、通常は 1 つの方向に定義された 2 つ以上のアンカー ポイントに向かって移動するアニメーションが表示されるような方法で、要素をドラッグできます。この修飾子は、「スワイプして閉じる」パターンを実装するためによく使用されます。
この修飾子は要素を移動せず、操作の検出のみを行う点に注意してください。たとえば、offset
修飾子を使用して要素を移動することにより、状態を保持して画面上で表現する必要があります。
スワイプ可能な状態は swipeable
修飾子で必須であり、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)
)
}
}
マルチタッチ: パン、ズーム、回転
パン、ズーム、回転に使用されるマルチタッチ操作を検出するには、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()
)
}
ズーム、パン、回転を他の操作と組み合わせる必要がある場合は、PointerInputScope.detectTransformGestures
検出機能を使用できます。