dnd-kit-implementation

dnd-kit 实现指南

概述

此技能提供了使用 dnd-kit 库实现拖放功能的模式，可同时支持可排序容器和可放置目标。

核心概念

组合使用 useSortable 和 useDroppable 的关键在于基于拖动上下文的条件逻辑：

• 拖动项目时 → 容器仅作为放置目标
• 拖动容器时 → 容器作为可排序元素

实现方式是检测当前正在拖动的对象，并仅启用相应的功能。

实现模式

容器组件结构

const SortableDroppableContainer = ({ container }) => {
  // useSortable for container reordering
  const {
    attributes,
    listeners,
    setNodeRef: setSortableRef,
    transform,
    transition,
    isDragging,
  } = useSortable({ id: container.id });

  // useDroppable for receiving items
  const { setNodeRef: setDroppableRef, isOver } = useDroppable({
    id: container.id,
  });

  // Active element from context
  const { active } = useDndContext();

  // Determine behavior based on what's being dragged
  const isItem = active?.id?.toString().startsWith('item-');
  const isContainer = active?.id?.toString().startsWith('container-');

  // Apply conditional refs
  const setNodeRef = isItem ? setDroppableRef : setSortableRef;

  return (
    <div ref={setNodeRef} {...(isContainer ? attributes : {})} style={style}>
      <div {...(isContainer ? listeners : {})}>{/* Drag handle */}</div>
      {/* Container content */}
    </div>
  );
};

关键实现要点

1. 双钩子用法：在同一组件中同时使用 useSortable 和 useDroppable
2. 上下文检测：使用 useDndContext() 检查当前正在拖动的对象
3. 条件引用：根据拖动状态应用相应的 ref
4. ID 命名约定：使用 container-* 和 item-* 等前缀区分类型

ID 命名约定

// Containers
const containerId = `container-${id}`;

// Items
const itemId = `item-${id}`;

这一约定使条件逻辑清晰且易于维护。

状态管理关键点

更新容器项目时，始终创建新对象：

// ❌ Won't trigger re-render
containers.items.push(newItem);

// ✅ Correct - creates new reference
setContainers(prev => prev.map(c =>
  c.id === targetId
    ? { ...c, items: [...c.items, newItem] }
    : c
));

常见用例

• 看板：重新排列列，并在列之间移动卡片
• 文件管理：重新整理文件夹，并将文件移入文件夹
• 播放列表编辑器：重新排列播放列表，并向播放列表添加歌曲
• 任务管理器：重新排列任务列表，并在列表之间移动任务

参考资料

如需详细的实现示例和代码模式，请参阅：

• implementation-patterns.md - 包含 TypeScript 的完整组件示例
• state-management.md - 状态更新模式和常见陷阱