從滑動式遷移至 AnchoredDraggable

Swipeable 是 Compose Material API，可協助您建構可在不同狀態之間滑動切換的元件，例如底部功能表、抽屜或滑動關閉。為進一步支援進階用途 (例如依元件大小而定的錨點)，Compose-Foundation 1.6.0-alpha01 發布了後繼版本：AnchoredDraggable。AnchoredDraggable 是 Foundation API，可用於建構具有固定狀態的可拖曳元件，例如底部功能表、抽屜或滑動關閉。

Material 的 Swipeable API 已淘汰，並將在日後推出的版本中移除，改用 Foundation 的 AnchoredDraggable。本指南將說明如何從 Swipeable API 遷移至 AnchoredDraggable。

將 SwipeableState 遷移至 AnchoredDraggableState

首先，請找出狀態持有人的變更內容。AnchoredDraggableState 無法繼承，且偏移量會在初始化前以 Float.NaN 表示。

更新狀態容器

AnchoredDraggableState 是最終類別，也就是無法繼承的類別。如果現有元件會繼承 SwipeableState，請更新狀態容器，讓其保留 AnchoredDraggableState 的參照，而非繼承自 AnchoredDraggableState：

class MySwitchState: SwipeableState()

class MySwitchState {
    private val anchoredDraggableState = AnchoredDraggableState(...)
}

由於狀態持有者不再從 SwipeableState 繼承，您可能必須自行公開 API。您可以使用的最常見 API 包括 offset、progress、currentValue 和 targetValue。

存取偏移量

與 Swipeable 不同，AnchoredDraggableState 的 offset 在初始化前為 Float.NaN。在 AnchoredDraggable 中，錨點可以傳遞至 AnchoredDraggableState 的建構函式，或透過 AnchoredDraggableState#updateAnchors 進行更新。將錨點傳遞至 AnchoredDraggableState 建構函式，即可立即初始化偏移量。

如果錨點依賴版面配置或可能變更，請使用 AnchoredDraggableState#updateAnchors，避免在錨點變更時重新建立狀態。

如果您使用 updateAnchors，偏移量會在將錨點傳遞至 updateAnchors 之前為 Float.NaN。為避免意外將 Float.NaN 傳遞至元件，請使用 AnchoredDraggableState#requireOffset，要求在讀取偏移量時先完成初始化。這有助於您及早發現不一致性或可能的錯誤。

@Composable
fun AnchoredDraggableBox() {
    val state = remember { AnchoredDraggableState(...) }
    val density = LocalDensity.current
    val anchors = remember { DraggableAnchors { ... } }
    SideEffect {
        state.updateAnchors(anchors)
    }
    Box(
        Modifier.offset { IntOffset(x = state.requireOffset(), y = 0) }
    }
}

將 Modifier.swipeable 遷移至 Modifier.anchoredDraggable

Modifier.anchoredDraggable() 取代 Modifier.swipeable。Modifier.swipeable() 的部分參數已直接移至 AnchoredDraggableState，如以下各節所述。

定義錨點

使用 DraggableAnchors 建構工具方法定義錨點。然後將這些值傳遞至 AnchoredDraggableState#updateAnchors 或 AnchoredDraggableState 的建構函式：

enum class DragValue { Start, Center, End }

@Composable
fun AnchoredDraggableBox() {
    val anchors = DraggableAnchors {
        Start at -100.dp.toPx()
        Center at 0f
        End at 100.dp.toPx()
    }
    val state = remember {
        AnchoredDraggableState(anchors = anchors)
    }
    Box(
        Modifier.offset { IntOffset(x = state.requireOffset(), y = 0) }
    )
}

enum class DragValue { Start, Center, End }

@Composable
fun AnchoredDraggableBox() {
    val state = remember { AnchoredDraggableState(...) }
    val density = LocalDensity.current
    val anchors = with (density) {
        DraggableAnchors {
            Start at -100.dp.toPx()
            Center at 0f
            End at 100.dp.toPx()
        }
    }
    SideEffect {
        state.updateAnchors(anchors)
    }
    Box(
        Modifier.offset { IntOffset(x = state.requireOffset(), y = 0) }
    )
}

如果錨點為靜態，請將其傳遞至建構函式。如果這些值依賴版面配置，或並非靜態值，請使用 updateAnchors。

定義位置門檻

門檻參數的類型和名稱已變更。AnchoredDraggableState 沒有獨立的 ThresholdConfig 介面，而是有 positionalThreshold 參數，該參數會接受 lambda 函式，並傳回閾值的位置。舉例來說，位置門檻為 50% 可以表示為：

val anchoredDraggableState = AnchoredDraggableState(
    positionalThreshold = { distance -> distance * 0.5f },
    ...
)

56dp 的位置門檻可表示為：

val density = LocalDensity.current
val anchoredDraggableState = AnchoredDraggableState(
    positionalThreshold = { with(density) { 56.dp.toPx() } },
    ...
)

定義速度閾值

速度門檻值也會傳遞至 AnchoredDraggableState 的建構函式，並以 lambda 表示：

val density = LocalDensity.current
val anchoredDraggableState = AnchoredDraggableState(
    velocityThreshold = { with(density) { 125.dp.toPx() } },
    ...
)

API 介面的變更

請參閱下方 API 介面變更的總覽。

AnchoredDraggableState

Modifier.anchoredDraggable