从 Swipeable 迁移到 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 的引用，而不是继承它。

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。

定义位置阈值

阈值参数的类型和名称已更改。不再使用单独的 ThresholdConfig 接口，AnchoredDraggableState 具有一个 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