implementing-drag-drop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Drag-and-Drop & Sortable Interfaces

拖拽与可排序界面

Purpose

用途

This skill helps implement drag-and-drop interactions and sortable interfaces using modern React/TypeScript libraries. It covers accessibility-first approaches, touch support, and performance optimization for creating intuitive direct manipulation UIs.

本技能可帮助你使用现代React/TypeScript库实现拖拽交互与可排序界面。内容涵盖无障碍优先方案、触控支持以及性能优化，助力打造直观的直接操作型UI。

When to Use

适用场景

Invoke this skill when:

Building Trello-style kanban boards with draggable cards between columns
Creating sortable lists with drag handles for priority ordering
Implementing file upload zones with visual drag-and-drop feedback
Building reorderable grids for dashboard widgets or galleries
Creating visual builders with node-based interfaces
Implementing any UI requiring spatial reorganization through direct manipulation

在以下场景中调用本技能：

构建Trello风格的看板，支持卡片在列间拖拽
创建带拖拽手柄的可排序列表，用于优先级排序
实现带视觉拖拽反馈的文件上传区域
构建用于仪表板组件或画廊的可重排网格
创建基于节点的可视化构建器界面
实现任何需要通过直接操作进行空间重组的UI

Core Patterns

核心模式

Sortable Lists

可排序列表

Reference

references/dnd-patterns.md

for:

Vertical lists with drag handles
Horizontal lists for tab/carousel reordering
Grid layouts with 2D dragging
Auto-scrolling near edges

参考

references/dnd-patterns.md

获取：

带拖拽手柄的垂直列表
用于标签页/轮播重排序的水平列表
支持2D拖拽的网格布局
边缘自动滚动

Kanban Boards

看板

Reference

references/kanban-implementation.md

for:

Multi-column boards with cards
WIP limits and swimlanes
Card preview on hover
Column management (add/remove/collapse)

参考

references/kanban-implementation.md

获取：

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

File Upload Zones

文件上传区域

Reference

references/file-dropzone.md

for:

Visual feedback states
File type validation
Multi-file handling
Progress indicators

参考

references/file-dropzone.md

获取：

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

Accessibility

无障碍设计

Reference

references/accessibility-dnd.md

for:

Keyboard navigation patterns
Screen reader announcements
Alternative UI approaches
ARIA attributes

参考

references/accessibility-dnd.md

获取：

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

Library Selection

库选择

Primary: dnd-kit

首选：dnd-kit

Modern, accessible, and performant drag-and-drop for React.

Reference

references/library-guide.md

for:

Library comparison (dnd-kit vs alternatives)
Installation and setup
Core concepts and API
Migration from react-beautiful-dnd

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

参考

references/library-guide.md

获取：

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

Key Features

核心特性

Built-in accessibility support
Touch, mouse, and keyboard input
Zero dependencies (~10KB core)
Highly customizable
TypeScript native

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

Implementation Workflow

实现流程

Step 1: Analyze Requirements

步骤1：分析需求

Determine the drag-and-drop pattern needed:

Simple list reordering → Sortable list pattern
Multi-container movement → Kanban pattern
File handling → Dropzone pattern
Complex interactions → Visual builder pattern

确定所需的拖拽模式：

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

Step 2: Set Up Library

步骤2：设置库

Install required packages:

bash

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

安装所需包：

bash

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

Step 3: Implement Core Functionality

步骤3：实现核心功能

Use examples as starting points:

```
examples/sortable-list.tsx
```
for basic lists
```
examples/kanban-board.tsx
```
for multi-column boards
```
examples/file-dropzone.tsx
```
for file uploads
```
examples/grid-reorder.tsx
```
for grid layouts

以示例为起点：

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

Step 4: Add Accessibility

步骤4：添加无障碍支持

Reference

references/accessibility-dnd.md

to:

Implement keyboard navigation
Add screen reader announcements
Provide alternative controls
Test with assistive technologies

Run

scripts/validate_accessibility.js

to check implementation.

参考

references/accessibility-dnd.md

完成：

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

运行

scripts/validate_accessibility.js

检查实现效果。

Step 5: Optimize Performance

步骤5：优化性能

For lists with >100 items:

Reference
```
references/performance-optimization.md
```
Implement virtual scrolling
Use
```
scripts/calculate_drop_position.js
```
for efficient calculations

针对超过100条数据的列表：

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

Step 6: Style with Design Tokens

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

Apply theming using the design-tokens skill:

Reference design token variables
Implement drag states (hovering, dragging, dropping)
Add visual feedback and animations

借助设计令牌技能应用主题：

参考设计令牌变量
实现拖拽状态（悬停、拖拽中、放置）
添加视觉反馈与动画

Mobile & Touch Support

移动端与触控支持

Reference

references/touch-support.md

for:

