implementing-drag-drop

拖放与可排序界面

用途

此技能可帮助使用现代 React/TypeScript 库实现拖放交互和可排序界面。内容涵盖以无障碍为先的方法、触控支持和性能优化，助你打造直观的直接操作式 UI。

适用场景

在以下情况下调用此技能：

• 构建可在列之间拖动卡片的 Trello 风格看板
• 创建带拖动手柄、用于调整优先级顺序的可排序列表
• 实现带有视觉拖放反馈的文件上传区域
• 构建可重新排序的仪表板小组件或图库网格
• 创建基于节点界面的可视化构建器
• 实现任何需要通过直接操作来重新组织空间布局的 UI

核心模式

可排序列表

参考 references/dnd-patterns.md，了解：

• 带拖动手柄的垂直列表
• 用于重新排列标签页/轮播项的水平列表
• 支持二维拖动的网格布局
• 靠近边缘时自动滚动

看板

参考 references/kanban-implementation.md，了解：

• 带卡片的多列看板
• WIP 限制和泳道
• 悬停时预览卡片
• 列管理（添加/移除/折叠）

文件上传区域

参考 references/file-dropzone.md，了解：

• 视觉反馈状态
• 文件类型验证
• 多文件处理
• 进度指示器

无障碍

参考 references/accessibility-dnd.md，了解：

• 键盘导航模式
• 屏幕阅读器播报
• 替代 UI 方案
• ARIA 属性

库选择

首选：dnd-kit

适用于 React 的现代化、无障碍且高性能的拖放库。

参考 references/library-guide.md，了解：

• 库对比（dnd-kit 与其他方案）
• 安装和设置
• 核心概念和 API
• 从 react-beautiful-dnd 迁移

主要功能

• 内置无障碍支持
• 支持触控、鼠标和键盘输入
• 零依赖（核心包约 10KB）
• 高度可定制
• 原生支持 TypeScript

实现工作流

第 1 步：分析需求

确定所需的拖放模式：

• 简单的列表重排 → 可排序列表模式
• 多容器移动 → 看板模式
• 文件处理 → 投放区域模式
• 复杂交互 → 可视化构建器模式

第 2 步：设置库

安装所需软件包：

npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

第 3 步：实现核心功能

以示例作为起点：

• 基础列表参考 examples/sortable-list.tsx
• 多列看板参考 examples/kanban-board.tsx
• 文件上传参考 examples/file-dropzone.tsx
• 网格布局参考 examples/grid-reorder.tsx

第 4 步：添加无障碍支持

参考 references/accessibility-dnd.md：

• 实现键盘导航
• 添加屏幕阅读器播报
• 提供替代控件
• 使用辅助技术进行测试

运行 scripts/validate_accessibility.js 检查实现。

第 5 步：优化性能

对于包含 >100 个项目的列表：

• 参考 references/performance-optimization.md
• 实现虚拟滚动
• 使用 scripts/calculate_drop_position.js 高效计算

第 6 步：使用设计令牌设置样式

使用 design-tokens 技能应用主题：

• 参考设计令牌变量
• 实现拖动状态（悬停、拖动、放下）
• 添加视觉反馈和动画

移动设备与触控支持

参考 references/touch-support.md，了解：

• 长按以开始拖动
• 拖动期间阻止滚动
• 适合触控的点击区域（最小 44px）
• 手势冲突处理

状态管理

参考 references/state-management.md，了解：

• 在 React 中管理拖动状态
• 乐观更新
• 撤销/重做功能
• 持久化顺序变更

脚本

计算放置位置

运行 scripts/calculate_drop_position.js 以：

• 确定有效放置区域
• 计算插入索引
• 处理边界情况

生成配置

运行 scripts/generate_dnd_config.js 以：

• 创建 dnd-kit 配置
• 设置传感器和修饰符
• 配置动画

验证无障碍性

运行 scripts/validate_accessibility.js 以：

• 检查键盘导航
• 验证 ARIA 属性
• 测试屏幕阅读器兼容性

示例

每个示例都包含完整的 TypeScript 代码，并支持无障碍访问：

可排序列表

examples/sortable-list.tsx

• 带拖动手柄的垂直列表
• 键盘导航（按 Space/Enter 键抓取，按方向键移动）
• 屏幕阅读器播报

看板

examples/kanban-board.tsx

• 多列布局，包含可拖动的卡片
• 在列之间移动卡片
• 列管理功能
• WIP 限制

文件拖放区

examples/file-dropzone.tsx

• 拖动文件以上传
• 视觉反馈状态
• 文件类型验证
• 上传进度

网格重排

examples/grid-reorder.tsx

• 二维网格拖动
• 放下后自动布局
• 响应式断点

资源

TypeScript 类型

assets/drag-state-types.ts 提供：

• 拖动状态的类型定义
• 事件处理程序类型
• 配置接口

配置架构

assets/dnd-config-schema.json 定义：

• 有效的配置选项
• 传感器设置
• 动画参数

最佳实践

视觉反馈

• 显示拖动手柄（⋮⋮）以表明可拖动
• 更改光标（grab → grabbing）
• 显示放置区域占位符
• 将拖动项设为半透明
• 高亮显示有效的放置目标

性能

• 使用 CSS 变换，而不是位置属性
• 为动画应用 will-change: transform
• 对大型列表的拖动事件进行节流
• 按需实现虚拟滚动

无障碍优先

• 始终提供键盘操作方式
• 添加屏幕阅读器播报
• 使用 NVDA/JAWS/VoiceOver 进行测试
• 提供非拖动操作方式（按钮/表单）

错误处理

• 显示无效放置的反馈
• 实现撤销功能
• 成功放置后自动保存
• 妥善处理网络故障

常见问题

避免以下问题

• 忘记实现键盘导航
• 缺少触控支持
• 拖动时未阻止滚动
• 忽视无障碍性
• 大型列表性能不佳

解决方案

针对每个问题参考相应指南：

• 无障碍性 → references/accessibility-dnd.md
• 触控 → references/touch-support.md
• 性能 → references/performance-optimization.md
• 状态 → references/state-management.md

测试清单

部署前，请确认：

• 键盘导航功能完整
• 屏幕阅读器会播报所有操作
• 触控设备能够顺畅拖动
• 使用预期数据量时性能可接受
• 视觉反馈清晰且响应及时
• 撤销/重做功能正常
• 提供了无障碍替代界面
• 兼容所有目标浏览器

后续步骤

实现基本拖放功能后：

1. 添加高级功能（自动滚动、多选）
2. 为移动设备实现手势支持
3. 使用 Framer Motion 优化动画
4. 创建自定义拖动预览组件
5. 构建复杂交互（嵌套拖动）