ant-design List 网格拖拽排序实战:基于 dnd-kit 手柄(Handler)方案的完整实现解析

原创2026-09-07 18:12:341,909 阅读
文章标签:UI组件设计系统前端React

ant-design List 网格拖拽排序实战:基于 dnd-kit 手柄(Handler)方案的完整实现解析

导读

在 ant-design 的 List 组件中实现「卡片网格 + 拖拽排序」是一个高频但需要组合技巧的需求:官方组件本身不具备拖拽能力,因此社区通用的做法是集成第三方拖拽库 dnd-kit。本文以仓库内 grid-drag-sorting-handler 示例 为骨架,完整解析「自定义元素 + 拖拽手柄(drag handle)」方案的架构设计、逐步实现与底层原理——读者将掌握:如何用 useSortable 包装 List.Item、如何通过 Context 把"仅手柄可拖拽"的能力注入到卡片标题栏,以及 grid 栅格布局在源码中究竟是如何计算列宽并渲染的。

一、需求场景与方案总览

拖拽排序在数据卡片、看板、可配置仪表盘等界面中十分常见。原文档的诉求非常聚焦:

使用自定义元素和拖拽手柄,我们可以集成 dnd-kit 来实现网格布局的拖拽排序。

拆解这句话,可以提炼出三个关键点:

  1. 网格布局(grid layout):基于 List 的 grid 属性,将条目渲染为多列卡片;
  2. 自定义元素(custom components):拖拽能力不依赖组件库,而是由使用者自定义的 List.Item 包装层接入;
  3. 拖拽手柄(drag handle):并非整行可拖,而是仅通过标题栏中一个 HolderOutlined 图标触发拖拽,避免拖动与卡片内其他交互冲突。

与本示例配套的还有三个同族示例,可以对照阅读、理解差异:

示例 布局 拖拽方式 说明
grid-drag-sorting.tsx 网格 整卡片可拖 无手柄版,拖拽监听直接绑定在 List.Item 上
drag-sorting-handler.tsx 单列 仅手柄可拖 本示例的纵向列表版本
drag-sorting.tsx 单列 整行可拖 基础的拖拽排序演示

二、环境准备:dnd-kit 依赖与 ant-design 基础

在开始编码前,需要确保安装了 dnd-kit 系列包。从 package.json 可以看到,本仓库在开发示例中使用的版本为:

"@dnd-kit/core": "^6.3.1",
"@dnd-kit/modifiers": "^9.0.0",
"@dnd-kit/sortable": "^10.0.0",
"@dnd-kit/utilities": "^3.2.2"

在你的业务项目中,对应的安装命令为:

npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
# 若需要限制拖拽轴向等能力,再安装:npm install @dnd-kit/modifiers

同时引入 ant-design 的 List、Card、Button 以及图标 HolderOutlined。需要说明的是,List 组件在当前版本已被标记为 deprecated(详见 components/list/index.tsx 中的 dev 警告:建议 6.6.0 及以后使用 Listy 替代),但 List 仍是存量业务中最常用的列表组件,本文示例的网格拖拽方案在迁移到 Listy 时同样适用,因为拖拽逻辑完全建立在 dnd-kit 之上,与具体列表组件解耦。

三、整体骨架:DndContext → SortableContext → List

拖拽排序的容器关系遵循 dnd-kit 的标准三层结构,完整示例源码 中的渲染部分如下:

<DndContext onDragEnd={onDragEnd} id="list-grid-drag-sorting-handler">
  <SortableContext items={data.map((i) => i.key)}>
    <List
      grid={{ gutter: 16, column: 4 }}
      dataSource={data}
      renderItem={(item) => (
        <SortableListItem key={item.key} itemKey={item.key}>
          <Card title={<><DragHandle />{item.title}</>}>
            Card content
          </Card>
        </SortableListItem>
      )}
    />
  </SortableContext>
</DndContext>