Long press to initiate drag
Preventing scroll during drag
Touch-friendly hit areas (44px minimum)
Gesture conflict resolution

参考

references/touch-support.md

获取：

长按触发拖拽
拖拽期间禁止滚动
触控友好的点击区域（最小44px）
手势冲突解决

State Management

状态管理

Reference

references/state-management.md

for:

Managing drag state in React
Optimistic updates
Undo/redo functionality
Persisting order changes

参考

references/state-management.md

获取：

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

Scripts

脚本

Calculate Drop Position

计算放置位置

Run

scripts/calculate_drop_position.js

to:

Determine valid drop zones
Calculate insertion indices
Handle edge cases

运行

scripts/calculate_drop_position.js

可：

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

Generate Configuration

生成配置

Run

scripts/generate_dnd_config.js

to:

Create dnd-kit configuration
Set up sensors and modifiers
Configure animations

运行

scripts/generate_dnd_config.js

可：

创建dnd-kit配置
设置传感器与修饰器
配置动画

Validate Accessibility

验证无障碍性

Run

scripts/validate_accessibility.js

to:

Check keyboard navigation
Verify ARIA attributes
Test screen reader compatibility

运行

scripts/validate_accessibility.js

可：

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

Examples

示例

Each example includes complete TypeScript code with accessibility:

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

Sortable List

可排序列表

examples/sortable-list.tsx

Vertical list with drag handles
Keyboard navigation (Space/Enter to grab, arrows to move)
Screen reader announcements

examples/sortable-list.tsx

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

Kanban Board

看板

examples/kanban-board.tsx

Multiple columns with draggable cards
Card movement between columns
Column management features
WIP limits

examples/kanban-board.tsx

多列布局，支持卡片拖拽
卡片在列间移动
列管理功能
在制品（WIP）限制

File Dropzone

文件上传区域

examples/file-dropzone.tsx

Drag files to upload
Visual feedback states
File type validation
Upload progress

examples/file-dropzone.tsx

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

Grid Reorder

网格重排

examples/grid-reorder.tsx

2D grid dragging
Auto-layout on drop
Responsive breakpoints

examples/grid-reorder.tsx

2D网格拖拽
放置时自动布局
响应式断点

Assets

资源

TypeScript Types

TypeScript类型定义

assets/drag-state-types.ts

provides:

Type definitions for drag state
Event handler types
Configuration interfaces

assets/drag-state-types.ts

提供：

拖拽状态的类型定义
事件处理函数类型
配置接口

Configuration Schema

配置Schema

assets/dnd-config-schema.json

defines:

Valid configuration options
Sensor settings
Animation parameters

assets/dnd-config-schema.json

定义：

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

Best Practices

最佳实践

Visual Feedback

视觉反馈

Show drag handles (⋮⋮) to indicate draggability
Change cursor (grab → grabbing)
Display drop zone placeholders
Make dragged items semi-transparent
Highlight valid drop targets

显示拖拽手柄（⋮⋮）以标识可拖拽性
更改光标样式（grab → grabbing）
显示放置区域占位符
拖拽中的元素设为半透明
高亮有效放置目标

Performance

性能

Use CSS transforms, not position properties
Apply
```
will-change: transform
```
for animations
Throttle drag events for large lists
Implement virtual scrolling when needed

使用CSS transform而非position属性
为动画添加
```
will-change: transform
```
对大型列表的拖拽事件进行节流
必要时实现虚拟滚动

Accessibility First

无障碍优先

Always provide keyboard alternatives
Include screen reader announcements
Test with NVDA/JAWS/VoiceOver
Provide non-drag alternatives (buttons/forms)

始终提供键盘替代方案
包含屏幕阅读器播报
使用NVDA/JAWS/VoiceOver测试
提供非拖拽式替代操作（按钮/表单）

Error Handling

错误处理

Show invalid drop feedback
Implement undo functionality
Auto-save after successful drops
Handle network failures gracefully

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

Common Pitfalls

常见陷阱

Avoid These Issues

需避免的问题

Forgetting keyboard navigation
Missing touch support
Not preventing scroll during drag
Ignoring accessibility
Poor performance with large lists

遗漏键盘导航
缺失触控支持
未在拖拽期间禁止滚动
忽略无障碍设计
大型列表性能不佳

Solutions

解决方案

Reference the appropriate guide for each issue:

Accessibility →
```
references/accessibility-dnd.md
```
Touch →
```
references/touch-support.md
```
Performance →
```
references/performance-optimization.md
```
State →
```
references/state-management.md
```

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

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

Testing Checklist

测试清单

Next Steps

后续步骤

After implementing basic drag-and-drop:

Add advanced features (auto-scroll, multi-select)
Implement gesture support for mobile
Add animation polish with Framer Motion
Create custom drag preview components
Build complex interactions (nested dragging)

实现基础拖拽功能后：

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