ant-design Tag 组件结合 dnd-kit 实现可拖拽标签排序
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 示例的代码结构可以拆成三个层次:
- 数据层:一个由
{ id, text }对象组成的items数组,是标签顺序的唯一数据源; - 拖拽编排层:
DndContext负责监听全局拖拽事件、管理传感器,SortableContext负责把普通子元素注册为可排序对象; - 展示层:
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 组件的示例提供了现成的参照:
- 垂直拖拽:把
horizontalListSortingStrategy换成verticalListSortingStrategy(Table 的 drag-sorting.tsx 即用于垂直排序),配合restrictToVerticalAxis修饰器限制只在纵轴移动; - 拖拽手柄:
useSortable的listeners不挂在整行上,而是挂在一个专门的手柄图标元素上,避免误触整行(见 Table 的 drag-sorting-handler.tsx); - 横向列拖拽:Table 的 drag-column-sorting.tsx 使用
restrictToHorizontalAxis限制横向移动,并用DragOverEvent处理跨区域悬停; - 键盘可访问性: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)上,即可快速获得一致的拖拽排序体验。