本頁面由 Cloud Translation API 翻譯而成。

捲動

捲動修飾符

在元素的內容邊界超過尺寸上限時，使用 verticalScroll 和 horizontalScroll 修飾符可以讓使用者以最簡單的方式捲動元素。只要使用 verticalScroll 和 horizontalScroll 修飾符，就不必平移或偏移內容。

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

回應捲動手勢的簡易垂直清單

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))
        }
    }
}GesturesSnippets.kt

scrollable 修飾符

scrollable 修飾符與捲動修飾符不同，scrollable 會偵測捲動手勢並擷取差異，但不會自動偏移其內容。這個值會改為透過 ScrollableState 委派給使用者，這項修飾符需要此值才能正常運作。

建構 ScrollableState 時，您必須提供 consumeScrollDelta 函式，利用手勢輸入、流暢捲動或快速滑過執行每個捲動步驟時，系統都會叫用該函式，並以像素呈現差異。此函式必須傳回使用的捲動距離量，以確保事件在含有 scrollable 修飾符的巢狀元素時能正確傳播。

下列程式碼片段會偵測手勢並顯示位移數值，但不會使任何元素位移：

@Composable
private 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())
    }
}GesturesSnippets.kt

UI 元素會偵測按下手指並顯示手指位置的數值

巢狀捲動

巢狀捲動是一種系統，其中包含多個捲動元件，這些元件會彼此合作，回應單一捲動手勢並傳達捲動差異 (變更)。

巢狀捲動系統可讓可捲動的元件之間進行協調，並以階層方式連結 (通常是共用相同的父項)。這個系統會連結捲動容器，並允許與捲動差異值互動，這些差異值會在容器之間傳播和共用。

Compose 提供多種方法，可處理可組合項之間的巢狀捲動。在清單中包含另一個清單，是典型的巢狀捲動運用，而較複雜的用途則是收合工具列。

自動巢狀捲動

簡易的巢狀捲動功能無需使用者執行任何動作。觸發捲動動作的手勢會自動從子項套用到父項，因此，當子項無法再捲動畫面時，就會由父項元素處理該手勢。

自動巢狀捲動功能是由部分 Compose 元件和修飾符直接支援並提供，包括：verticalScroll、horizontalScroll、scrollable、Lazy API 與 TextField。這表示當使用者捲動巢狀元件的內部子項時，先前的修飾符會將捲動差異傳播至支援巢狀捲動功能的父項。

以下範例顯示已套用 verticalScroll 修飾符的元素，位於同樣套用 verticalScroll 修飾符的容器中。

@Composable
private fun AutomaticNestedScroll() {
    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)
                    )
                }
            }
        }
    }
}GesturesSnippets.kt

兩個巢狀垂直捲動 UI 元素，回應內部元素的內外手勢

使用 `nestedScroll` 修飾符

如果您需要在多個元素間建立進階協調捲動功能，nestedScroll 修飾符可定義巢狀捲動階層，讓您擁有更多彈性。如前所述，部分元件已內建支援巢狀捲動。不過，像是 Box 或 Column 這類無法自動捲動的可組合元件，便無法在巢狀捲動系統中傳播捲動差異，且差異也無法進入 NestedScrollConnection 或父項元件。如要解決這個問題，您可以使用 nestedScroll 將這類支援權限授予其他元件，包括自訂元件。

巢狀捲動循環

巢狀捲動週期是指捲動差異的流程，這些差異會透過巢狀捲動系統的所有元件 (或節點) 上下調度，例如使用可捲動元件和修飾符，或 nestedScroll。

疊套式捲動週期的階段

當捲動元件偵測到觸發事件 (例如手勢) 時，在實際捲動動作觸發之前，產生的差異值會傳送至巢狀捲動系統，並經歷三個階段：捲動前、節點消耗和捲動後。

巢狀捲動週期的階段

在第一個捲動前階段，收到觸發事件差異值的元件會透過階層樹狀圖，將這些事件向上調度至最頂層的父項。接著，差異事件會向上傳遞，也就是說，差異會從最接近根層的父項傳遞至啟動巢狀捲動週期的子項。

捲動前階段 - 調度向上

這樣一來，巢狀捲動父項 (使用 nestedScroll 或可捲動修飾符的可組合項) 就能在節點本身可使用差異之前，先對差異執行某些操作。

捲動前階段 - 向上傳遞

在節點使用階段，節點本身會使用父項未使用的任何差異。這時捲動動作已完成，且可供查看。