三者职责分别是:

  • DndContext:拖拽的根上下文,统一管理传感器、冲突检测与拖拽事件,并声明 id(在 React StrictMode 或存在多个拖拽上下文时用于标识隔离);
  • SortableContext:声明参与排序的元素集合,items 接收每个条目的唯一 id 数组(这里取数据项的 key);
  • List:ant-design 组件本体,只负责网格排版与渲染,对拖拽完全无感知——这正是"拖拽与 UI 组件解耦"的设计体现。

注意 renderItem 返回的 SortableListItem 是自定义组件(即原文档所说的"自定义元素"),它接收 key(React 列表标识)与 itemKey(dnd-kit 排序 id),二者都是数据项的 key 值。为每个条目显式指定稳定的唯一 id,是 dnd-kit 排序正确性的前提——示例中的 6 条数据形如 { key: 1, title: 'Title 1' } 至 { key: 6, title: 'Title 6' }。

grid 属性与栅格渲染

grid={{ gutter: 16, column: 4 }} 表示卡片间距 16px、每行 4 列。从 components/list/index.tsx 可以查到 grid 的完整类型定义:

export interface ListGridType {
  gutter?: RowProps['gutter'];
  column?: ColumnCount;
  xs?: ColumnCount;
  sm?: ColumnCount;
  md?: ColumnCount;
  lg?: ColumnCount;
  xl?: ColumnCount;
  xxl?: ColumnCount;
  xxxl?: ColumnCount;
}

其中 column 是基准列数,xs/sm/md/lg/xl/xxl/xxxl 则是响应式断点列数。源码第 248-274 行的实现逻辑可以印证栅格渲染原理:

  1. 当 grid 中存在响应式断点键时,调用 useBreakpoint 订阅视口尺寸;
  2. 计算出当前命中的断点后,取对应断点的列数(否则回退到 grid.column);
  3. 将列数换算为百分比宽度,width 与 maxWidth 均为 100 / columnCount %;
  4. 最终由 ant-design 的 Row 承担容器、每个条目被包进独立的 <div style={colStyle}> 内,实现均分多列排版。

这意味着本示例中 column: 4 时每列约 25% 宽。值得注意的约束是:每一条目被包裹进 List 内部产生的额外 div 后,renderItem 返回的 List.Item 并不是直系 Row 子元素——这对拖拽时的层级判定有一定影响,dnd-kit 的碰撞检测基于 DOM 几何位置计算,因此多层 DOM 包裹并不会破坏拖拽,只要排序 id 与条目一一对应即可。

四、数据更新:onDragEnd 与 arrayMove

拖拽结束后,需要根据起止位置重排数据。示例的完整逻辑为:

const onDragEnd = ({ active, over }: DragEndEvent) => {
  if (!active || !over) {
    return;
  }
  if (active.id !== over.id) {
    setData((prevState) => {
      const activeIndex = prevState.findIndex((i) => i.key === active.id);
      const overIndex = prevState.findIndex((i) => i.key === over.id);
      return arrayMove(prevState, activeIndex, overIndex);
    });
  }
};

几个实现要点:

  • active 是被拖拽项、over 是当前悬停目标项,解构自 DragEndEvent;
  • 空值保护:active 或 over 可能为空(如拖到列表外取消),必须先行返回;
  • 位置未变化保护:active.id === over.id 时直接返回,避免无意义的 state 更新与重渲染;
  • 位置换算:dnd-kit 全程只认 id,因此要用 findIndex 把 id 映射回数组下标;
  • 重排工具:arrayMove 来自 @dnd-kit/sortable,返回一个把元素从 activeIndex 移到 overIndex 的新数组,天然满足 React 不可变更新的要求。

由于使用了函数式 setData((prevState) => ...),即使拖拽回调因并发渲染拿到旧闭包,也能基于最新状态计算,是 React 18 并发模式下的稳妥写法。

五、核心自定义元素:用 useSortable 包装 List.Item

要让一个 List.Item 成为可排序节点,需要调用 dnd-kit 的 useSortable Hook,并把返回的 ref、样式等接入到 DOM 上。示例源码 中该组件接收所有 List.Item 属性并附加拖拽所需信息:

