拖拽系统设计-深度剖析

开发通用拖拽组件,支持列表排序、看板拖拽等多种场景
- 基于 Pointer Events API 实现跨设备拖拽,兼容鼠标、触摸、触控笔
- 支持拖拽排序、跨列表拖拽、拖拽复制等 8+ 种交互模式
- 实现拖拽预览、吸附对齐、撤销重做等增强功能,用户体验提升 40%

设计并实现企业级拖拽系统,支持复杂业务场景
- 自研拖拽引擎,通过碰撞检测、约束验证、状态管理等机制,支持 10+ 种复杂拖拽场景
- 实现类 Trello 看板系统,支持卡片拖拽、列拖拽、泳道拖拽,日活用户 5000+
- 开发可视化布局编辑器,支持组件拖拽、嵌套容器、参考线对齐,配置效率提升 5 倍
- 优化拖拽性能,通过节流、虚拟化、增量更新等手段,大数据量拖拽帧率稳定 60fps

主导拖拽交互系统架构设计,建立统一的拖拽解决方案
- 抽象拖拽核心模型,支持声明式 API,新增拖拽场景开发时间从 3 天降至 4 小时
- 设计插件化架构,功能按需加载,基础库体积仅 8KB,完整功能 25KB
- 建立拖拽性能监控体系,自动识别性能瓶颈,优化建议准确率 90%
- 制定拖拽交互规范和可访问性标准,通过 WCAG 2.1 AA 级认证

<DraggableList v-model=\"items\" item-key=\"id\">
  <template #item=\"{ item }\">
    <div>{{ item.name }}</div>
  </template>
</DraggableList>

{
  columns: [
    {
      id: 'col1',
      name: '待办',
      cards: [
        { id: 'card1', title: '任务1' },
        { id: 'card2', title: '任务2' }
      ]
    }
  ]
}

element.style.transform = `translate(${x}px, ${y}px)`

let rafId = null
function handleMove(e) {
  if (rafId) return

  rafId = requestAnimationFrame(() => {
    updatePosition(e.clientX, e.clientY)
    rafId = null
  })
}

{
  \"columns\": [
    {
      \"id\": \"col1\",
      \"order\": 0,
      \"cards\": [
        { \"id\": \"card1\", \"order\": 0 },
        { \"id\": \"card2\", \"order\": 1 }
      ]
    }
  ]
}

{
  \"components\": [
    {
      \"id\": \"comp1\",
      \"type\": \"button\",
      \"x\": 100,
      \"y\": 200,
      \"width\": 80,
      \"height\": 40,
      \"parentId\": null
    }
  ]
}

{
  isDragging: false,      // 是否正在拖拽
  dragData: null,         // 拖拽的数据
  sourceContainer: null,  // 源容器
  targetContainer: null,  // 目标容器
  sourceIndex: null,      // 源索引
  targetIndex: null,      // 目标索引
}

const containerId = registerContainer({
  id: 'list-1',
  type: 'list',
  onDrop: handleDrop,
  canAccept: (data) => data.type === 'card'
})

// 拖拽管理器
const dragManager = {
  state: reactive({
    isDragging: false,
    dragData: null,
    sourceContainer: null,
    targetContainer: null,
  }),

  containers: new Map(),

  registerContainer(config) {
    const id = generateId()
    this.containers.set(id, config)
    return id
  },

  startDrag(containerId, index, data) {
    const container = this.containers.get(containerId)

    this.state.isDragging = true
    this.state.dragData = data
    this.state.sourceContainer = containerId
    this.state.sourceIndex = index

    container.onDragStart?.(data, index)
  },

  updateTarget(containerId, index) {
    if (this.state.targetContainer !== containerId) {
      // 离开旧容器
      if (this.state.targetContainer) {
        const oldContainer = this.containers.get(this.state.targetContainer)
        oldContainer.onDragLeave?.()
      }

      // 进入新容器
      const newContainer = this.containers.get(containerId)
      if (newContainer.canAccept(this.state.dragData)) {
        this.state.targetContainer = containerId
        newContainer.onDragEnter?.(this.state.dragData)
      }
    }

    this.state.targetIndex = index
  },

  endDrag() {
    const { sourceContainer, targetContainer, sourceIndex, targetIndex, dragData } = this.state

    if (targetContainer && sourceContainer !== targetContainer) {
      // 跨容器拖拽
      const source = this.containers.get(sourceContainer)
      const target = this.containers.get(targetContainer)

      source.onRemove(sourceIndex)
      target.onAdd(targetIndex, dragData)
    } else if (targetContainer && sourceIndex !== targetIndex) {
      // 同容器排序
      const container = this.containers.get(sourceContainer)
      container.onReorder(sourceIndex, targetIndex)
    }

    // 清空状态
    this.state.isDragging = false
    this.state.dragData = null
    this.state.sourceContainer = null
    this.state.targetContainer = null
  }
}

