react-beautiful-dnd

2 阅读5分钟

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)}

注意两个要求:

  1. 必须是字符串。
  2. 同一个拖拽上下文中的 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}>

只作用在拖拽手柄上。