從滑動式遷移至 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()

AnchoredDraggable

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) }
    )
}

updateAnchors

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

SwipeableState

AnchoredDraggableState

open class SwipeableState(initialValue: T, animationSpec: AnimationSpec = …, confirmStateChange: (T) -> Boolean = …)

class AnchoredDraggableState( initialValue: T, animationSpec: AnimationSpec = …, confirmValueChange: (T) -> Boolean = …, positionalThreshold: Density.(Float) -> Float = …, velocityThreshold: Dp = …)

offset: State

offset: Float
requireOffset()

progress: SwipeProgress

progress: Float [0f..1f]

currentValue: T

currentValue: T

targetValue: T

targetValue: T

direction: Float [-1f, 0f, 1f]

無

suspend animateTo(
targetValue: T,
anim: AnimationSpec = …)

suspend animateTo(
targetState: T,
velocity: Float =
lastVelocity)

suspend snapTo(targetValue: T)

suspend snapTo(targetValue: T)

performDrag(delta: Float)

dispatchRawDelta(delta: Float)

suspend performFling(velocity: Float)

suspend settle(velocity: Float)

isAnimationRunning: Boolean

isAnimationRunning: Boolean

lastVelocity: Float

Modifier.anchoredDraggable

Modifier.swipeable

Modifier.anchoredDraggable

state: SwipeableState

state: AnchoredDraggableState

anchors: Map

AnchoredDraggableState#updateAnchors
or

AnchoredDraggableState#constructor

orientation: Orientation

orientation: Orientation

enabled: Boolean = true

enabled: Boolean = true

reverseDirection: Boolean = false

reverseDirection: Boolean = false

interactionSource: MutableInteractionSource? = null

interactionSource: MutableInteractionSource? = null

thresholds: (from: T, to: T) -> ThresholdConfig = FixedThreshold(56.dp)

以 positionalThreshold 的形式傳遞至 AnchoredDraggableState 建構函式

resistance: ResistanceConfig? = …

尚不支援，如需最新狀態，請參閱 b/288084801。

velocityThreshold: Dp = 125.dp

已傳遞至 AnchoredDraggable 建構函式