ant-design Tag 组件结合 dnd-kit 实现可拖拽标签排序

原创2026-09-19 10:56:221,642 阅读
文章标签:前端UI组件设计系统

ant-design Tag 组件结合 dnd-kit 实现可拖拽标签排序

在 ant-design 中,Tag 组件本质上是渲染为 <span> 的轻量标记元素,其本身并不提供拖拽能力。但在 components/tag/demo/draggable.tsx 这一官方示例中,ant-design 展示了如何借助成熟的拖拽库 dnd-kit 与 Tag 组件组合,实现一套完整的"可拖拽标签"交互:标签可以自由换行排列、用鼠标拖拽重新排序,并在松开后持久化新的顺序。读完本文,你将掌握 DndContext / SortableContext / useSortable 的核心用法、transform/transition 的拖拽视觉处理细节,以及如何把任意 ant-design 组件(Tag、Table 等)接入 dnd-kit 的排序体系。

一、示例定位:Tag 的 Draggable Tag 官方 Demo

在仓库中,Tag 组件位于 components/tag,其官方文档 index.en-US.md 的 Examples 列表里包含一个名为 Draggable Tag 的示例(<code src="./demo/draggable.tsx">Draggable Tag</code>)。该示例的中英文说明只有一句话:

使用 dnd kit 实现的可拖拽标签。(Draggable tags using dnd kit.)

虽然描述简短,但配套的 draggable.tsx 是一份结构完整、可直接复制运行的参考实现,涵盖了拖拽排序场景下的全部关键环节:传感器(sensor)配置、碰撞检测、排序上下文、数组重排逻辑与拖拽样式处理。

从 package.json 可以看到,ant-design 的 devDependencies 中已内置 dnd-kit 全家桶:

  • @dnd-kit/core ^6.1.0
  • @dnd-kit/modifiers ^7.0.0
  • @dnd-kit/sortable ^8.0.0
  • @dnd-kit/utilities ^3.2.2

这意味着在 ant-design 仓库内,dnd-kit 是官方示例所采用的拖拽基础设施,除了 Tag,Table 组件的 drag-sorting、drag-column-sorting、drag-sorting-handler 等示例也基于它实现(见 components/table/demo)。

二、整体架构:三个层次如何协作

可拖拽 Tag 示例的代码结构可以拆成三个层次:

  1. 数据层:一个由 { id, text } 对象组成的 items 数组,是标签顺序的唯一数据源;
  2. 拖拽编排层:DndContext 负责监听全局拖拽事件、管理传感器,SortableContext 负责把普通子元素注册为可排序对象;
  3. 展示层:DraggableTag 包装了 ant-design 的 <Tag>,通过 useSortable 获取拖拽所需的监听器与样式变换信息。

三者通过 id 建立映射:SortableContext 的 items 数组中的 id,必须与每个 useSortable({ id }) 传入的 id 一一对应,dnd-kit 才能正确计算排序索引。

三、源码逐段拆解

下面以 draggable.tsx 为骨架,逐段讲解实现要点。

1. 数据模型与拖拽项组件

interface Item {
  id: number;
  text: string;
}

interface DraggableTagProps {
  tag: Item;
}

每个标签由唯一 id 与显示文本 text 组成。DraggableTag 是"可拖拽的单个标签",其核心代码如下:

const DraggableTag: React.FC<DraggableTagProps> = (props) => {
  const { tag } = props;
  const { listeners, transform, transition, isDragging, setNodeRef } = useSortable({ id: tag.id });

  const style = transform
    ? {
        ...commonStyle,
        transform: `translate3d(${transform.x}px, ${transform.y}px, 0)`,
        transition: isDragging ? 'unset' : transition,
      }
    : commonStyle;

  return (
    <Tag style={style} ref={setNodeRef} {...listeners}>
      {tag.text}
    </Tag>
  );
};

这里有几个值得注意的细节:

  • useSortable({ id }) 的返回值:setNodeRef 需要绑定到被拖拽元素的 DOM 节点上(即 <Tag> 的 ref),dnd-kit 依赖它测量元素尺寸与位置;listeners 是激活拖拽的事件监听器(pointer/touch/keyboard 等),通过 {...listeners} 展开到 <Tag> 上;transform 是一个 { x, y } 坐标对象,描述当前元素相对初始位置的位移。
  • 为什么 transform 要手写 translate3d:示例没有直接使用 @dnd-kit/utilities 中的 CSS.Transform.toString() 工具,而是手写为 translate3d(${transform.x}px, ${transform.y}px, 0)。translate3d 会触发 GPU 合成,拖拽过程更加流畅。
  • 拖拽时的 transition: 'unset':commonStyle 里注释说明 transition: 'unset' 是为了防止元素在拖拽后抖动;而拖拽中(isDragging 为 true)同样强制取消过渡动画,以提升拖拽跟手度。这正是 dnd-kit 官方推荐的"拖拽中禁用 transition、结束时恢复"的实践。
  • cursor: 'move':给所有标签设置移动光标,提示用户该元素可拖动。

2. 拖拽编排:DndContext + SortableContext + 传感器

const sensors = useSensors(useSensor(PointerSensor));

const handleDragEnd = (event: DragEndEvent) => {
  const { active, over } = event;
  if (!over) return;
  if (active.id !== over.id) {
    setItems((data) => {
      const oldIndex = data.findIndex((item) => item.id === active.id);
      const newIndex = data.findIndex((item) => item.id === over.id);
      return arrayMove(data, oldIndex, newIndex);
    });
  }
};