function createDragPreview(element) {
  const preview = document.createElement('div')
  preview.className = 'drag-preview'

  // 只提取关键信息
  const title = element.querySelector('.card-title')
  const icon = element.querySelector('.card-icon')

  if (icon) preview.appendChild(icon.cloneNode(true))
  if (title) preview.appendChild(title.cloneNode(true))

  return preview
}

async function createCanvasPreview(element) {
  // 使用 html2canvas 把元素转成图片
  const canvas = await html2canvas(element, {
    width: element.offsetWidth,
    height: element.offsetHeight,
    scale: 0.5, // 缩小一半,提高性能
  })

  // Canvas 作为预览
  canvas.className = 'drag-preview'
  return canvas
}

function createBatchPreview(items) {
  const preview = document.createElement('div')
  preview.className = 'drag-preview-batch'

  // 显示第一个元素的预览
  const firstItem = createDragPreview(items[0])
  preview.appendChild(firstItem)

  // 显示数量徽章
  if (items.length > 1) {
    const badge = document.createElement('div')
    badge.className = 'preview-badge'
    badge.textContent = items.length
    preview.appendChild(badge)
  }

  return preview
}

function createLazyPreview(element) {
  // 先渲染占位符
  const preview = document.createElement('div')
  preview.className = 'drag-preview-placeholder'

  // 延迟渲染完整内容
  requestIdleCallback(() => {
    const fullPreview = createDragPreview(element)
    preview.replaceWith(fullPreview)
  })

  return preview
}

.drag-preview {
  will-change: transform;
  transform: translate3d(0, 0, 0);
  opacity: 0.8;
  pointer-events: none;
}

const boundaries = []

components.forEach(comp => {
  if (comp.id === draggingId) return

  boundaries.push(
    { type: 'left', value: comp.x, component: comp },
    { type: 'right', value: comp.x + comp.width, component: comp },
    { type: 'center-x', value: comp.x + comp.width / 2, component: comp },
    { type: 'top', value: comp.y, component: comp },
    { type: 'bottom', value: comp.y + comp.height, component: comp },
    { type: 'center-y', value: comp.y + comp.height / 2, component: comp }
  )
})

const draggingBounds = {
  left: draggingX,
  right: draggingX + draggingWidth,
  centerX: draggingX + draggingWidth / 2,
  top: draggingY,
  bottom: draggingY + draggingHeight,
  centerY: draggingY + draggingHeight / 2
}

const SNAP_THRESHOLD = 5 // 5px 以内算接近

function findClosestBoundary(value, boundaries, type) {
  let closest = null
  let minDistance = Infinity

  boundaries.forEach(boundary => {
    if (boundary.type !== type) return

    const distance = Math.abs(boundary.value - value)

    if (distance < SNAP_THRESHOLD && distance < minDistance) {
      minDistance = distance
      closest = boundary
    }
  })

  return closest
}

const alignments = {
  left: findClosestBoundary(draggingBounds.left, boundaries, 'left'),
  right: findClosestBoundary(draggingBounds.right, boundaries, 'right'),
  centerX: findClosestBoundary(draggingBounds.centerX, boundaries, 'center-x'),
  top: findClosestBoundary(draggingBounds.top, boundaries, 'top'),
  bottom: findClosestBoundary(draggingBounds.bottom, boundaries, 'bottom'),
  centerY: findClosestBoundary(draggingBounds.centerY, boundaries, 'center-y'),
}

const guidelines = []

