用途
该技能用于在项目中实现拖拽与放置功能,底层使用 @atlaskit/pragmatic-drag-and-drop 库。文档明确指出适用场景包括:可排序列表、可重新排序的项目、看板,以及任何拖拽交互。
主要能力与所需导入
文档要求从以下路径导入相应能力:
- combine(来自 @atlaskit/pragmatic-drag-and-drop/combine)
- draggable、dropTargetForElements、ElementDropTargetEventBasePayload(来自 element/adapter)
- pointerOutsideOfPreview(来自 element/pointer-outside-of-preview)
- setCustomNativeDragPreview(来自 element/set-custom-native-drag-preview)
- attachClosestEdge、Edge、extractClosestEdge(来自 hitbox/closest-edge)
- DropIndicator(来自 react-drop-indicator/box)
关键模式:用 ref 保存易变状态
文档强调:永远不要把易变的拖拽状态放进 useEffect 的依赖中,否则处理程序会在每次状态变化时重新注册。资料给出了反例(BAD:将 closestEdge 作为 useEffect 依赖,导致每次拖拽移动都重新运行)与正例(GOOD:使用 ref 保存 closestEdge,并用 useCallback 包裹 updateClosestEdge 以满足 lint 的 exhaustive-deps 要求,同时把 updateClosestEdge 加入 useEffect 依赖)。
使用方式
资料提供了基础的可拖拽项目模式代码,包含:
- 通过 ref 引用元素与拖拽手柄
- 用 combine 组合 draggable 与 dropTargetForElements
- getInitialData 返回项目数据(id、index、instanceId)
- onDragStart / onDrop 切换 isDragging 状态
- onGenerateDragPreview 中使用 setCustomNativeDragPreview 与 pointerOutsideOfPreview 生成自定义拖拽预览
- dropTargetForElements 的 canDrop 判断实例一致且索引不同
- getData 中通过 attachClosestEdge 附加最近边缘信息,allowedEdges 为 top、bottom
- onDrag 中根据 source 与 index 关系判断是否隐藏放置指示器(前一项目底部、后一项目顶部时隐藏)
- onDrop 中从 ref 读取 closestEdge,计算 targetIndex 并在 sourceIndex 较小时做减一调整,再调用 onDrop
此外,文档说明可用 Symbol 作为 instance ID 将拖拽操作限定在单个列表内,并给出重排处理函数:从 items 复制数组、splice 移出并插入到目标位置、按索引重新设置 position、先做乐观更新 setItems 再调用 saveOrder 持久化。
检查清单
资料末尾列出检查项:易变状态使用 ref、updateClosestEdge 用 useCallback 包裹以符合 lint、将 updateClosestEdge 加入 useEffect 依赖、为列表划分提供实例 ID、带边缘检测的放置指示器、自定义拖拽预览、乐观 UI 更新。
限制
资料未提供该技能的具体安装步骤、版本要求、收费或价格信息、平台支持范围与实际效果数据,这些内容暂未提供。