React拖放功能实现指南：dnd-kit库教程与无障碍可排序界面开发

implementing-drag-drop by ancoleman/ai-design-components

110 周安装量

321 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/ancoleman/ai-design-components --skill implementing-drag-drop

UI组件库 React 前端优化

🇨🇳中文介绍

拖放与可排序界面

目的

此技能帮助使用现代 React/TypeScript 库实现拖放交互和可排序界面。它涵盖了无障碍优先方法、触摸支持以及性能优化，用于创建直观的直接操作 UI。

何时使用

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

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

核心模式

可排序列表

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

带有拖拽手柄的垂直列表
用于选项卡/轮播重新排序的水平列表
支持 2D 拖动的网格布局
边缘附近的自动滚动

看板

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

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

文件上传区域

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 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：使用设计令牌进行样式设计

使用设计令牌技能应用主题：

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

移动端与触摸支持

参考 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

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

examples/kanban-board.tsx

带有可拖动卡片的多列
卡片在列间移动
列管理功能
在制品限制

examples/file-dropzone.tsx

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

examples/grid-reorder.tsx

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

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

部署前，请验证：

键盘导航完全可用
屏幕阅读器播报所有操作
触摸设备可以平滑拖动
在预期数据量下性能可接受
视觉反馈清晰且响应迅速
撤销/重做功能有效
为无障碍性提供了替代 UI
在所有目标浏览器中均能工作

实现基本拖放功能后：

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

🇺🇸English

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.

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

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

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)

File Upload Zones

Reference references/file-dropzone.md for:

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

Accessibility

Reference references/accessibility-dnd.md for:

Keyboard navigation patterns
Screen reader announcements
Alternative UI approaches
ARIA attributes

Library Selection

Primary: 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

Key Features

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

Implementation Workflow

Step 1: Analyze Requirements

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

Install required packages:

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

Step 3: Implement Core Functionality

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

Step 4: Add Accessibility

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.

Step 5: Optimize Performance

For lists with >100 items:

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

Step 6: Style with Design Tokens

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

State Management

Reference references/state-management.md for:

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

Scripts

Calculate Drop Position

Run scripts/calculate_drop_position.js to:

Determine valid drop zones
Calculate insertion indices
Handle edge cases

Generate Configuration

Run scripts/generate_dnd_config.js to:

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

Validate Accessibility

Run scripts/validate_accessibility.js to:

Check keyboard navigation
Verify ARIA attributes
Test screen reader compatibility

Examples

Each example includes complete TypeScript code with accessibility:

Sortable List

examples/sortable-list.tsx

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

Kanban Board

examples/kanban-board.tsx

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

File Dropzone

examples/file-dropzone.tsx

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

Grid Reorder

examples/grid-reorder.tsx

2D grid dragging
Auto-layout on drop
Responsive breakpoints

Assets

TypeScript Types

assets/drag-state-types.ts provides:

Type definitions for drag state
Event handler types
Configuration interfaces

Configuration Schema

assets/dnd-config-schema.json defines:

Valid configuration options
Sensor settings
Animation parameters

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

Performance

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

Accessibility First

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

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

Testing Checklist

Before deployment, verify:

Keyboard navigation works completely
Screen readers announce all actions
Touch devices can drag smoothly
Performance acceptable with expected data volume
Visual feedback clear and responsive
Undo/redo functionality works
Alternative UI provided for accessibility
Works across all target browsers

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)

Weekly Installs

Repository

ancoleman/ai-de…mponents

GitHub Stars

308

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode83

gemini-cli75

github-copilot71

codex71

cursor67

claude-code62

React Native 棕地迁移指南：逐步集成到原生应用（Expo/裸RN）

509 周安装

React拖放功能实现指南：dnd-kit库教程与无障碍可排序界面开发

🇨🇳中文介绍

拖放与可排序界面

目的

何时使用

核心模式

可排序列表

看板

文件上传区域

相关 Skills

无障碍性

库选择

首选：dnd-kit

主要特性

实现工作流程

步骤 1：分析需求

步骤 2：设置库

步骤 3：实现核心功能

步骤 4：添加无障碍性

步骤 5：优化性能

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

移动端与触摸支持

状态管理

脚本

计算放置位置

生成配置

验证无障碍性

示例

可排序列表

看板

文件拖放区域

网格重新排序

资源

TypeScript 类型

配置模式

最佳实践

视觉反馈

性能

无障碍性优先

错误处理

常见陷阱

避免这些问题

解决方案

测试清单

后续步骤

🇺🇸English

Drag-and-Drop & Sortable Interfaces

Purpose

When to Use

Core Patterns

Sortable Lists

Kanban Boards

File Upload Zones

Accessibility

Library Selection

Primary: dnd-kit

Key Features

Implementation Workflow

Step 1: Analyze Requirements

Step 2: Set Up Library

Step 3: Implement Core Functionality

Step 4: Add Accessibility

Step 5: Optimize Performance

Step 6: Style with Design Tokens

Mobile & Touch Support

State Management

Scripts

Calculate Drop Position

Generate Configuration

Validate Accessibility

Examples

Sortable List

Kanban Board

File Dropzone

Grid Reorder

Assets

TypeScript Types

Configuration Schema

Best Practices

Visual Feedback