企业官网建设流程全解析

react-native-reanimated-dnd 是一款基于 Reanimated 4 与 Gesture Handler 构建的 React Native 拖拽排序库，提供 60fps 平滑动画、碰撞检测与完整 TypeScript 支持。本教程面向新手，带你从零实现一个可水平滚动的排序列表——无论是标签栏、分类轮播还是自定义工具栏，滑动重排的交互体验只需几行配置就能完成。

🎯 为什么选它：水平排序列表的 5 大核心优势

在 React Native 中实现「按住拖动 → 松手吸附 → 列表自动补位」这套交互，手写通常需要几十行手势与动画代码，而且很容易掉帧。react-native-reanimated-dnd 把这套逻辑封装成了开箱即用的Sortable组件：

• 🚀丝滑 60fps：动画全部运行在 Reanimated 4 的 Worklet 线程，不阻塞 JS 主线程，拖动过程不卡顿
• 📜垂直 + 水平双方向：同一套 API，切换direction属性即可从竖排列表变成横排轮播
• 🌀边缘自动滚动：拖拽靠近列表左右边缘时，列表自动跟随滚动，无需自己写滚动逻辑
• 🧲拖拽手柄模式：可以指定「只有按住小把手才能拖动」，适合卡片中带按钮的复杂 UI
• 📦Tiny + 类型安全：约 70kb 的包体，全量 TypeScript 定义，配合 FlatList 虚拟列表可承载长列表

⚡ 最快安装步骤：3 个依赖搞定环境

水平排序功能属于库的核心能力，安装主包 + 3 个 peer 依赖即可：

npm install react-native-reanimated-dnd npm install react-native-reanimated react-native-gesture-handler react-native-worklets

版本要求：react-native-reanimated4.x、react-native-gesture-handler2.x、react-native-worklets0.7+（见 package.json）。Expo 项目可用npx expo install安装，完整步骤参考 documentation/web-docs/docs/getting-started/installation.md。

🛠️ 3 步实现水平排序列表

第 1 步：准备数据。每条数据必须带一个稳定的id字符串字段：

interface Tag { id: string; label: string; color: string; }

第 2 步：配置Sortable组件。关键是direction="horizontal"，此时itemWidth（每项固定宽度）变为必填参数：

<Sortable data={tags} renderItem={renderTag} direction="horizontal" // 开启水平模式 itemWidth={120} // 水平模式必填：每项宽度 gap={12} // 项间距 paddingHorizontal={16} // 容器左右内边距 />

第 3 步：在renderItem中返回SortableItem。把组件传入的positions、leftBound、autoScrollHorizontalDirection等状态原样透传，库就会自动接管拖拽、动画与重排：

const renderTag = ({ item, id, positions, leftBound, autoScrollHorizontalDirection, itemsCount, itemWidth, gap, paddingHorizontal }) => ( <SortableItem key={id} id={id} data={item} positions={positions} leftBound={leftBound} autoScrollHorizontalDirection={autoScrollHorizontalDirection} itemsCount={itemsCount} direction="horizontal" itemWidth={itemWidth} gap={gap} paddingHorizontal={paddingHorizontal} > <View style={{ backgroundColor: item.color, borderRadius: 20 }}> <Text>{item.label}</Text> </View> </SortableItem> );

运行后你就能获得完整的滑动重排体验：长按约 200ms 触发拖起（源码见 hooks/useHorizontalSortable.ts），拖动中其他项自动让位，松手后弹簧动画归位。下面的动画演示了库的整体拖拽效果：

📐 关键参数配置表：宽度、间距与自动滚动

回调方面，SortableItem提供了完整的拖拽生命周期钩子：onDragStart（拖起）、onDragging（拖动中，可拿到当前悬停项与 X 坐标）、onMove（位置变化）、onDrop（落下，附allPositions全量位置）。完整参数表见 documentation/web-docs/docs/hooks/useHorizontalSortable.md。

🧲 拖拽手柄模式：只按住图标才能重排

如果卡片上有按钮或输入框，整卡可拖会误触。此时用SortableItem.Handle包裹一个小把手，只要注册了手柄，整卡拖拽手势会自动禁用（该逻辑在 hooks/useHorizontalSortable.ts 中实现）：

<SortableItem.Handle> <Icon name="drag-handle" size={16} /> </SortableItem.Handle>

仓库示例应用里就内置了「整卡拖 / 手柄拖」两种模式的切换演示，可直接对照：example-app/components/HorizontalSortableExample.tsx。

🌀 自动滚动原理：拖到边缘 60px 内列表自动跟随

水平列表最常见的痛点是：屏幕一次只显示几个项，要拖到远处的位置必须先手动滚动。这个库把它做成了自动的——拖拽中当项接近左/右边缘（阈值不小于 60px，见 components/sortableUtils.ts），列表会平滑地向对应方向滚动，松手前你能把项一路「送」到列表末端。整个滚动状态通过useHorizontalSortableList的scrollX与autoScroll共享值驱动，列表手动滑动时也能与拖拽状态正确同步。

⚠️ 常见坑与状态管理：onMove 里别急着 setState

这是新手最容易踩的坑：Sortable组件自己维护排序状态，拖动时的重排、动画补位都由内部状态驱动。正确姿势是：

• ✅ 在onMove里做日志、埋点等副作用
• ✅ 在onDrop的allPositions参数中读取最终顺序并持久化
• ❌ 不要在onMove里直接setState重排外部数组，会破坏内部状态导致动画错乱

官方文档明确写了这一条，详见 documentation/web-docs/docs/components/sortable.md。

📈 性能优化清单：4 个要点保证不掉帧

1. 保持 FlatList 虚拟列表：默认开启，项数上百时不要关闭
2. 稳定的 id：数据项的id在重渲染间必须稳定，否则位置映射会错乱
3. 回调记忆化：onMove、onDrop等用useCallback包裹，避免重复创建
4. 拖拽中样式用isMoving切换：透明度、缩放等视觉反馈只在拖起时应用，参考示例应用中标签的高亮处理

🎨 适用场景：4 类高频水平重排交互

• 标签选择器：技术栈标签、关注话题，用户可自定义展示顺序
• 分类轮播：商品分类、频道入口，横向卡片带拖拽手柄
• 导航 Tab / 工具栏：让用户自定义功能入口顺序
• 媒体轮播：图片、视频缩略图按优先级排序

更多场景与完整示例代码见官方文档 documentation/web-docs/docs/examples/horizontal-sortable.mdx。

📚 源码与文档导航

总结

用 react-native-reanimated-dnd 打造水平排序列表只需要记住三件事：装上库和 3 个依赖、给Sortable加上direction="horizontal"和itemWidth、把SortableItem的透传状态接好。长按拖起、边缘自动滚动、弹簧归位动画全部内置，你只需专注设计每项的 UI。从标签栏到媒体轮播，这套滑动重排交互可以直接搬进你的产品里。