節點消耗階段

在這個階段，子項可以選擇使用所有或部分剩餘的捲動。剩餘的內容會傳回至上一個階段。

最後，在捲動後階段，節點本身未消耗的任何內容都會再次傳送至其祖系節點，以供消耗。

捲動後階段 - 調度

捲動後階段的運作方式與捲動前階段類似，其中任何父項都可以選擇是否要使用。

捲動後階段 - 向上傳遞

與捲動類似，當拖曳手勢完成時，使用者的意圖可能會轉譯為用於彈跳 (使用動畫捲動) 可捲動容器的速度。彈跳也是巢狀捲動週期的一部分，拖曳事件產生的速度會經歷類似的階段：彈跳前、節點消耗和彈跳後。請注意，快速滑動動畫只與觸控手勢相關聯，不會由其他事件 (例如 a11y 或硬體捲動) 觸發。

參與巢狀捲動循環

參與這個循環，代表攔截、使用及回報沿著階層使用差異值的情形。Compose 提供一組工具，可影響巢狀捲動系統的運作方式，以及如何直接與該系統互動，例如在捲動式元件開始捲動之前，您需要對捲動差異值執行某些操作時。

如果巢狀捲動週期是針對節點鏈結運作的系統，則 nestedScroll 修飾符是一種攔截並插入這些變更的方式，並影響在鏈結中傳播的資料 (捲動差異)。這個修飾符可放在階層中的任何位置，並與樹狀結構中的巢狀捲動修飾符例項通訊，以便透過這個管道分享資訊。這個修飾符的構件為 NestedScrollConnection 和 NestedScrollDispatcher。

NestedScrollConnection 提供一種方法，可回應巢狀捲動週期的各個階段，並影響巢狀捲動系統。它由四個回呼方法組成，每個方法代表一個使用階段：前/後捲動和前/後彈跳：

val nestedScrollConnection = object : NestedScrollConnection {
    override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
        println("Received onPreScroll callback.")
        return Offset.Zero
    }

    override fun onPostScroll(
        consumed: Offset,
        available: Offset,
        source: NestedScrollSource
    ): Offset {
        println("Received onPostScroll callback.")
        return Offset.Zero
    }
}GesturesSnippets.kt

每個回呼也會提供有關傳播的差異值的資訊：該特定階段的 available 差異值，以及先前階段使用的 consumed 差異值。如果您在任何時間點想要停止向上傳播差異，可以使用巢狀捲動連結來執行此操作：

val disabledNestedScrollConnection = remember {
    object : NestedScrollConnection {
        override fun onPostScroll(
            consumed: Offset,
            available: Offset,
            source: NestedScrollSource
        ): Offset {
            return if (source == NestedScrollSource.SideEffect) {
                available
            } else {
                Offset.Zero
            }
        }
    }
}GesturesSnippets.kt

所有回呼都會提供 NestedScrollSource 類型的資訊。

NestedScrollDispatcher 會初始化巢狀捲動週期。使用調度器並呼叫其方法會觸發循環。可捲動的容器具有內建調度器，可將手勢期間擷取的差異值傳送至系統。因此，在大多數自訂巢狀捲動功能的用途中，都會使用 NestedScrollConnection 而非調度器，以便回應現有的差異，而非傳送新的差異。如需瞭解更多用途，請參閱 NestedScrollDispatcherSample。

在捲動時調整圖片大小

您可以為使用者捲動畫面時建立動態視覺效果，讓圖片根據捲動位置變更大小。

根據捲動位置調整圖片大小

這個程式碼片段示範如何根據垂直捲動位置，在 LazyColumn 中調整圖片大小。圖片會隨著使用者向下捲動而縮小，向上捲動時則會放大，並維持在指定的最小和最大大小範圍內：

