Реализация Drag-and-Drop интерфейса (Kanban-доска) на сайте

Реализация Drag-and-Drop интерфейса (Kanban-доска) на сайте

Drag-and-drop на первый взгляд кажется простой задачей — пока не начинаешь разбираться с touch-устройствами, автоскроллом при перетаскивании к краю, вложенными контейнерами и accessibility. HTML5 Drag-and-Drop API покрывает базовые сценарии, но для Kanban-доски с несколькими колонками и вложенными списками нужна библиотека.

Выбор библиотеки

@dnd-kit/core — современный стандарт для React. Работает с touch и keyboard, поддерживает accessibility из коробки, не зависит от DOM-порядка элементов. Размер ~10 КБ gzipped.

react-beautiful-dnd — популярна, но разработка заморожена. Использовать в новых проектах не стоит.

Sortable.js — ванильный вариант, работает с любым фреймворком, но требует больше ручной работы при интеграции с React state.

Установка dnd-kit

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

Структура данных

type CardId = string
type ColumnId = string

interface Card {
  id: CardId
  title: string
  description?: string
  assignee?: string
  priority: 'low' | 'medium' | 'high'
}

interface Column {
  id: ColumnId
  title: string
  cardIds: CardId[]
}

interface BoardState {
  cards: Record<CardId, Card>
  columns: Record<ColumnId, Column>
  columnOrder: ColumnId[]
}

Нормализованная структура (карточки отдельно от колонок) упрощает перемещение: не нужно искать элемент в массиве — только обновить cardIds в нужных колонках.

DndContext и сенсоры

import {
  DndContext,
  DragEndEvent,
  DragOverEvent,
  DragStartEvent,
  PointerSensor,
  KeyboardSensor,
  TouchSensor,
  useSensor,
  useSensors,
  closestCorners,
} from '@dnd-kit/core'
import { sortableKeyboardCoordinates } from '@dnd-kit/sortable'

function KanbanBoard() {
  const [board, setBoard] = useState<BoardState>(initialBoard)
  const [activeCardId, setActiveCardId] = useState<CardId | null>(null)

  const sensors = useSensors(
    useSensor(PointerSensor, {
      activationConstraint: {
        distance: 8, // пиксели до начала DnD — чтобы не мешать кликам
      },
    }),
    useSensor(TouchSensor, {
      activationConstraint: {
        delay: 250,       // задержка на touch — избегаем конфликта со scroll
        tolerance: 5,
      },
    }),
    useSensor(KeyboardSensor, {
      coordinateGetter: sortableKeyboardCoordinates,
    })
  )

  function handleDragStart(event: DragStartEvent) {
    setActiveCardId(event.active.id as CardId)
  }

  function handleDragOver(event: DragOverEvent) {
    const { active, over } = event
    if (!over) return

    const activeColId = findColumnByCardId(board, active.id as CardId)
    const overColId = isColumnId(over.id)
      ? (over.id as ColumnId)
      : findColumnByCardId(board, over.id as CardId)

    if (!activeColId || !overColId || activeColId === overColId) return

    // Перемещаем карточку между колонками во время drag (live preview)
    setBoard((prev) => moveCardBetweenColumns(prev, active.id as CardId, activeColId, overColId, over.id as CardId))
  }

  function handleDragEnd(event: DragEndEvent) {
    const { active, over } = event
    setActiveCardId(null)

    if (!over) return

    const activeColId = findColumnByCardId(board, active.id as CardId)
    const overColId = isColumnId(over.id)
      ? (over.id as ColumnId)
      : findColumnByCardId(board, over.id as CardId)

    if (!activeColId || !overColId) return

    if (activeColId === overColId) {
      // Сортировка внутри одной колонки
      setBoard((prev) => reorderCardInColumn(prev, activeColId, active.id as CardId, over.id as CardId))
    }
    // Между колонками уже обработано в handleDragOver
  }

  const activeCard = activeCardId ? board.cards[activeCardId] : null

  return (
    <DndContext
      sensors={sensors}
      collisionDetection={closestCorners}
      onDragStart={handleDragStart}
      onDragOver={handleDragOver}
      onDragEnd={handleDragEnd}
    >
      <div className="flex gap-4 overflow-x-auto p-4">
        {board.columnOrder.map((colId) => (
          <KanbanColumn
            key={colId}
            column={board.columns[colId]}
            cards={board.columns[colId].cardIds.map((id) => board.cards[id])}
          />
        ))}
      </div>
      <DragOverlay>
        {activeCard ? <KanbanCard card={activeCard} isDragging /> : null}
      </DragOverlay>
    </DndContext>
  )
}