const SortableListItem: React.FC<GetProps<typeof List.Item> & { itemKey: number }> = (props) => {
  const { itemKey, style, ...rest } = props;

  const {
    attributes,
    listeners,
    setNodeRef,
    setActivatorNodeRef,
    transform,
    transition,
    isDragging,
  } = useSortable({ id: itemKey });

  const listStyle: React.CSSProperties = {
    ...style,
    transform: CSS.Translate.toString(transform),
    transition,
    ...(isDragging ? { position: 'relative', zIndex: 9999 } : {}),
  };

  const memoizedValue = useMemo<SortableListItemContextProps>(
    () => ({ setActivatorNodeRef, listeners, attributes }),
    [setActivatorNodeRef, listeners, attributes],
  );

  return (
    <SortableListItemContext.Provider value={memoizedValue}>
      <List.Item {...rest} ref={setNodeRef} style={listStyle} />
    </SortableListItemContext.Provider>
  );
};

这里逐一说明每个 Hook 返回值的用途:

返回值 作用
setNodeRef 绑定到 List.Item 的 ref,标记可排序 DOM 节点的边界,供碰撞检测使用
setActivatorNodeRef 标记"拖拽触发元素"的 ref,配合下方的 Context 传递给手柄按钮
attributes / listeners dnd-kit 生成的 ARIA 无障碍属性与指针/键盘事件监听(如 role、tabIndex、onKeyDown 等),需展开到触发元素上
transform 拖拽位移向量,用于让被拖元素跟随指针移动
transition 排序交互动画所需的 CSS transition 值
isDragging 当前是否处于拖拽状态,可据此提升层级、添加样式

样式合并的关键细节:因为外层可能已经向 List.Item 传入自定义 style(例如栅格列的布局样式),所以需要用展开运算符把原 style 合并进新的 listStyle,再拼接上 dnd-kit 的位移。位移通过 CSS.Translate.toString(transform) 序列化为 transform CSS 值——dnd-kit 的位移是"视觉偏移",被拖元素其实仍占据原文档流位置,排序的"让位"效果由其他条目根据碰撞情况平滑过渡实现,这正是 transition 需要保留的原因。

isDragging 为真时设置 position: 'relative' 与 zIndex: 9999,将正在拖拽的卡片提到最上层,避免被同层级的兄弟卡片遮挡。

交互式无障碍(ARIA)注意点

把 attributes 与 listeners 完全展开到 DOM 元素上是 dnd-kit 无障碍支持的一部分:键盘用户可通过 Tab 聚焦手柄、用方向键完成排序。属性与监听器应当绑定到同一个可交互元素上,本方案通过 Context 将它们一并传递给手柄按钮,保证了语义完整性。

六、手柄(DragHandle):把"仅手柄可拖"落实为代码

原文档强调"拖拽手柄"这一能力,本示例用 Context + 手柄组件 + 激活节点 ref 三个机制配合实现:

1. Context 定义与 Provider

由于 useSortable 只能在 SortableListItem 内部调用,而手柄按钮渲染在卡片标题里、属于更深层的子孙节点,因此需要一个模块级 Context 传递拖拽触发所需的能力:

interface SortableListItemContextProps {
  setActivatorNodeRef?: (element: HTMLElement | null) => void;
  listeners?: SyntheticListenerMap;
  attributes?: DraggableAttributes;
}

const SortableListItemContext = createContext<SortableListItemContextProps>({});

在 SortableListItem 的 JSX 中,把这三者放入 Context.Provider:

<SortableListItemContext.Provider value={memoizedValue}>
  <List.Item {...rest} ref={setNodeRef} style={listStyle} />
</SortableListItemContext.Provider>

外层 Provider 包裹内层的 List.Item,而 List.Item 的 children 中包含卡片与手柄——手柄因此能够通过 useContext 拿到激活节点信息。示例使用 useMemo 缓存 value 对象、并声明了正确的依赖数组,避免每次渲染都创建新对象、触发所有消费方重渲染。

2. DragHandle 组件

手柄最终渲染为一个纯文本样式的图标按钮:

