告别繁琐排序：dnd-kit + React Hook Form 打造流畅表单拖拽体验

你是否还在为表单中的列表排序功能编写冗长代码？是否遇到过拖拽排序与表单验证冲突的问题？本文将展示如何通过 dnd-kit 与 React Hook Form 的无缝集成，仅需 10 分钟即可实现兼具美感与功能性的表单拖拽排序功能。读完本文你将掌握：拖拽排序与表单状态同步、复杂表单场景下的性能优化、无障碍拖拽实现方案。

核心组件与集成原理

dnd-kit 提供了现代化的拖拽基础设施，其核心能力来自 DndContext 组件和 useSortable 钩子。DndContext 作为拖拽系统的中枢，管理着整个应用的拖拽状态，而 useSortable 则为列表项提供了排序能力。

React Hook Form 则通过非受控组件和 refs 实现高效表单管理。两者集成的关键在于将拖拽产生的排序变化同步到 React Hook Form 的表单状态中，同时保持表单验证的实时性。

// 核心集成架构
<DndContext onDragEnd={handleDragEnd}>
  <SortableContext items={formValues.items.map(i => i.id)}>
    {formValues.items.map((item, index) => (
      <SortableItem key={item.id} id={item.id}>
        <Controller
          name={`items.${index}.name`}
          control={control}
          render={({ field }) => <input {...field} />}
        />
      </SortableItem>
    ))}
  </SortableContext>
</DndContext>

完整实现步骤

1. 安装依赖

首先安装必要的依赖包，包括 dnd-kit 的核心模块和 React Hook Form：

npm install @dnd-kit/core @dnd-kit/sortable react-hook-form

2. 基础表单与拖拽列表实现

创建一个包含可排序列表的表单，使用 useForm 初始化表单状态，设置初始列表数据：

import { useForm, Controller } from 'react-hook-form';
import { DndContext, DragEndEvent } from '@dnd-kit/core';
import { SortableContext, useSortable } from '@dnd-kit/sortable';
import { CSS } from '@dnd-kit/utilities';

// 定义表单数据类型
type Item = {
  id: string;
  name: string;
  description: string;
};

type FormValues = {
  items: Item[];
};

export default function SortableForm() {
  const { control, watch, setValue } = useForm<FormValues>({
    defaultValues: {
      items: [
        { id: '1', name: '项目 1', description: '描述 1' },
        { id: '2', name: '项目 2', description: '描述 2' },
        { id: '3', name: '项目 3', description: '描述 3' }
      ]
    }
  });
  
  const formValues = watch();
  
  // 拖拽结束处理函数
  const handleDragEnd = (event: DragEndEvent) => {
    const { active, over } = event;
    if (!over) return;
    
    const activeIndex = formValues.items.findIndex(i => i.id === active.id);
    const overIndex = formValues.items.findIndex(i => i.id === over.id);
    
    if (activeIndex !== overIndex) {
      // 创建新数组，避免直接修改状态
      const newItems = [...formValues.items];
      const [movedItem] = newItems.splice(activeIndex, 1);
      newItems.splice(overIndex, 0, movedItem);
      
      // 更新表单状态
      setValue('items', newItems);
    }
  };
  
  return (
    <form>
      <DndContext onDragEnd={handleDragEnd}>
        <SortableContext items={formValues.items.map(i => i.id)}>
          {formValues.items.map((item, index) => (
            <SortableItem key={item.id} id={item.id} index={index}>
              <div className="item-content">
                <Controller
                  name={`items.${index}.name`}
                  control={control}
                  render={({ field }) => (
                    <input 
                      {...field} 
                      placeholder="名称" 
                      className="form-input"
                    />
                  )}
                />
                <Controller
                  name={`items.${index}.description`}
                  control={control}
                  render={({ field }) => (
                    <textarea 
                      {...field} 
                      placeholder="描述" 
                      className="form-textarea"
                    />
                  )}
                />
              </div>
            </SortableItem>
          ))}
        </SortableContext>
      </DndContext>
    </form>
  );
}

3. 实现 SortableItem 组件

创建可排序列表项组件，使用 useSortable 钩子获取拖拽属性，并应用到元素上：

const SortableItem = ({ id, children }: { id: string; children: React.ReactNode }) => {
  const {
    attributes,
    listeners,
    setNodeRef,
    transform,
    transition,
    isDragging
  } = useSortable({ id });
  
  const style = {
    transform: CSS.Transform.toString(transform),
    transition,
    opacity: isDragging ? 0.5 : 1,
    cursor: 'grab'
  };
  
  return (
    <div
      ref={setNodeRef}
      style={style}
      {...attributes}
      {...listeners}
      className="sortable-item"
    >
      <div className="drag-handle">::</div>
      {children}
    </div>
  );
};

性能优化策略

对于包含大量字段或复杂验证逻辑的表单，需要实施性能优化。关键优化点包括：

1. 使用 React.memo 包装列表项组件，避免不必要的重渲染
2. 对于超过 50 项的长列表，实现虚拟滚动，可配合 react-window
3. 拖拽过程中暂停表单验证，拖拽结束后恢复

// 性能优化示例 - 使用 useCallback 和 React.memo
const SortableItem = React.memo(({ 
  id, 
  index, 
  children,
  control 
}: SortableItemProps) => {
  // 使用 useCallback 记忆化处理函数
  const handleChange = useCallback((value: string) => {
    // 处理逻辑
  }, []);
  
  // ...
});

无障碍支持与键盘导航

dnd-kit 内置了完善的无障碍支持，通过 Accessibility 组件实现。要确保拖拽功能对键盘用户友好，需添加键盘导航支持：

// 无障碍配置
<DndContext
  onDragEnd={handleDragEnd}
  sensors={[
    useSensor(MouseSensor),
    useSensor(TouchSensor),
    useSensor(KeyboardSensor, {
      coordinateGetter: keyboardCoordinates
    })
  ]}
>
  {/* 列表内容 */}
</DndContext>

高级应用场景

嵌套表单与拖拽

在嵌套表单场景中，可通过调整字段名称路径实现深层对象的拖拽排序：

// 嵌套表单拖拽示例
<Controller
  name={`sections.${sectionIndex}.items.${itemIndex}.name`}
  control={control}
  render={({ field }) => <input {...field} />}
/>

拖拽过程中的表单验证

如需在拖拽过程中保持表单验证，可使用 React Hook Form 的 trigger 方法手动触发验证：

// 拖拽结束后触发验证
const handleDragEnd = async (event: DragEndEvent) => {
  // ...排序逻辑
  
  // 触发表单验证
  await trigger();
};

常见问题与解决方案

1. 表单状态不同步：确保使用 setValue 更新整个数组，而非单独修改元素
2. 性能问题：使用 React.memo 和 useCallback 优化列表项渲染
3. 复杂验证场景：拖拽结束后使用 trigger 方法手动触发验证
4. 移动端兼容性：确保引入 TouchSensor 并测试触摸设备上的体验

通过 dnd-kit 与 React Hook Form 的集成，我们实现了既美观又高效的表单拖拽排序功能。这种方案不仅代码简洁，而且性能优异，同时支持完整的无障碍特性。无论你是构建简单的待办事项列表，还是复杂的多步骤表单，这种集成方案都能满足需求。

完整示例代码可在项目 playground 目录中找到，包含各种复杂度的表单拖拽实现。尝试将这种技术应用到你的项目中，提升用户体验和开发效率。