DragOverlay рендерит «призрак» карточки поверх всего — без него карточка пропадает из колонки во время перетаскивания, что выглядит плохо.

SortableContext и колонка

import { SortableContext, verticalListSortingStrategy, useSortable } from '@dnd-kit/sortable'
import { useDroppable } from '@dnd-kit/core'
import { CSS } from '@dnd-kit/utilities'

function KanbanColumn({ column, cards }: { column: Column; cards: Card[] }) {
  // Колонка как drop-target для пустых зон
  const { setNodeRef, isOver } = useDroppable({ id: column.id })

  return (
    <div
      className={`w-72 rounded-lg bg-gray-100 p-3 flex-shrink-0 ${
        isOver ? 'ring-2 ring-blue-400' : ''
      }`}
    >
      <h3 className="font-semibold mb-3">{column.title}</h3>
      <SortableContext
        items={cards.map((c) => c.id)}
        strategy={verticalListSortingStrategy}
      >
        <div ref={setNodeRef} className="space-y-2 min-h-[48px]">
          {cards.map((card) => (
            <SortableCard key={card.id} card={card} />
          ))}
        </div>
      </SortableContext>
    </div>
  )
}

function SortableCard({ card }: { card: Card }) {
  const {
    attributes,
    listeners,
    setNodeRef,
    transform,
    transition,
    isDragging,
  } = useSortable({ id: card.id })

  const style = {
    transform: CSS.Transform.toString(transform),
    transition,
    opacity: isDragging ? 0.4 : 1, // исходная позиция становится полупрозрачной
  }

  return (
    <div
      ref={setNodeRef}
      style={style}
      {...attributes}
      {...listeners}
      className="bg-white rounded-md p-3 shadow-sm cursor-grab active:cursor-grabbing"
    >
      <KanbanCard card={card} />
    </div>
  )
}

Утилиты перемещения

function moveCardBetweenColumns(
  board: BoardState,
  cardId: CardId,
  fromColId: ColumnId,
  toColId: ColumnId,
  overCardId: CardId | ColumnId
): BoardState {
  const fromCol = board.columns[fromColId]
  const toCol = board.columns[toColId]
  const newFromIds = fromCol.cardIds.filter((id) => id !== cardId)

  const insertIndex = isColumnId(overCardId)
    ? toCol.cardIds.length
    : toCol.cardIds.indexOf(overCardId as CardId)

  const newToIds = [...toCol.cardIds]
  newToIds.splice(insertIndex, 0, cardId)

  return {
    ...board,
    columns: {
      ...board.columns,
      [fromColId]: { ...fromCol, cardIds: newFromIds },
      [toColId]: { ...toCol, cardIds: newToIds },
    },
  }
}

Персистентность состояния

Для сохранения порядка после перезагрузки — синхронизируем с бэкендом после каждого dragEnd:

const mutation = useMutation({
  mutationFn: (update: BoardUpdatePayload) =>
    api.patch('/boards/main', update),
  onError: (_, __, context) => {
    // Откат при ошибке
    setBoard(context!.previousBoard)
    toast.error('Не удалось сохранить изменения')
  },
})

function handleDragEnd(event: DragEndEvent) {
  // ... логика перемещения
  const previousBoard = board
  const newBoard = applyDragEnd(board, event)
  setBoard(newBoard) // оптимистичное обновление

  mutation.mutate(
    { cardId: event.active.id, columnId: targetColId, position: newPosition },
    { context: { previousBoard } }
  )
}

Сортировка колонок

Сами колонки тоже можно перетаскивать — для этого колонки оборачиваются в SortableContext на уровне доски:

<SortableContext
  items={board.columnOrder}
  strategy={horizontalListSortingStrategy}
>
  {board.columnOrder.map((colId) => (
    <SortableColumn key={colId} column={board.columns[colId]} ... />
  ))}
</SortableContext>

Логика определения, что перетаскивается (карточка или колонка), — через тип данных в active.data.current.

Что делаем

Проектируем структуру данных под конкретную задачу (может быть доска задач, воронка продаж, редактор контента). Настраиваем DnD с поддержкой touch и клавиатуры, реализуем live preview через DragOverlay, подключаем синхронизацию с API с оптимистичными обновлениями и откатом при ошибке.

Срок: базовая Kanban-доска — 3–4 дня. С сортировкой колонок, вложенными задачами и оффлайн-синхронизацией — 6–8 дней.