const DragHandle: React.FC = () => {
  const { setActivatorNodeRef, listeners, attributes } = useContext(SortableListItemContext);
  return (
    <Button
      type="text"
      size="small"
      icon={<HolderOutlined />}
      style={{ cursor: 'move' }}
      ref={setActivatorNodeRef}
      {...attributes}
      {...listeners}
    />
  );
};

它做了三件事:

  • 把 ref 指向 setActivatorNodeRef:明确告知 dnd-kit"只有这个按钮是拖拽起点";
  • 展开 attributes 与 listeners:键盘/指针的拖拽交互都由此按钮承接;
  • 设置 cursor: 'move':鼠标悬停时给出可拖拽的视觉反馈。

因为整条 List.Item 上没有绑定任何 listeners,所以拖拽只会在按住手柄时触发,卡片其余区域可正常承载点击、选中等业务交互。从源码的对比版 grid-drag-sorting.tsx可以看出:如果去掉手柄这一层,就需要把 attributes 和 listeners 直接展开在 List.Item 上,并额外使用 PointerSensor 与 activationConstraint: { distance: 1 } 来避免与点击的误冲突——手柄方案天然规避了这些问题。

3. 手柄在卡片标题中的占位

为避免标题文字跳动,示例将手柄放在 Card 的 title 内并与标题文本并列:

<Card title={<><DragHandle />{item.title}</>}>
  Card content
</Card>

这样网格中每张卡片标题栏的左侧都会显示一个 HolderOutlined 图标作为手柄,视觉直观、命中区域清晰。

七、纵向列表示例中的手柄进阶用法

网格与单列共用了几乎相同的 Context/手柄结构,区别只在于排序策略与轴向限制。在 drag-sorting-handler.tsx 中可以看到两处与本例的差异,可作为手柄方案的补充参考:

  1. verticalListSortingStrategy:SortableContext 额外声明 strategy,针对单列垂直列表优化排序(计算垂直位移),而网格布局不需要该策略,因为网格的换行排布由算法自动处理;
  2. restrictToVerticalAxis 修饰器:通过 DndContext 的 modifiers 属性把拖拽运动限制在垂直轴内,防止网格/纵向布局中出现横向漂移的错觉(该能力来自 @dnd-kit/modifiers)。

这些差异化能力说明:dnd-kit 的方案是"一套 useSortable 核心 + 按布局选择策略与修饰器",架构上具有良好的可扩展性。

八、关键实现要点总结

结合源码与示例,把本方案的要点归纳如下,供你在真实业务中直接套用:

  1. id 必须稳定唯一:useSortable({ id })、SortableContext 的 items、数据项三处使用的 id 必须一一对应,建议使用数据主键而非数组下标(拖拽重排会改变下标);
  2. ref 不能遗漏:setNodeRef 决定碰撞检测区域,漏绑将导致排序失灵;setActivatorNodeRef 决定拖拽起点,只在需要手柄时使用;
  3. 样式要合并而非覆盖:务必 { ...style, transform, transition, ... },否则会破坏 grid 栅格通过 style 传入的百分比宽度(源码见 components/list/index.tsx);
  4. onDragEnd 三段式防护:空值判断 → 位置未变短路 → 不可变数组更新(arrayMove);
  5. Context value 做缓存:通过 useMemo 稳定引用,减少整棵列表子树的不必要重渲染;
  6. 拖拽期间提升层级:isDragging 时使用 zIndex 让被拖卡片悬浮于其他卡片之上,避免被遮挡。

九、结语

通过 dnd-kit 与 ant-design List 的组合,网格卡片拖拽排序并不需要"魔改"组件库:List 负责栅格排版,dnd-kit 的 useSortable 负责排序状态机,二者仅通过 renderItem 返回的自定义 List.Item 桥接。手柄方案进一步把交互入口收窄到一个图标按钮,既满足了"网格 + 拖拽排序"的功能需求,也保住了卡片内部其他操作的可用性。整套代码可以直接从本仓库的 grid-drag-sorting-handler.tsx 复制迁移,并根据业务需要把 Card 替换为任意自定义卡片内容。

登录后查看全文
ant-design