if (alignments.left) {
  guidelines.push({
    type: 'vertical',
    position: alignments.left.value,
    start: Math.min(draggingBounds.top, alignments.left.component.y),
    end: Math.max(draggingBounds.bottom, alignments.left.component.y + alignments.left.component.height)
  })
}

// 其他方向同理...

<div
  v-for="line in guidelines"
  :key="line.id"
  class="guideline"
  :class="line.type"
  :style="{
    [line.type === 'vertical' ? 'left' : 'top']: line.position + 'px',
    [line.type === 'vertical' ? 'top' : 'left']: line.start + 'px',
    [line.type === 'vertical' ? 'height' : 'width']: (line.end - line.start) + 'px'
  }"
></div>

let snapX = draggingX
let snapY = draggingY

if (alignments.left) {
  snapX = alignments.left.value
} else if (alignments.right) {
  snapX = alignments.right.value - draggingWidth
} else if (alignments.centerX) {
  snapX = alignments.centerX.value - draggingWidth / 2
}

if (alignments.top) {
  snapY = alignments.top.value
} else if (alignments.bottom) {
  snapY = alignments.bottom.value - draggingHeight
} else if (alignments.centerY) {
  snapY = alignments.centerY.value - draggingHeight / 2
}

// 应用吸附位置
draggingElement.style.transform = `translate(${snapX}px, ${snapY}px)`

// composables/useDraggable.js
import { ref, onMounted, onUnmounted } from 'vue'

export function useDraggable(options = {}) {
  const {
    onDragStart,
    onDragMove,
    onDragEnd,
    disabled = false,
    handle = null, // 拖拽手柄选择器
  } = options

  const elementRef = ref(null)
  const isDragging = ref(false)
  const dragData = ref(null)

  let startX = 0
  let startY = 0
  let currentX = 0
  let currentY = 0

  function handlePointerDown(e) {
    if (disabled) return

    // 如果指定了手柄,检查点击的是否是手柄
    if (handle && !e.target.closest(handle)) {
      return
    }

    e.preventDefault()

    // 记录起始位置
    startX = e.clientX
    startY = e.clientY
    currentX = 0
    currentY = 0

    isDragging.value = true

    // 设置指针捕获
    elementRef.value.setPointerCapture(e.pointerId)

    // 添加事件监听
    document.addEventListener('pointermove', handlePointerMove)
    document.addEventListener('pointerup', handlePointerUp)

    // 触发回调
    dragData.value = onDragStart?.(e)
  }

  function handlePointerMove(e) {
    if (!isDragging.value) return

    currentX = e.clientX - startX
    currentY = e.clientY - startY

    onDragMove?.({
      x: currentX,
      y: currentY,
      clientX: e.clientX,
      clientY: e.clientY,
      event: e,
    })
  }

  function handlePointerUp(e) {
    if (!isDragging.value) return

    isDragging.value = false

    // 移除事件监听
    document.removeEventListener('pointermove', handlePointerMove)
    document.removeEventListener('pointerup', handlePointerUp)

    // 触发回调
    onDragEnd?.({
      x: currentX,
      y: currentY,
      event: e,
      data: dragData.value,
    })

    dragData.value = null
  }

  onMounted(() => {
    if (elementRef.value) {
      elementRef.value.addEventListener('pointerdown', handlePointerDown)
    }
  })

  onUnmounted(() => {
    if (elementRef.value) {
      elementRef.value.removeEventListener('pointerdown', handlePointerDown)
    }
    document.removeEventListener('pointermove', handlePointerMove)
    document.removeEventListener('pointerup', handlePointerUp)
  })

  return {
    elementRef,
    isDragging,
    dragData,
  }
}

<!-- components/DraggableList/DraggableList.vue -->
<template>
  <div ref="containerRef" class="draggable-list">
    <div
      v-for="(item, index) in localItems"
      :key="getItemKey(item)"
      :ref="el => setItemRef(el, index)"
      class="draggable-item"
      :class="{
        'is-dragging': draggingIndex === index,
        'is-placeholder': placeholderIndex === index
      }"
      :style="getItemStyle(index)"
      @pointerdown="handlePointerDown($event, index)"
    >
      <slot :item="item" :index="index"></slot>
    </div>

    <!-- 拖拽预览 -->
    <Teleport to="body">
      <div
        v-if="isDragging"
        class="drag-preview"
        :style="{
          transform: `translate(${previewX}px, ${previewY}px)`,
          width: previewWidth + 'px'
        }"
      >
        <slot name="preview" :item="draggingItem">
          <slot :item="draggingItem" :index="draggingIndex"></slot>
        </slot>
      </div>
    </Teleport>
  </div>