return (
  <DndContext sensors={sensors} onDragEnd={handleDragEnd} collisionDetection={closestCenter}>
    <SortableContext items={items} strategy={horizontalListSortingStrategy}>
      <Flex gap="4px 0" wrap>
        {items.map<React.ReactNode>((item) => (
          <DraggableTag tag={item} key={item.id} />
        ))}
      </Flex>
    </SortableContext>
  </DndContext>
);

各部分职责如下:

组成部分 作用
useSensor(PointerSensor) 指针传感器,鼠标/触摸笔按下即可激活拖拽;不配置传感器时拖拽无法被触发
collisionDetection={closestCenter} 碰撞检测策略:当被拖元素中心点离某个元素最近时,判定为"悬停于该元素之上"
onDragEnd 拖拽结束回调,事件对象包含 active(被拖元素)与 over(当前悬停目标)
SortableContext 声明哪些 id 是可排序集合,并指定排序策略
horizontalListSortingStrategy 水平列表排序策略,让元素沿横向移动并让位,适合一行排列的标签
arrayMove 来自 @dnd-kit/sortable 的工具函数,按新旧索引重排数组

handleDragEnd 的逻辑非常典型:先通过 findIndex 找出 active.id 与 over.id 在数组中的位置,再用 arrayMove 生成新数组交给 setItems。由于 React 状态更新是异步的,这里使用了函数式更新 setItems((data) => ...),保证基于最新数据计算索引。只有 active.id !== over.id 时才重排,避免无意义更新。

3. 布局容器:为什么选择 Flex

外层使用 ant-design 的 Flex 组件并设置 gap="4px 0" 与 wrap:

<Flex gap="4px 0" wrap>
  • gap="4px 0":行间距 4px、列间距 0,标签密集排列时保持呼吸感;
  • wrap:允许换行,标签数量超出容器宽度时自动折行。

从 components/flex/index.tsx 的源码可以看到,Flex 会把 gap 转换为 style.gap(非预设尺寸时直接写入内联样式),wrap 则生成 ant-flex-wrap-wrap 类名,最终渲染为 <div>。快照测试 components/tag/__tests__/__snapshots__/demo.test.ts.snap 也印证了这一点:示例渲染结果为 <div class="ant-flex ant-flex-wrap-wrap" style="gap:4px 0">,其内部是三个带 cursor:move;transition:unset 内联样式的 ant-tag span。

四、与 Tag 组件的衔接:ref 与 style 的透传

<Tag ref={setNodeRef} style={style} {...listeners}> 之所以能无缝衔接,得益于 Tag 组件的实现。查看 components/tag/index.tsx 的源码:

  • Tag 通过 React.forwardRef<HTMLSpanElement, TagProps> 对外转发 ref,因此 setNodeRef 可以直接拿到内部 <span> 的真实 DOM 节点;
  • Tag 接受 style 并合并进 tagStyle:{ backgroundColor: ..., ...tagContext?.style, ...style },外层传入的拖拽 transform 样式因此能最终作用到 DOM 上;
  • Tag 的其余 props 通过 {...domProps} 透传给 <span>,listeners(如 onPointerDown、onKeyDown)可以正常生效。

也就是说,dnd-kit 并不关心被拖元素是不是"组件",它只要求一个可绑定 ref 的 DOM 节点,而 ant-design 的 Tag 天然满足这一点。同理,Table 示例也是把 useSortable 的 ref 与监听器绑定到自定义单元格元素上(见 components/table/demo/drag-sorting.tsx)。

五、扩展思路:从水平拖拽到更多场景

draggable.tsx 演示的是最简单的"整行水平换行拖拽",基于同一套骨架可以扩展出多种变体,仓库内 Table 组件的示例提供了现成的参照:

  1. 垂直拖拽:把 horizontalListSortingStrategy 换成 verticalListSortingStrategy(Table 的 drag-sorting.tsx 即用于垂直排序),配合 restrictToVerticalAxis 修饰器限制只在纵轴移动;
  2. 拖拽手柄:useSortable 的 listeners 不挂在整行上,而是挂在一个专门的手柄图标元素上,避免误触整行(见 Table 的 drag-sorting-handler.tsx);
  3. 横向列拖拽:Table 的 drag-column-sorting.tsx 使用 restrictToHorizontalAxis 限制横向移动,并用 DragOverEvent 处理跨区域悬停;
  4. 键盘可访问性:dnd-kit 内置键盘传感器,快照中出现的 "press the space bar / use the arrow keys" 提示文案(见 demo-extend.test.ts.snap)说明默认的 KeyboardSensor 同样会生效,保证无障碍体验。

六、测试佐证:示例被快照测试覆盖

ant-design 的所有 demo 都会进入快照测试。在 components/tag/__tests__/__snapshots__/demo.test.ts.snap 中可以找到 renders components/tag/demo/draggable.tsx correctly 的渲染结果:三个 ant-tag span 依序输出,每个都带 cursor:move;transition:unset 内联样式。这从测试层面确认了示例的静态渲染结构,也意味着你照抄这份实现时,得到的 DOM 结构与官方保持一致。

小结

ant-design 的可拖拽标签示例虽然说明文字极简,但代码本身是一份高质量的拖拽排序参考实现:useSortable 负责单个元素的 ref、监听器与位移信息,DndContext + SortableContext 负责全局编排与碰撞检测,arrayMove 负责数据重排,Flex 负责换行布局,而 Tag 组件的 ref/style 透传能力保证了 dnd-kit 可以像操作普通 DOM 一样操作它。把这份模式迁移到其他 ant-design 组件(如 Table、Card)上,即可快速获得一致的拖拽排序体验。

登录后查看全文
ant-design