SvelteKit-Superforms 实现文件上传进度条功能详解

在 SvelteKit 应用开发中，表单处理是一个常见需求，而 sveltekit-superforms 作为一款优秀的表单库，近期在 v2.16.0 版本中新增了自定义请求功能，使得开发者能够轻松实现文件上传进度条等高级功能。

传统表单上传的局限性

在 Web 开发中，传统的表单提交方式无法提供上传进度反馈，用户只能被动等待上传完成。虽然现代浏览器提供了 Fetch API，但它缺乏对上传进度的原生支持，这给需要显示上传进度的场景带来了挑战。

XMLHttpRequest 的解决方案

XMLHttpRequest 对象提供了 progress 事件，可以监听上传进度。通过监听 xhr.upload.onprogress 事件，开发者能够获取上传的字节数和总字节数，从而计算出上传百分比并更新进度条。

sveltekit-superforms 的集成方案

sveltekit-superforms 从 v2.16.0 版本开始，通过 customRequest 选项完美支持了自定义请求功能。开发者现在可以：

1. 在表单配置中指定 customRequest 函数
2. 创建自定义的 XMLHttpRequest 对象
3. 实现进度事件监听
4. 手动处理响应数据

实现步骤详解

基本实现

首先，在 Svelte 组件中导入并初始化 superForm：

import { superForm } from 'sveltekit-superforms'
import { zodSchema } from 'sveltekit-superforms/adapters'

// 初始化表单
const { form, enhance } = superForm({
  // 表单配置
})

自定义请求实现

然后，在表单配置中添加 customRequest 函数：

const { form, enhance } = superForm({
  customRequest: async ({ formElement, cancel, submitter }) => {
    // 创建 XMLHttpRequest 对象
    const xhr = new XMLHttpRequest()
    
    // 设置进度监听
    xhr.upload.onprogress = (event) => {
      if (event.lengthComputable) {
        const percent = Math.round((event.loaded / event.total) * 100)
        console.log(`上传进度: ${percent}%`)
        // 更新进度条状态
      }
    }
    
    // 处理响应
    xhr.onload = () => {
      if (xhr.status >= 200 && xhr.status < 300) {
        // 处理成功响应
      } else {
        // 处理错误
      }
    }
    
    // 发送请求
    xhr.open(formElement.method, formElement.action)
    xhr.send(new FormData(formElement))
    
    // 返回一个可取消的 Promise
    return {
      response: new Promise((resolve) => {
        xhr.onload = () => resolve(xhr.response)
      }),
      cancel: () => xhr.abort()
    }
  }
})

多文件上传进度处理

对于需要处理多个文件上传进度的情况，可以在服务器端实现分块上传，并通过自定义事件或长轮询将进度信息返回给客户端：

// 服务器端代码示例
export const actions = {
  default: async ({ request }) => {
    const formData = await request.formData()
    const files = formData.getAll('files')
    
    for (const [index, file] of files.entries()) {
      await uploadToCloudStorage(file, (progress) => {
        // 这里可以通过 Server-Sent Events 或 WebSocket 发送进度到客户端
        console.log(`文件 ${index} 上传进度: ${progress}%`)
      })
    }
    
    return { success: true }
  }
}

最佳实践建议

1. 用户体验优化：在上传过程中显示进度条的同时，考虑添加取消上传按钮和预估剩余时间显示。

2. 错误处理：完善错误处理逻辑，包括网络错误、文件大小限制等情况的友好提示。

3. 性能考虑：对于大文件上传，建议实现分块上传以提升可靠性和用户体验。

4. 状态管理：使用 Svelte 的 store 或组件状态来管理上传进度，确保 UI 及时更新。

总结

sveltekit-superforms 通过 customRequest 功能的引入，为开发者提供了更大的灵活性，使得实现文件上传进度条等高级功能变得简单直接。这一改进不仅提升了用户体验，也展示了该库对开发者需求的快速响应能力。

对于需要更复杂上传场景的开发者，可以结合 Server-Sent Events 或 WebSocket 实现实时进度更新，构建更加完善的文件上传解决方案。