</template>

<script setup>
import { ref, computed, watch } from 'vue'

const props = defineProps({
  modelValue: {
    type: Array,
    required: true,
  },
  itemKey: {
    type: [String, Function],
    default: 'id',
  },
  disabled: {
    type: Boolean,
    default: false,
  },
})

const emit = defineEmits(['update:modelValue', 'change'])

const containerRef = ref(null)
const localItems = ref([...props.modelValue])

watch(() => props.modelValue, (newVal) => {
  localItems.value = [...newVal]
}, { deep: true })

// 拖拽状态
const isDragging = ref(false)
const draggingIndex = ref(null)
const draggingItem = ref(null)
const placeholderIndex = ref(null)

// 预览位置
const previewX = ref(0)
const previewY = ref(0)
const previewWidth = ref(0)

// 元素引用
const itemRefs = new Map()

function setItemRef(el, index) {
  if (el) {
    itemRefs.set(index, el)
  }
}

// 获取项的 key
function getItemKey(item) {
  if (typeof props.itemKey === 'function') {
    return props.itemKey(item)
  }
  return item[props.itemKey]
}

// 获取项的样式
function getItemStyle(index) {
  if (draggingIndex.value === index) {
    return {
      opacity: 0.3,
      pointerEvents: 'none',
    }
  }
  return {}
}

// 开始拖拽
let startX = 0
let startY = 0
let startPageY = 0

function handlePointerDown(e, index) {
  if (props.disabled) return

  const element = itemRefs.get(index)
  if (!element) return

  // 记录起始位置
  const rect = element.getBoundingClientRect()
  startX = e.clientX - rect.left
  startY = e.clientY - rect.top
  startPageY = e.clientY

  draggingIndex.value = index
  draggingItem.value = localItems.value[index]
  placeholderIndex.value = index

  previewWidth.value = rect.width
  previewX.value = rect.left
  previewY.value = rect.top

  isDragging.value = true

  // 设置指针捕获
  element.setPointerCapture(e.pointerId)

  document.addEventListener('pointermove', handlePointerMove)
  document.addEventListener('pointerup', handlePointerUp)
}

// 拖拽中
function handlePointerMove(e) {
  if (!isDragging.value) return

  // 更新预览位置
  previewX.value = e.clientX - startX
  previewY.value = e.clientY - startY

  // 计算应该插入的位置
  const newIndex = findInsertIndex(e.clientY)
  if (newIndex !== placeholderIndex.value) {
    placeholderIndex.value = newIndex
  }
}

// 查找插入位置
function findInsertIndex(clientY) {
  const containerRect = containerRef.value.getBoundingClientRect()
  const relativeY = clientY - containerRect.top

  let insertIndex = 0

  for (let i = 0; i < localItems.value.length; i++) {
    if (i === draggingIndex.value) continue

    const element = itemRefs.get(i)
    if (!element) continue

    const rect = element.getBoundingClientRect()
    const elementY = rect.top - containerRect.top
    const elementMiddle = elementY + rect.height / 2

    if (relativeY < elementMiddle) {
      break
    }

    insertIndex = i + 1
  }

  return insertIndex
}

// 结束拖拽
function handlePointerUp(e) {
  if (!isDragging.value) return

  document.removeEventListener('pointermove', handlePointerMove)
  document.removeEventListener('pointerup', handlePointerUp)

  // 更新数组顺序
  if (placeholderIndex.value !== draggingIndex.value) {
    const newItems = [...localItems.value]
    const [removed] = newItems.splice(draggingIndex.value, 1)
    newItems.splice(placeholderIndex.value, 0, removed)

    localItems.value = newItems
    emit('update:modelValue', newItems)
    emit('change', {
      from: draggingIndex.value,
      to: placeholderIndex.value,
      item: removed,
    })
  }

  // 重置状态
  isDragging.value = false
  draggingIndex.value = null
  draggingItem.value = null
  placeholderIndex.value = null
}
</script>

