企业官网建设流程全解析

react-native-reanimated-dnd是一个专为 React Native 打造的高性能拖拽交互（drag-and-drop）库，基于 Reanimated 4 与 Gesture Handler 构建，能实现流畅的 60fps 动画、拖拽排序列表/网格、碰撞检测，并提供完整的 TypeScript 支持。本教程带你从零安装、到跑通第一个可拖拽、可放置、可排序的交互界面，全程面向新手，代码量极少。

为什么选 react-native-reanimated-dnd

很多拖拽库是从 Web 移植过来的，在移动端要么卡顿、要么早已停更。而这个库是为移动端原生设计的"完整生态"，核心卖点：

💡 一句话记忆：想拖拽 →Draggable，想接住 →Droppable，想排序 →Sortable。

环境要求与一键安装步骤

1. 确认版本兼容

该库依赖几个"搭档"包，需要一起安装。版本对照如下：

⚠️ Reanimated 4要求启用 New Architecture，且 Expo 项目必须用开发构建（development build），不能用 Expo Go。

2. 安装命令

普通 React Native CLI 项目：

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

Expo 项目（SDK 55+）：

npx expo install react-native-reanimated-dnd react-native-reanimated react-native-worklets react-native-gesture-handler

3. 两个必做配置

• Babel 插件：在babel.config.js中把react-native-worklets/plugin放在插件数组的最后一位。
• 根视图包裹：用GestureHandlerRootView包裹整个应用，它是手势识别生效的前提。

安装配置的细节可参考仓库内文档：installation.md。

三个核心组件：DropProvider、Draggable、Droppable

理解拖拽库，先记住它的组件层级结构（上下文通信架构）：

App └── GestureHandlerRootView ← 手势根容器（必需） └── DropProvider ← 创建拖放上下文（必需） ├── Draggable ← 可被拖动的"物品" └── Droppable ← 可接收物品的"区域"

• DropProvider：整个拖放系统的"地基"，负责组件注册、碰撞检测、状态与位置跟踪。所有拖放组件都必须放在它的内部。源码见 context/DropContext.tsx。
• Draggable：被拖动的对象，通过data属性携带数据，源文件 components/Draggable.tsx。
• Droppable：目标区域，通过onDrop回调接收数据，源文件 components/Droppable.tsx。

数据流很简单：Draggable携带的数据，会在被放下时通过Droppable的onDrop回调传递给你。

跑通第一个拖拽示例

下面是最小可运行的"拖到目标区域"示例，跟着写一遍即可上手：

import { GestureHandlerRootView } from "react-native-gesture-handler"; import { DropProvider, Draggable, Droppable } from "react-native-reanimated-dnd"; export default function App() { return ( <GestureHandlerRootView style={{ flex: 1 }}> <DropProvider> <Droppable onDrop={(data) => console.log("放下了:", data)}> <View> <Text>放到这里</Text> </View> </Droppable> <Draggable data={{ id: "1", title: "拖我一下！" }}> <View> <Text>拖我一下！</Text> </View> </Draggable> </DropProvider> </GestureHandlerRootView> ); }

如果能把"拖我一下"拖进"放到这里"的区域，就说明环境已搭好 ✅。完整的验证组件见快速上手文档：quick-start.md。

进阶：用 Sortable 做出拖拽排序列表

当你不想"拖到某处"，而是想拖动列表项重新排序（如音乐播放队列、任务列表）时，就用Sortable+SortableItem。它们会自动处理重排动画与自动滚动，无需你手动管理数组。

使用要点（来自 README 的 Sortable List 示例）：

• 每个数据项必须有字符串类型的id，这是库追踪与重排的依据；
• Sortable通过data传入数组、renderItem渲染每一项、itemHeight指定项高度；
• 可用SortableItem.Handle声明一个专属拖拽手柄区域（如右侧的 ⋮⋮）。

⚠️ 状态管理提醒：排序组件维护内部状态。不要在onMove回调里直接去改外部数组（setItems、Redux 等），onMove只用于埋点、日志等副作用；组件会自动完成内部重排。

组件与 Hook 源码参考：components/Sortable.tsx、components/SortableItem.tsx、hooks/useSortable.ts。

新手常见问题快速排查

更完整的排查清单见 installation.md 的 Troubleshooting 一节。

想直接看完整效果？运行官方示例 App

仓库内置了包含18 个交互式 Demo的示例应用，覆盖基本拖放、拖拽手柄、碰撞检测、边界约束、动态高度、网格排序等全部能力。可先克隆仓库：

git clone https://gitcode.com/gh_mirrors/re/react-native-reanimated-dnd cd react-native-reanimated-dnd npm install

然后按 example-app/README.md 启动，入口在 example-app/App.tsx，示例组件集中在 example-app/components/ 目录下。

小结与下一步

• 用DropProvider+GestureHandlerRootView搭好"地基"；
• 用Draggable/Droppable实现最基本的拖放交互；
• 用Sortable/SortableItem（以及SortableGrid）实现拖拽排序；
• 记住数据项必须有字符串id，排序组件不要手动改外部状态。

接下来建议阅读 basic-concepts.md 理解上下文通信架构，并在 index.ts 中查看当前导出的全部组件、Hooks 与工具函数，逐步解锁更多高级能力。