ant-design List 网格拖拽排序实战:基于 dnd-kit 手柄(Handler)方案的完整实现解析
ant-design List 网格拖拽排序实战:基于 dnd-kit 手柄(Handler)方案的完整实现解析
导读
在 ant-design 的 List 组件中实现「卡片网格 + 拖拽排序」是一个高频但需要组合技巧的需求:官方组件本身不具备拖拽能力,因此社区通用的做法是集成第三方拖拽库 dnd-kit。本文以仓库内 grid-drag-sorting-handler 示例 为骨架,完整解析「自定义元素 + 拖拽手柄(drag handle)」方案的架构设计、逐步实现与底层原理——读者将掌握:如何用 useSortable 包装 List.Item、如何通过 Context 把"仅手柄可拖拽"的能力注入到卡片标题栏,以及 grid 栅格布局在源码中究竟是如何计算列宽并渲染的。
一、需求场景与方案总览
拖拽排序在数据卡片、看板、可配置仪表盘等界面中十分常见。原文档的诉求非常聚焦:
使用自定义元素和拖拽手柄,我们可以集成 dnd-kit 来实现网格布局的拖拽排序。
拆解这句话,可以提炼出三个关键点:
- 网格布局(grid layout):基于
List的grid属性,将条目渲染为多列卡片; - 自定义元素(custom components):拖拽能力不依赖组件库,而是由使用者自定义的
List.Item包装层接入; - 拖拽手柄(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 行的实现逻辑可以印证栅格渲染原理:
- 当
grid中存在响应式断点键时,调用useBreakpoint订阅视口尺寸; - 计算出当前命中的断点后,取对应断点的列数(否则回退到
grid.column); - 将列数换算为百分比宽度,
width与maxWidth均为100 / columnCount %; - 最终由 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 中可以看到两处与本例的差异,可作为手柄方案的补充参考:
verticalListSortingStrategy:SortableContext额外声明strategy,针对单列垂直列表优化排序(计算垂直位移),而网格布局不需要该策略,因为网格的换行排布由算法自动处理;restrictToVerticalAxis修饰器:通过DndContext的modifiers属性把拖拽运动限制在垂直轴内,防止网格/纵向布局中出现横向漂移的错觉(该能力来自@dnd-kit/modifiers)。
这些差异化能力说明:dnd-kit 的方案是"一套 useSortable 核心 + 按布局选择策略与修饰器",架构上具有良好的可扩展性。
八、关键实现要点总结
结合源码与示例,把本方案的要点归纳如下,供你在真实业务中直接套用:
- id 必须稳定唯一:
useSortable({ id })、SortableContext的items、数据项三处使用的 id 必须一一对应,建议使用数据主键而非数组下标(拖拽重排会改变下标); - ref 不能遗漏:
setNodeRef决定碰撞检测区域,漏绑将导致排序失灵;setActivatorNodeRef决定拖拽起点,只在需要手柄时使用; - 样式要合并而非覆盖:务必
{ ...style, transform, transition, ... },否则会破坏grid栅格通过 style 传入的百分比宽度(源码见 components/list/index.tsx); - onDragEnd 三段式防护:空值判断 → 位置未变短路 → 不可变数组更新(
arrayMove); - Context value 做缓存:通过
useMemo稳定引用,减少整棵列表子树的不必要重渲染; - 拖拽期间提升层级:
isDragging时使用zIndex让被拖卡片悬浮于其他卡片之上,避免被遮挡。
九、结语
通过 dnd-kit 与 ant-design List 的组合,网格卡片拖拽排序并不需要"魔改"组件库:List 负责栅格排版,dnd-kit 的 useSortable 负责排序状态机,二者仅通过 renderItem 返回的自定义 List.Item 桥接。手柄方案进一步把交互入口收窄到一个图标按钮,既满足了"网格 + 拖拽排序"的功能需求,也保住了卡片内部其他操作的可用性。整套代码可以直接从本仓库的 grid-drag-sorting-handler.tsx 复制迁移,并根据业务需要把 Card 替换为任意自定义卡片内容。