implementing-drag-drop（实施拖放）

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:

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