@Composable
fun ImageResizeOnScrollExample(
    modifier: Modifier = Modifier,
    maxImageSize: Dp = 300.dp,
    minImageSize: Dp = 100.dp
) {
    var currentImageSize by remember { mutableStateOf(maxImageSize) }
    var imageScale by remember { mutableFloatStateOf(1f) }

    val nestedScrollConnection = remember {
        object : NestedScrollConnection {
            override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
                // Calculate the change in image size based on scroll delta
                val delta = available.y
                val newImageSize = currentImageSize + delta.dp
                val previousImageSize = currentImageSize

                // Constrain the image size within the allowed bounds
                currentImageSize = newImageSize.coerceIn(minImageSize, maxImageSize)
                val consumed = currentImageSize - previousImageSize

                // Calculate the scale for the image
                imageScale = currentImageSize / maxImageSize

                // Return the consumed scroll amount
                return Offset(0f, consumed.value)
            }
        }
    }

    Box(Modifier.nestedScroll(nestedScrollConnection)) {
        LazyColumn(
            Modifier
                .fillMaxWidth()
                .padding(15.dp)
                .offset {
                    IntOffset(0, currentImageSize.roundToPx())
                }
        ) {
            // Placeholder list items
            items(100, key = { it }) {
                Text(
                    text = "Item: $it",
                    style = MaterialTheme.typography.bodyLarge
                )
            }
        }

        Image(
            painter = ColorPainter(Color.Red),
            contentDescription = "Red color image",
            Modifier
                .size(maxImageSize)
                .align(Alignment.TopCenter)
                .graphicsLayer {
                    scaleX = imageScale
                    scaleY = imageScale
                    // Center the image vertically as it scales
                    translationY = -(maxImageSize.toPx() - currentImageSize.toPx()) / 2f
                }
        )
    }
}AnimateImageSnippets.kt

程式碼的重點

這個程式碼會使用 NestedScrollConnection 攔截捲動事件。
onPreScroll 會根據捲動差異計算圖片大小的變化。
currentImageSize 狀態變數會儲存圖片目前的大小，並受到 minImageSize 和 maxImageSize. imageScale 之間的限制，這些值皆衍生自 currentImageSize。
LazyColumn 會根據 currentImageSize 進行偏移。
Image 會使用 graphicsLayer 修飾符套用計算的比例。
graphicsLayer 中的 translationY 可確保圖片在縮放時保持垂直置中。

結果

上述程式碼片段會在捲動時產生縮放圖片效果：

圖 1。捲動時的縮放圖片效果。

巢狀捲動互通性

如果想在捲動式可組合項中建立巢狀捲動 View 元素 (或相反情況)，可能會發生問題。最容易判別的情況，就是當將子項捲動到開頭或尾端時，本應由父項接續捲動，但這項預期行為可能不會發生，或是實際運作方式和預期內容不同。

這可能是由於捲動式可組合元件內建的預期情況所導致的。捲動式可組合元件具有「預設建立巢狀捲動」的規則，因此任何可以捲動的容器都必須加入巢狀捲動鏈結，包括透過 NestedScrollConnection 方式作為父項，以及透過 NestedScrollDispatcher 方式作為子項。當子項抵達邊界時，就會對父項驅動巢狀捲動。舉例來說，這項規則可以讓您同時正常使用 Compose Pager 和 Compose LazyRow。不過，如果使用 ViewPager2 或 RecyclerView 達成互通性捲動，則由於這些元件並未實作 NestedScrollingParent3，因此子項無法將捲動延續到父項。

如果想啟用可在捲動式 View 與捲動式可組合元件之間同時使用的巢狀捲動互通性 API，讓兩個方向皆使用巢狀結構，那麼在以下情況中，您可以使用巢狀捲動互通性 API 緩解這類問題。

含有子項 `ComposeView` 的合作執行父項 `View`

合作執行父項 View 已經實作 NestedScrollingParent3，因此可以從合作執行的巢狀子項可組合元件接收捲動差異。在這種情況下，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>touchinput_gestures_nested_scroll_interop.xml

您需要在「Activity」(活動) 或「Fragment」(片段) 中設定子項可組合元件，以及必要的 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())
                        }
                    }
                }
            }
        }
    }
}GesturesSnippets.kt

含有子項 `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)
                    }
            }
        )
    }
}

最後，這個範例可以說明如何透過 BottomSheetDialogFragment 使用巢狀捲動互通性 API，藉此成功達成拖曳和關閉行為：

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 元件。如要解決這個問題，請務必同時將捲動修飾符設定為這些巢狀可組合元件的類型。欲知更多詳情，請參考上述的巢狀捲動一節。

含有子項 `ComposeView` 的非合作執行父項 `View`

非合作執行的 View 並未在 View 端實作必要的 NestedScrolling 介面。請注意，這代表具有 Views 的巢狀捲動互通性無法供您馬上使用。非合作執行的 Views 為 RecyclerView 和 ViewPager2。

為您推薦

注意：系統會在 JavaScript 關閉時顯示連結文字
瞭解手勢
將 CoordinatorLayout 遷移至 Compose
在 Compose 中使用 View

輕觸並按下

拖曳、滑動及快速滑過