SvelteKit SuperForms 实现多阶段表单数据共享方案

在实际开发中，我们经常会遇到需要分阶段收集用户信息的表单场景。本文将介绍如何利用 SvelteKit SuperForms 库实现一个包含两个阶段（邮箱验证和OTP输入）的表单流程，并解决阶段间数据共享的问题。

多阶段表单的基本实现

首先，我们创建一个包含两个阶段的基本表单结构：

<script lang="ts">
  let stage = $state<'one' | 'two'>('one');
  
  let stages = {
    one: zod(AuthSchema.pick({ email: true })),
    two: zod(AuthSchema)
  };
  
  // 表单初始化代码...
</script>

<form>
  {#if stage === 'one'}
    <!-- 第一阶段：邮箱输入 -->
  {/if}
  
  {#if stage === 'two'}
    <!-- 第二阶段：OTP输入 -->
  {/if}
</form>

动态切换验证模式

SuperForms 允许我们动态切换验证模式。通过 $effect 监听阶段变化，我们可以更新表单验证器：

$effect(() => {
  form.options.validators = stages[stage];
});

阶段间数据共享的核心问题

当从第一阶段切换到第二阶段时，用户在第一阶段输入的邮箱信息会丢失。这是因为：

1. 每个阶段使用不同的验证模式
2. 表单数据没有在阶段切换时被保留

解决方案：程序化更新表单数据

SuperForms 提供了 form.update 方法，允许我们程序化地更新表单数据。在阶段切换时，我们可以手动保留前一阶段的数据：

onUpdated({ form: { message } }) {
  if (message?.status === 'success') {
    // 保存当前邮箱数据
    const email = formData.email;
    
    // 切换到第二阶段
    stage = 'two';
    
    // 恢复邮箱数据
    form.update({
      email
    });
  }
}

完整实现示例

<script lang="ts">
  // 省略导入部分...
  
  let stage = $state<'one' | 'two'>('one');
  let stages = {
    one: zod(AuthSchema.pick({ email: true })),
    two: zod(AuthSchema)
  };

  const form = superForm(data.form, {
    async onSubmit(input) {
      if (stage === 'two') return;
      
      const result = await form.validateForm({ update: true });
      if (result.valid) {
        input.formElement.requestSubmit();
      }
    },
    onUpdated({ form: { message } }) {
      if (message) {
        if (message.status === 'success') {
          const email = $formData.email;
          stage = 'two';
          form.update({ email });
          toast.success(message.text);
        } else {
          toast.error(message.text);
        }
      }
    }
  });

  $effect(() => {
    form.options.validators = stages[stage];
  });
</script>

最佳实践建议

1. 状态管理：考虑使用更健壮的状态管理方案，如 Svelte store，来处理复杂的多阶段表单状态。

2. 数据验证：确保在阶段切换时验证前一阶段的数据有效性。

3. 用户体验：添加清晰的进度指示，让用户了解当前所处的阶段。

4. 错误处理：为每个阶段实现独立的错误处理逻辑。

通过上述方法，我们可以构建一个既保持数据完整性又提供流畅用户体验的多阶段表单。SuperForms 的灵活性使得这种复杂交互的实现变得简单而优雅。