<style scoped>
.draggable-list {
  position: relative;
}

.draggable-item {
  cursor: move;
  transition: opacity 0.2s;
  user-select: none;
}

.draggable-item.is-dragging {
  opacity: 0.3;
  pointer-events: none;
}

.drag-preview {
  position: fixed;
  top: 0;
  left: 0;
  z-index: 9999;
  opacity: 0.8;
  pointer-events: none;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}
</style>

<!-- components/Kanban/KanbanBoard.vue -->
<template>
  <div class="kanban-board">
    <div class="kanban-columns">
      <div
        v-for="column in columns"
        :key="column.id"
        class="kanban-column"
      >
        <div class="column-header">
          <h3>{{ column.name }}</h3>
          <span class="card-count">{{ column.cards.length }}</span>
        </div>

        <div
          :ref="el => setColumnRef(el, column.id)"
          class="column-body"
          :class="{ 'is-over': overColumnId === column.id }"
          @dragover="handleDragOver($event, column.id)"
          @dragleave="handleDragLeave"
          @drop="handleDrop($event, column.id)"
        >
          <div
            v-for="(card, index) in column.cards"
            :key="card.id"
            class="kanban-card"
            draggable="true"
            @dragstart="handleDragStart($event, column.id, index, card)"
            @dragend="handleDragEnd"
          >
            <slot name="card" :card="card">
              <div class="card-title">{{ card.title }}</div>
            </slot>
          </div>

          <!-- 插入指示器 -->
          <div
            v-if="overColumnId === column.id && insertIndex !== null"
            class="insert-indicator"
            :style="{ top: insertIndicatorTop + 'px' }"
          ></div>

          <!-- 空状态 -->
          <div v-if="column.cards.length === 0" class="column-empty">
            拖拽卡片到这里
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref, reactive } from 'vue'

const props = defineProps({
  columns: {
    type: Array,
    required: true,
  },
})

const emit = defineEmits(['card-move'])

// 列元素引用
const columnRefs = new Map()

function setColumnRef(el, columnId) {
  if (el) {
    columnRefs.set(columnId, el)
  }
}

// 拖拽状态
const dragState = reactive({
  sourceColumnId: null,
  sourceIndex: null,
  dragData: null,
})

const overColumnId = ref(null)
const insertIndex = ref(null)
const insertIndicatorTop = ref(0)

// 开始拖拽
function handleDragStart(e, columnId, index, card) {
  dragState.sourceColumnId = columnId
  dragState.sourceIndex = index
  dragState.dragData = card

  // 设置拖拽数据
  e.dataTransfer.effectAllowed = 'move'
  e.dataTransfer.setData('text/plain', card.id)

  // 自定义拖拽图像(可选)
  const dragImage = e.target.cloneNode(true)
  dragImage.style.opacity = '0.8'
  document.body.appendChild(dragImage)
  e.dataTransfer.setDragImage(dragImage, 0, 0)
  setTimeout(() => document.body.removeChild(dragImage), 0)
}

// 拖拽经过
function handleDragOver(e, columnId) {
  e.preventDefault()
  e.dataTransfer.dropEffect = 'move'

  overColumnId.value = columnId

  // 计算插入位置
  const columnEl = columnRefs.get(columnId)
  if (!columnEl) return

  const cards = Array.from(columnEl.querySelectorAll('.kanban-card'))
  const afterElement = getDragAfterElement(columnEl, e.clientY, cards)

  if (afterElement == null) {
    insertIndex.value = cards.length
    insertIndicatorTop.value = columnEl.scrollHeight
  } else {
    const rect = afterElement.getBoundingClientRect()
    const containerRect = columnEl.getBoundingClientRect()
    insertIndex.value = cards.indexOf(afterElement)
    insertIndicatorTop.value = rect.top - containerRect.top
  }
}

// 找到拖拽后面的元素
function getDragAfterElement(container, y, cards) {
  return cards.reduce((closest, child) => {
    const box = child.getBoundingClientRect()
    const offset = y - box.top - box.height / 2

    if (offset < 0 && offset > closest.offset) {
      return { offset: offset, element: child }
    } else {
      return closest
    }
  }, { offset: Number.NEGATIVE_INFINITY }).element
}

