Ant Design Tabs 可拖拽标签实战:基于 dnd-kit 与 renderTabBar 的完整实现

原创2026-09-19 23:57:572,333 阅读
文章标签:前端UI组件设计系统

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 仓库中,可拖拽标签的官方示例由两个文件组成:

该示例的核心设计是:不修改 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。

五、进阶扩展建议

在理解示例的基础上,可以按需扩展:

  1. 与新增/关闭联动:把 renderTabBar 与 type="editable-card"、onEdit 组合,实现"可拖拽 + 可增删"的完整管理型标签页。注意此时必须配合第四节 CSS 关闭过渡;
  2. 拖拽限制:可引入 @dnd-kit/modifiers(仓库中同样声明了该依赖)限制拖拽轴(如 restrictToHorizontalAxis),防止纵向漂移;
  3. 添加删除动画:为 DraggableTabNode 增加进入/退出的过渡样式,但需保持 transition 语义与 dnd-kit 协调;
  4. 持久化顺序:onDragEnd 中把排序结果同步到服务端或 localStorage,实现用户自定义顺序记忆;
  5. 无障碍: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 玩法,举一反三实现更多自定义交互。

登录后查看全文
ant-design