React 拖拽库详解:react-beautiful-dnd
一、react-beautiful-dnd 是什么?
react-beautiful-dnd 是一个 React 拖拽库,主要用于列表排序和列表之间的元素移动。
例如有一个列表:
┌─────────────────────┐
│ A. 商品1 │
├─────────────────────┤
│ B. 商品2 │
├─────────────────────┤
│ C. 商品3 │
├─────────────────────┤
│ D. 商品4 │
└─────────────────────┘
用户把商品 C 拖到商品 A 前面:
┌─────────────────────┐
│ C. 商品3 │
├─────────────────────┤
│ A. 商品1 │
├─────────────────────┤
│ B. 商品2 │
├─────────────────────┤
│ D. 商品4 │
└─────────────────────┘
这个过程实际上分为两部分。
第一部分:拖拽交互。
包括:
- 监听鼠标拖拽。
- 判断当前拖动哪个元素。
- 判断拖动到哪个位置。
- 处理其他元素让位。
- 显示拖拽动画。
这些工作由 react-beautiful-dnd 完成。
第二部分:更新业务数据。
例如:
['A', 'B', 'C', 'D']
变成:
['C', 'A', 'B', 'D']
这部分需要我们自己实现。
这是理解这个库最重要的一点:
react-beautiful-dnd 负责拖拽过程,但不会自动修改你的 React State。
二、先理解三个核心组件
react-beautiful-dnd 最重要的是三个组件:
DragDropContext
Droppable
Draggable
它们之间的关系是:
DragDropContext
│
└── Droppable
│
├── Draggable
│
├── Draggable
│
└── Draggable
可以理解为:
| 组件 | 作用 |
|---|---|
DragDropContext | 管理整个拖拽过程 |
Droppable | 定义允许放置元素的区域 |
Draggable | 定义可以拖动的元素 |
我们分别讲解。
2.1 DragDropContext:拖拽上下文
先看代码:
import { DragDropContext } from 'react-beautiful-dnd';
function App() {
const handleDragEnd = (result) => {
console.log(result);
};
return (
<DragDropContext onDragEnd={handleDragEnd}>
<div>这里放拖拽列表</div>
</DragDropContext>
);
}
它有什么作用?
DragDropContext 是整个拖拽功能的最外层容器。
它负责协调内部的 Droppable 和 Draggable。
可以理解为:
DragDropContext
│
├── 哪个元素开始拖拽?
│
├── 当前拖拽到哪里?
│
├── 哪些元素需要移动?
│
└── 拖拽结束后通知谁?
onDragEnd 是什么?
onDragEnd 是 DragDropContext 的一个必需属性。
它接收一个回调函数。
类型大致如下:
onDragEnd: (result: DropResult) => void
参数:
result:本次拖拽结束的信息。
返回值:
- 不需要返回值。
例如:
<DragDropContext onDragEnd={handleDragEnd}>
意思是:
当用户结束拖拽时,调用 handleDragEnd 函数。
官方文档还提供 onDragStart、onDragUpdate 等生命周期事件,但对于简单排序,通常只需要 onDragEnd。
2.2 Droppable:可放置区域
Droppable 定义一个可以接收拖拽元素的区域。
例如:
<Droppable droppableId="bucket-list">
{(provided) => (
<div>
这里放列表
</div>
)}
</Droppable>
这里有两个需要理解的概念。
droppableId
droppableId="bucket-list"
它是当前拖拽区域的唯一标识。
假设页面上有两个列表:
待分配桶 已分配桶
A C
B D
可以分别定义:
<Droppable droppableId="available">
和:
<Droppable droppableId="assigned">
拖拽结束时,库就能告诉你:
source.droppableId = 'available'
destination.droppableId = 'assigned'
说明元素从待分配区域移动到了已分配区域。
注意: droppableId 必须是字符串,并且在同一个拖拽上下文中保持唯一。
为什么里面是一个函数?
你可能不太熟悉这种写法:
<Droppable droppableId="bucket-list">
{(provided) => (
<div>...</div>
)}
</Droppable>
这是 React 中的 Render Props(渲染属性)模式。
我们先看一个普通函数:
function renderItem(name: string) {
return <div>{name}</div>;
}
调用:
renderItem('商品A');
得到:
<div>商品A</div>
Droppable 的写法类似。
它会调用你传入的函数,并提供一些拖拽相关的属性:
(provided) => (...)
这里的 provided 是库传给你的对象。
你需要把里面的属性绑定到真实 DOM 上。
完整写法:
<Droppable droppableId="bucket-list">
{(provided) => (
<div
ref={provided.innerRef}
{...provided.droppableProps}
>
{/* 拖拽元素 */}
{provided.placeholder}
</div>
)}
</Droppable>
这里有三个重要内容。
① provided.innerRef
ref={provided.innerRef}
React 的 ref 可以用于获取 DOM 元素。
例如:
const divRef = useRef<HTMLDivElement>(null);
return <div ref={divRef}>内容</div>;
React 渲染完成后:
divRef.current
就可以访问对应的 DOM 元素。
而:
ref={provided.innerRef}
是把这个 DOM 元素交给拖拽库。
拖拽库需要知道:
- 这个区域在哪里。
- 宽度是多少。
- 高度是多少。
- 是否允许元素放入。
因此必须正确绑定。
② provided.droppableProps
{...provided.droppableProps}
这里的 ... 是 JSX 的属性展开语法。
假设:
const props = {
id: 'list',
className: 'container',
};
那么:
<div {...props} />
相当于:
<div id="list" className="container" />
同理:
<div {...provided.droppableProps}>
就是把拖拽库提供的属性绑定到 DOM 上。
这些属性主要用于内部识别拖拽区域。
③ provided.placeholder
{provided.placeholder}
这是非常重要的一个元素。
假设原始列表:
A
B
C
D
用户开始拖动 B。
如果 B 直接脱离原来的布局:
A
C
D
列表高度就可能突然变化。
placeholder 的作用是:
在拖拽过程中保留必要的占位空间。
这样列表布局不会突然塌陷。
所以一定要写:
{provided.placeholder}
通常放在可拖拽列表的末尾。
三、Draggable:可拖拽元素
现在我们已经有了一个可放置区域。
接下来需要定义里面的元素。
<Draggable draggableId="bucket-1" index={0}>
{(provided) => (
<div
ref={provided.innerRef}
{...provided.draggableProps}
{...provided.dragHandleProps}
>
商品A
</div>
)}
</Draggable>
我们逐个解释。
3.1 draggableId
draggableId="bucket-1"
它是拖拽元素的唯一标识。
例如:
const buckets = [
{ id: 101, name: '版本1' },
{ id: 102, name: '版本2' },
{ id: 103, name: '版本3' },
];
可以使用:
draggableId={String(item.id)}
注意两个要求:
- 必须是字符串。
- 同一个拖拽上下文中的
draggableId必须唯一。
不要使用数组下标作为 draggableId。
例如:
draggableId={String(index)}
不推荐。
因为拖拽后数组顺序会变化,下标会跟着变化。
正确做法:
draggableId={String(item.ruleId)}
业务 ID 不会随着排序变化。
3.2 index
index={0}
index 表示当前元素在 Droppable 列表中的位置。
例如:
[
{ id: 101, name: '版本1' },
{ id: 102, name: '版本2' },
{ id: 103, name: '版本3' },
]
对应:
版本1 index=0
版本2 index=1
版本3 index=2
这里特别容易混淆:
| 属性 | 含义 | 拖拽后是否变化 |
|---|---|---|
draggableId | 元素身份 | 不变 |
index | 元素当前位置 | 会变化 |
比如版本3拖到第一位:
版本3 index=0
版本1 index=1
版本2 index=2
但是版本3的 draggableId 仍然是 "103"。
3.3 draggableProps
{...provided.draggableProps}
这些属性负责让元素参与拖拽布局。
其中包含拖拽库计算的样式,例如位置变化需要的 transform。
因此,不能随意丢掉这些属性。
3.4 dragHandleProps
{...provided.dragHandleProps}
这个属性比较有意思。
它决定:
用户从哪里开始拖拽。
例如:
<div
ref={provided.innerRef}
{...provided.draggableProps}
{...provided.dragHandleProps}
>
商品A
</div>
表示整个卡片都可以拖动。
但你的原型中有一个拖拽手柄:
┌──────────────────────┐
│ ⠿ 332590-版本1 │
└──────────────────────┘
如果只希望用户拖动左侧图标,可以这样写:
<div
ref={provided.innerRef}
{...provided.draggableProps}
>
<span {...provided.dragHandleProps}>
⠿
</span>
<span>332590-版本1</span>
</div>
注意区别:
<div {...provided.draggableProps}>
作用在整个卡片上。
而:
<span {...provided.dragHandleProps}>
只作用在拖拽手柄上。