// 离开拖拽区域
function handleDragLeave(e) {
  // 检查是否真的离开了列(而不是进入子元素)
  if (e.currentTarget.contains(e.relatedTarget)) {
    return
  }

  if (overColumnId.value) {
    overColumnId.value = null
    insertIndex.value = null
  }
}

// 放置
function handleDrop(e, targetColumnId) {
  e.preventDefault()

  const { sourceColumnId, sourceIndex, dragData } = dragState

  if (!sourceColumnId || !dragData) return

  // 触发移动事件
  emit('card-move', {
    card: dragData,
    fromColumn: sourceColumnId,
    fromIndex: sourceIndex,
    toColumn: targetColumnId,
    toIndex: insertIndex.value,
  })

  // 重置状态
  overColumnId.value = null
  insertIndex.value = null
}

// 结束拖拽
function handleDragEnd() {
  dragState.sourceColumnId = null
  dragState.sourceIndex = null
  dragState.dragData = null
  overColumnId.value = null
  insertIndex.value = null
}
</script>

<style scoped>
.kanban-board {
  height: 100%;
  overflow-x: auto;
}

.kanban-columns {
  display: flex;
  gap: 16px;
  padding: 16px;
  height: 100%;
}

.kanban-column {
  flex: 0 0 300px;
  display: flex;
  flex-direction: column;
  background: #f5f5f5;
  border-radius: 4px;
}

.column-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 12px 16px;
  border-bottom: 1px solid #e0e0e0;
}

.column-header h3 {
  margin: 0;
  font-size: 16px;
  font-weight: 500;
}

.card-count {
  color: #999;
  font-size: 14px;
}

.column-body {
  flex: 1;
  padding: 12px;
  overflow-y: auto;
  position: relative;
  min-height: 100px;
}

.column-body.is-over {
  background: #e8f4fd;
}

.kanban-card {
  background: white;
  border-radius: 4px;
  padding: 12px;
  margin-bottom: 8px;
  cursor: move;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  transition: box-shadow 0.2s;
}

.kanban-card:hover {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
}

.card-title {
  font-size: 14px;
  line-height: 1.5;
}

.insert-indicator {
  position: absolute;
  left: 0;
  right: 0;
  height: 2px;
  background: #1890ff;
  pointer-events: none;
  transition: top 0.2s;
}

.column-empty {
  text-align: center;
  padding: 40px 20px;
  color: #999;
  font-size: 14px;
}
</style>

<!-- views/KanbanExample.vue -->
<template>
  <div class="kanban-example">
    <h2>看板示例</h2>

    <KanbanBoard
      :columns="columns"
      @card-move="handleCardMove"
    >
      <template #card="{ card }">
        <div class="custom-card">
          <div class="card-title">{{ card.title }}</div>
          <div class="card-desc">{{ card.description }}</div>
          <div class="card-footer">
            <span class="card-assignee">{{ card.assignee }}</span>
            <span class="card-date">{{ card.dueDate }}</span>
          </div>
        </div>
      </template>
    </KanbanBoard>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { message } from 'ant-design-vue'
import KanbanBoard from '@/components/Kanban/KanbanBoard.vue'

const columns = ref([
  {
    id: 'todo',
    name: '待办',
    cards: [
      {
        id: '1',
        title: '设计首页原型',
        description: '完成首页的交互设计',
        assignee: '张三',
        dueDate: '2024-01-15',
      },
      {
        id: '2',
        title: '开发用户登录',
        description: '实现用户登录功能',
        assignee: '李四',
        dueDate: '2024-01-16',
      },
    ],
  },
  {
    id: 'doing',
    name: '进行中',
    cards: [
      {
        id: '3',
        title: '优化列表性能',
        description: '使用虚拟滚动优化',
        assignee: '王五',
        dueDate: '2024-01-17',
      },
    ],
  },
  {
    id: 'done',
    name: '已完成',
    cards: [
      {
        id: '4',
        title: '搭建项目框架',
        description: '完成项目初始化',
        assignee: '赵六',
        dueDate: '2024-01-10',
      },
    ],
  },
])

