边界约束完全掌握:用 react-native-reanimated-dnd 实现轴向锁定与范围限制拖拽
边界约束完全掌握:用 react-native-reanimated-dnd 实现轴向锁定与范围限制拖拽
react-native-reanimated-dnd 是一款基于 Reanimated 4 构建的 React Native 拖放(drag-and-drop)库,提供 60fps 流畅动画、可排序列表/网格、碰撞检测与完整的 TypeScript 支持。本指南聚焦两大核心约束能力——轴向锁定(dragAxis)与范围限制(dragBoundsRef),帮助新手快速掌握如何把拖拽行为精确控制在想要的方向和区域内。
📌 两个核心属性,看懂约束的本质
react-native-reanimated-dnd 通过两个属性覆盖所有边界约束需求,理解它们是掌握受控拖拽的关键:
| 属性 | 作用 | 一句话理解 |
|---|---|---|
dragAxis |
轴向锁定 | 决定"能不能往某方向移动" |
dragBoundsRef |
范围限制 | 决定"最多能移到哪里" |
两者可以独立使用,也可以叠加,组合后就是你想要的"有方向 + 有边界"的精确拖拽体验。
🎯 轴向锁定:dragAxis 只允许一个方向
dragAxis 属性将拖拽行为限制在单一轴上,支持 "x"、"y" 或 "both"(默认)三种取值:
// 仅水平移动
<Draggable data={data} dragAxis="x">...</Draggable>
// 仅垂直移动
<Draggable data={data} dragAxis="y">...</Draggable>
// 自由移动(默认,可省略)
<Draggable data={data} dragAxis="both">...</Draggable>
经典场景:自定义滑块控件
dragAxis="x" 最实用的场景就是构建滑块。配合 onDragging 回调,把位移 tx 换算成 0~1 的比例值:
<Draggable
data={{ type: "slider" }}
dragAxis="x"
onDragging={({ tx }) => {
const normalized = Math.max(0, Math.min(1, (tx + 150) / 300));
onValueChange(normalized);
}}
>
<View style={styles.thumb} />
</Draggable>
📖 更多轴向约束交互示例见 axis-constraints.mdx
📐 范围限制:dragBoundsRef 把拖拽项关进"笼子"
想让拖拽项绝对不能逃出某个容器,用 dragBoundsRef 传入一个指向边界 View 的 ref:
const boundsRef = useRef<View>(null);
<DropProvider>
<View ref={boundsRef} style={styles.container}>
<Draggable data={data} dragBoundsRef={boundsRef}>
<View><Text>我出不去</Text></View>
</Draggable>
</View>
</DropProvider>
dragBoundsRef 指向的 View 可以是父容器或任意兄弟节点,只要它在拖拽开始前已完成布局,库就会自动测量其位置和尺寸,并在每次位移更新时做 clamp 钳制,确保拖拽项的边缘永远不会越过边界。
边界约束的内部原理
useDraggable 在每次 onUpdate 时计算允许的位移范围,核心逻辑:
minTx = boundsX - originX
maxTx = boundsX + boundsWidth - originX - itemWidth
minTy / maxTy 同理
newTx = Math.max(minTx, Math.min(newTx, maxTx))
整个过程运行在 UI 线程的 worklet 中,不阻塞主线程,保证 60fps 流畅体验。核心实现见 hooks/useDraggable.ts。
⚡ 组合使用:轴向锁定 + 范围限制 = 精确滑块
把两个属性叠加,就能实现"在轨道内只能水平滑动"的精确控件,这是音量条、亮度调节器、进度滑块的标准实现模式:
const trackRef = useRef<View>(null);
<Draggable
data={{ type: "slider" }}
dragAxis="x"
dragBoundsRef={trackRef}
>
<View style={styles.thumb} />
</Draggable>
🖼️ 看看拖拽的流畅效果
🛠️ 常见实战场景速查表
| 场景 | 推荐配置 |
|---|---|
| 水平滑块 / 音量条 | dragAxis="x" + dragBoundsRef |
| 垂直滑块 / 亮度条 | dragAxis="y" + dragBoundsRef |
| 绘图画布贴纸 | dragBoundsRef(自由移动,不超出画布) |
| 游戏棋盘棋子 | dragBoundsRef + onDragging 做格子对齐 |
| 表单方向输入控件 | dragAxis="y" |
⚠️ 新手常见坑点
1. 边界 View 必须先完成布局
dragBoundsRef 指向的 View 必须在拖拽开始时已渲染完成。若测量失败,控制台会打印警告,拖拽项将暂时不受约束,直到下次测量成功。
2. dragAxis 是响应式的,可动态切换
用 useState 管理轴向值,运行时更新即可实时改变约束方向,无需卸载重建组件:
const [axis, setAxis] = useState<"x" | "y" | "both">("both");
<Draggable data={data} dragAxis={axis}>...</Draggable>
3. 边界约束不影响碰撞检测
dragBoundsRef 只限制物理移动范围,碰撞检测(collisionAlgorithm)仍正常工作,拖拽项依然可以与边界内的 Droppable 区域正常交互。
4. 暂不支持自定义角度
dragAxis 目前只支持 "x"、"y"、"both" 三种取值,不支持对角线或任意角度约束。
📁 相关文件导航
| 文件 | 说明 |
|---|---|
| hooks/useDraggable.ts | 核心 hook,包含轴向/边界约束的全部实现逻辑 |
| types/draggable.ts | dragAxis、dragBoundsRef 等属性的完整类型定义 |
| components/Draggable.tsx | Draggable 组件封装与 Handle 子组件 |
| documentation/web-docs/docs/guides/constraints-bounds.md | 官方约束与边界指南 |
| documentation/web-docs/docs/examples/axis-constraints.mdx | 轴向约束完整示例(含动态切换) |
| documentation/web-docs/docs/examples/bounded-dragging.mdx | 边界拖拽完整示例(含多种边界类型) |
| example-app/components/examples/BoundedDraggingExample.tsx | 示例 App 中的边界拖拽可运行组件 |
掌握 dragAxis 和 dragBoundsRef 这两个属性,就能用 react-native-reanimated-dnd 实现绝大多数受控拖拽场景,从简单滑块到游戏棋盘,轻松搞定 🎉
