Ant Design Tabs 可拖拽标签实战:基于 dnd-kit 与 renderTabBar 的完整实现
Ant Design Tabs 可拖拽标签实战:基于 dnd-kit 与 renderTabBar 的完整实现
本指南讲解如何基于开源仓库 ant-design 中的 Tabs 组件,利用 dnd-kit(@dnd-kit/core、@dnd-kit/sortable、@dnd-kit/utilities)实现可拖拽排序的标签页(Draggable Tabs)。通过 renderTabBar 自定义 TabBar、用 useSortable 包装每个标签节点、并结合 arrayMove 维护数据顺序,你可以完整复现官方示例 custom-tab-bar-node 的交互能力,并理解其中关键 CSS 的取舍原因。读完本文,你将掌握一套可复制、可扩展的拖拽标签实现方案。
一、方案概览:官方如何实现"标签可拖拽"
在 ant-design 仓库中,可拖拽标签的官方示例由两个文件组成:
- 说明文档:components/tabs/demo/custom-tab-bar-node.md —— 核心思路一句话:使用 dnd-kit 实现标签可拖拽;
- 完整实现:components/tabs/demo/custom-tab-bar-node.tsx —— 约 90 行的可运行示例代码。
该示例的核心设计是:不修改 Tabs 组件内部实现,而是利用 Tabs 暴露的 renderTabBar 回调,把默认的 TabBar 整体嵌入 dnd-kit 的拖拽上下文中,再对每个标签节点附加拖拽能力。这种"组合式"改造方式对任何 antd 版本都具备很强的移植性。
仓库根目录 package.json 中已经声明了 dnd-kit 家族依赖(作为 devDependencies 供示例与测试使用),版本如下:
| 依赖包 | 版本 |
|---|---|
@dnd-kit/core |
^6.1.0 |
@dnd-kit/sortable |
^8.0.0 |
@dnd-kit/modifiers |
^7.0.0 |
@dnd-kit/utilities |
^3.2.2 |
在你自己项目中使用时,需要先安装这些包(示例核心只用到了 core、sortable、utilities 三个):
npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
# 或
yarn add @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
二、完整示例代码
以下是 components/tabs/demo/custom-tab-bar-node.tsx 的完整实现,它是理解全部机制的基础:
import React, { useState } from 'react';
import type { DragEndEvent } from '@dnd-kit/core';
import { DndContext, PointerSensor, closestCenter, useSensor } from '@dnd-kit/core';
import {
arrayMove,
horizontalListSortingStrategy,
SortableContext,
useSortable,
} from '@dnd-kit/sortable';
import { CSS } from '@dnd-kit/utilities';
import { Tabs } from 'antd';
interface DraggableTabPaneProps extends React.HTMLAttributes<HTMLDivElement> {
'data-node-key': string;
}
const DraggableTabNode = ({ className, ...props }: DraggableTabPaneProps) => {
const { attributes, listeners, setNodeRef, transform, transition } = useSortable({
id: props['data-node-key'],
});
const style: React.CSSProperties = {
...props.style,
transform: CSS.Translate.toString(transform),
transition,
cursor: 'move',
};
return React.cloneElement(props.children as React.ReactElement, {
ref: setNodeRef,
style,
...attributes,
...listeners,
});
};
const App: React.FC = () => {
const [items, setItems] = useState([
{
key: '1',
label: 'Tab 1',
children: 'Content of Tab Pane 1',
},
{
key: '2',
label: 'Tab 2',
children: 'Content of Tab Pane 2',
},
{
key: '3',
label: 'Tab 3',
children: 'Content of Tab Pane 3',
},
]);
const sensor = useSensor(PointerSensor, { activationConstraint: { distance: 10 } });
const onDragEnd = ({ active, over }: DragEndEvent) => {
if (active.id !== over?.id) {
setItems((prev) => {
const activeIndex = prev.findIndex((i) => i.key === active.id);
const overIndex = prev.findIndex((i) => i.key === over?.id);
return arrayMove(prev, activeIndex, overIndex);
});
}
};
return (
<Tabs
items={items}
renderTabBar={(tabBarProps, DefaultTabBar) => (
<DndContext sensors={[sensor]} onDragEnd={onDragEnd} collisionDetection={closestCenter}>
<SortableContext items={items.map((i) => i.key)} strategy={horizontalListSortingStrategy}>
<DefaultTabBar {...tabBarProps}>
{(node) => (
<DraggableTabNode {...node.props} key={node.key}>
{node}
</DraggableTabNode>
)}
</DefaultTabBar>
</SortableContext>
</DndContext>
)}
/>
);
};
export default App;
三、逐层拆解实现原理
3.1 入口:renderTabBar 替换 TabBar
renderTabBar 是 Tabs 组件暴露的自定义 TabBar 入口。在 components/tabs/index.tsx 中,TabsProps 继承自 rc-tabs 的 RcTabsProps,renderTabBar 的签名定义在 components/tabs/index.en-US.md 中为:
renderTabBar: (props: DefaultTabBarProps, DefaultTabBar: React.ComponentClass) => React.ReactElement
它接收两个参数:
props:默认 TabBar 的全部属性(当前激活项、onChange 回调、前缀类名等),需要原样透传给DefaultTabBar;DefaultTabBar:antd 默认 TabBar 的组件类,可以理解为"渲染标签栏的标准实现"。
示例中的用法是:用 DndContext 和 SortableContext 包裹 <DefaultTabBar {...tabBarProps}>,并在 DefaultTabBar 的子渲染函数中逐个包装标签节点。这样拖拽层完全包在 Tabs 外面,Tabs 自身的激活切换、滚动、键盘操作等行为不受影响。
仓库测试 components/tabs/tests/index.test.tsx 中也验证了 renderTabBar 的基础用法(直接替换为自定义 div),说明该 API 是公开、稳定的能力边界。
3.2 节点包装:DraggableTabNode 与 useSortable
DraggableTabNode 是拖拽能力的核心载体:
const { attributes, listeners, setNodeRef, transform, transition } = useSortable({
id: props['data-node-key'],
});
useSortable是@dnd-kit/sortable提供的 Hook,入参id用于在拖拽上下文中唯一标识该节点——这里直接复用 Tabs 项的key(通过data-node-key属性传入),保证与SortableContext的items一一对应;setNodeRef:绑定到 DOM 节点,dnd-kit 据此计算拖拽位置;listeners:拖拽事件监听器(mousedown/touchstart 等),绑定后即可"抓住"标签拖动;attributes:无障碍相关的role、aria等属性,保持键盘可访问性;transform/transition:拖拽过程中的位移与过渡,是视觉反馈的来源。
关键技巧在于这一行:
return React.cloneElement(props.children as React.ReactElement, {
ref: setNodeRef,
style,
...attributes,
...listeners,
});
DraggableTabNode 并不自己渲染 DOM,而是通过 React.cloneElement 把 setNodeRef、style、attributes、listeners 注入到子节点(即 antd 渲染出的标签 DOM 节点)上,从而实现"零额外 DOM 层级"的拖拽包装。样式中 cursor: 'move' 让鼠标悬停时显示可拖拽手势。
3.3 拖拽上下文:DndContext + PointerSensor + closestCenter
const sensor = useSensor(PointerSensor, { activationConstraint: { distance: 10 } });
PointerSensor:统一处理鼠标与触控笔/触摸事件;activationConstraint: { distance: 10 }:只有当指针移动超过 10px 才激活拖拽。这是官方特意设置的"防误触"参数——如果用户只是想单击切换标签,轻微的抖动不会误触发拖拽;collisionDetection={closestCenter}:拖拽过程中实时计算"距离哪个标签中心最近",从而高亮目标位置。
3.4 排序策略:SortableContext + horizontalListSortingStrategy
<SortableContext items={items.map((i) => i.key)} strategy={horizontalListSortingStrategy}>
items传入所有标签的key数组,dnd-kit 据此知道"哪些节点可以相互排序";strategy={horizontalListSortingStrategy}是横向列表专用策略。Tabs 标签栏是水平排布的(tabPosition="top"时),横向策略能正确计算水平方向的排序位移与占位,避免使用默认垂直策略导致布局错乱。
3.5 拖拽结束:onDragEnd 与 arrayMove
const onDragEnd = ({ active, over }: DragEndEvent) => {
if (active.id !== over?.id) {
setItems((prev) => {
const activeIndex = prev.findIndex((i) => i.key === active.id);
const overIndex = prev.findIndex((i) => i.key === over?.id);
return arrayMove(prev, activeIndex, overIndex);
});
}
};
active.id是被拖拽标签的key,over.id是释放时悬停目标的key;- 若二者不同,则从
items中找出两个索引,调用arrayMove(dnd-kit 提供的不变式数组移动函数)生成新数组; - 由于
items通过useState管理,新顺序会驱动 Tabs 重新渲染,实现标签顺序持久化。
四、关键 CSS:为什么 type="editable-card" 要关闭 transition
原文档还附带了一段必读 CSS:
/* set transition to none when type="editable-card" */
.ant-tabs-editable > .ant-tabs-nav .ant-tabs-tab {
transition: none;
}
背景是:当 type="editable-card" 时,antd 为标签自身设置了过渡动画(transition),用于切换、新增、关闭标签时的平滑效果。但拖拽过程中,dnd-kit 需要通过 transform 实时移动标签,且 useSortable 返回的 transition 也会控制拖拽时的过渡。两者叠加会导致:
- 拖拽位移与自带过渡动画互相干扰,标签"拖不动"或出现抖动、卡顿;
- 动画叠加造成视觉错位,排序结果与实际位置不一致。
因此官方做法是:在 editable-card 类型下,用 .ant-tabs-editable > .ant-tabs-nav .ant-tabs-tab 选择器将标签的 transition 置为 none,把动画控制权完全交给 dnd-kit。注意选择器使用了 > 直接子选择器与 .ant-tabs-nav 限定,避免误伤其他区域。
对照 components/tabs/index.tsx 的 className 拼装逻辑可以看到:当 type === 'editable-card' 时,根节点会同时加上 ant-tabs-card 和 ant-tabs-editable-card 两个类名,因此该 CSS 选择器能精确命中。若你使用的不是 editable-card 类型(如默认的 line 或 card),则无需这段 CSS。
五、进阶扩展建议
在理解示例的基础上,可以按需扩展:
- 与新增/关闭联动:把
renderTabBar与type="editable-card"、onEdit组合,实现"可拖拽 + 可增删"的完整管理型标签页。注意此时必须配合第四节 CSS 关闭过渡; - 拖拽限制:可引入
@dnd-kit/modifiers(仓库中同样声明了该依赖)限制拖拽轴(如restrictToHorizontalAxis),防止纵向漂移; - 添加删除动画:为
DraggableTabNode增加进入/退出的过渡样式,但需保持transition语义与 dnd-kit 协调; - 持久化顺序:
onDragEnd中把排序结果同步到服务端或localStorage,实现用户自定义顺序记忆; - 无障碍:
attributes已内置role="button"与aria-roledescription等属性,建议保留;同时可接入KeyboardSensor支持纯键盘拖拽排序。
六、总结
本文完整还原了 ant-design 仓库中 custom-tab-bar-node 这一官方示例的全部要点:通过 renderTabBar 将默认 TabBar 嵌入 dnd-kit 的 DndContext/SortableContext,用 useSortable + React.cloneElement 零侵入地为每个标签附加拖拽能力,用 arrayMove 维护 items 顺序,并明确了 editable-card 下关闭 CSS 过渡的原因。这套方案完全基于公开 API 与外部拖拽库组合而成,不依赖 Tabs 内部实现细节,可直接迁移到你的业务代码中,也可以参考 custom-tab-bar.tsx(基于 react-sticky-box 的吸顶 TabBar)等其他 renderTabBar 玩法,举一反三实现更多自定义交互。