function handleCardMove(event) {
  const { card, fromColumn, fromIndex, toColumn, toIndex } = event

  // 从源列删除
  const sourceColumn = columns.value.find(col => col.id === fromColumn)
  if (sourceColumn) {
    sourceColumn.cards.splice(fromIndex, 1)
  }

  // 添加到目标列
  const targetColumn = columns.value.find(col => col.id === toColumn)
  if (targetColumn) {
    targetColumn.cards.splice(toIndex, 0, card)
  }

  message.success(`卡片 "${card.title}" 移动到 ${targetColumn.name}`)

  // 这里可以调用接口保存顺序
  // await updateCardPosition({ cardId: card.id, columnId: toColumn, order: toIndex })
}
</script>

<style scoped>
.kanban-example {
  height: 100vh;
  display: flex;
  flex-direction: column;
}

.custom-card {
  font-size: 14px;
}

.card-title {
  font-weight: 500;
  margin-bottom: 8px;
}

.card-desc {
  color: #666;
  margin-bottom: 12px;
}

.card-footer {
  display: flex;
  justify-content: space-between;
  font-size: 12px;
  color: #999;
}
</style>

class MoveCardCommand {
  constructor(data) {
    this.fromColumn = data.fromColumn
    this.toColumn = data.toColumn
    this.fromIndex = data.fromIndex
    this.toIndex = data.toIndex
    this.card = data.card
  }

  execute() {
    // 执行移动
    moveCard(this.card, this.toColumn, this.toIndex)
  }

  undo() {
    // 撤销移动
    moveCard(this.card, this.fromColumn, this.fromIndex)
  }
}
```"

### Q: 拖拽时如何实现自动滚动?

"当拖拽到容器边缘时,自动滚动容器,方便拖拽到不可见的位置。

实现思路:

1. **检测边缘** - 拖拽时判断鼠标是否接近容器边缘(比如距离边缘 50px 以内)

2. **计算滚动速度** - 距离边缘越近,滚动越快。用线性函数计算:
```javascript
const speed = (threshold - distance) / threshold * maxSpeed

function autoScroll() {
  if (shouldScroll) {
    container.scrollTop += scrollSpeed
    requestAnimationFrame(autoScroll)
  }
}

import { mount } from '@vue/test-utils'
import DraggableList from './DraggableList.vue'

test('drag and drop reorders items', async () => {
  const wrapper = mount(DraggableList, {
    props: {
      modelValue: [{ id: 1 }, { id: 2 }, { id: 3 }]
    }
  })

  // 模拟拖拽
  const items = wrapper.findAll('.draggable-item')
  await items[0].trigger('pointerdown', { clientX: 0, clientY: 0 })
  await items[0].trigger('pointermove', { clientX: 0, clientY: 100 })
  await items[0].trigger('pointerup')

  // 断言顺序变化
  expect(wrapper.emitted('update:modelValue')[0][0]).toEqual([
    { id: 2 }, { id: 1 }, { id: 3 }
  ])
})

test('kanban drag and drop', async ({ page }) => {
  await page.goto('/kanban')

  const card = page.locator('.kanban-card').first()
  const column = page.locator('.kanban-column').nth(1)

  await card.dragTo(column)

  await expect(column.locator('.kanban-card')).toHaveCount(2)
})
```"

---

## 项目经验总结

### 踩过的坑

1. **iOS Safari 的触摸延迟** - 移动端拖拽有 300ms 延迟,加了 `touch-action: none` 解决

2. **拖拽预览在 Firefox 不显示** - Firefox 的 setDragImage 有 bug,改用绝对定位的 div 模拟预览

3. **跨 iframe 拖拽不工作** - 拖拽数据无法跨 iframe 传递,改用 postMessage 通信

4. **内存泄漏** - 拖拽结束后没有清理事件监听和元素引用,导致内存持续增长

### 性能数据

- 1000 个元素的列表拖拽:帧率 60fps
- 碰撞检测耗时:< 2ms(使用空间索引)
- 拖拽预览渲染:< 16ms(一帧时间内)
- 看板拖拽响应时间:< 50ms

### 可以吹的点

- 自研拖拽引擎,不依赖第三方库,灵活可控
- 支持 10+ 种拖拽场景,覆盖绝大部分业务需求
- 性能优异,大数据量拖拽仍流畅
- API 简洁易用,接入成本低
- 兼容主流浏览器和移动端
```text