React useFormStatus：全面的表单状态管理指南

在 React 18 中引入的 useFormStatus 钩子提供了一种强大而高效的方式来管理 React 服务器组件（React Server Components）中表单的提交状态。该钩子专门设计用于与服务器操作（Server Actions）协同工作，为直接在服务器上处理表单提交提供了无缝集成。它简化了跟踪表单提交状态的过程，提供了诸如表单是否处于待处理、成功或遇到错误等有价值的信息。本指南将探讨 useFormStatus 的功能、其优势以及在各种场景下展示其用法的实践示例。

理解服务器操作与 useFormStatus

在深入了解 useFormStatus 之前，理解 React 服务器组件和服务器操作至关重要。服务器操作允许您定义在服务器上运行的函数，这些函数可以直接从您的 React 组件中访问。这使得处理表单提交、数据获取和其他服务器端操作无需单独的 API 端点成为可能。

useFormStatus 钩子则提供了对由表单提交触发的这些服务器操作执行情况的洞察。

什么是 useFormStatus？

useFormStatus 是一个 React 钩子，它返回一个包含有关最近一次表单提交状态信息的对象。这些信息包括：

• pending: 一个布尔值，指示表单当前是否正在提交中。
• data: 与提交关联的 FormData 对象。
• method: 用于提交的 HTTP 方法（通常是 'POST'）。
• action: 被触发的服务器操作函数。

使用 useFormStatus 的好处

利用 useFormStatus 带来了几个关键优势：

• 简化的状态管理： 无需手动进行状态管理来跟踪表单提交状态。该钩子会随着提交过程的进展而自动更新。
• 改善的用户体验： 向用户提供实时反馈，例如在表单处理期间显示加载指示器或在失败时显示错误消息。
• 简洁的代码： 通过将表单提交逻辑与组件渲染分离，促进了更具声明性和可维护性的代码库。
• 与服务器操作的无缝集成： 专为与服务器操作完美配合而设计，使得直接在服务器上处理表单提交变得容易。

useFormStatus 的实践示例

让我们探讨几个实践示例，以说明 useFormStatus 在不同场景下的用法。

带加载指示器的基本表单提交

此示例演示了一个简单的表单，在提交期间会显示一个加载指示器。

服务器操作 (actions.js)：

'use server'

export async function submitForm(formData) {
  // 模拟延迟以展示加载状态
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Form submitted with name:', name);
  return { message: `Form submitted successfully with name: ${name}` };
}

React 组件 (FormComponent.jsx)：

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      名称：
      
      
        {pending ? '提交中...' : '提交'}
      
    
  )
}

export default FormComponent

在此示例中，来自 useFormStatus 的 pending 属性用于在表单提交期间禁用输入字段和按钮，并显示“提交中...”的消息。

处理成功与错误状态

此示例演示了如何在表单提交后处理成功和错误状态。

服务器操作 (actions.js)：

'use server'

export async function submitForm(formData) {
  // 模拟延迟
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');

  if (!name) {
    throw new Error('名称是必填项');
  }

  console.log('Form submitted with name:', name);
  return { message: `Form submitted successfully with name: ${name}` };
}

React 组件 (FormComponent.jsx)：

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      名称：
      
      
        {pending ? '提交中...' : '提交'}
      
      {pending && 
提交中...
}
      {message && 
{message}
}
      {error && 
错误： {error}
}
    
  )
}

export default FormComponent

在此示例中，handleSubmit 函数中使用了一个 try/catch 块。如果服务器操作抛出错误，它将被捕获并显示给用户。成功提交后会显示一条成功消息。

使用 FormData 处理复杂数据

useFormStatus 与 FormData 无缝协作，让您可以轻松处理复杂的数据结构。以下是一个展示如何上传文件的示例。

服务器操作 (actions.js)：

'use server'

export async function uploadFile(formData) {
  // 模拟文件处理
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('没有上传文件');
  }

  console.log('File uploaded:', file.name);
  return { message: `File uploaded successfully: ${file.name}` };
}

React 组件 (FormComponent.jsx)：

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      上传文件：
      
      
        {pending ? '上传中...' : '上传'}
      
      {pending && 
上传中...
}
      {message && 
{message}
}
      {error && 
错误： {error}
}
    
  )
}

export default FormComponent

此示例演示了如何使用 FormData 处理文件上传。服务器操作从 FormData 对象中检索文件并进行处理。useFormStatus 钩子在文件上传期间管理加载状态。

使用 useFormStatus 的最佳实践

为了最大化 useFormStatus 的好处，请考虑以下最佳实践：

• 提供清晰的用户反馈： 使用 pending 状态来显示信息丰富的加载指示器，并禁用表单元素以防止多次提交。
• 优雅地处理错误： 实现错误处理以捕获服务器操作中的异常，并显示用户友好的错误消息。
• 在服务器上验证数据： 执行服务器端验证以确保数据的完整性和安全性。
• 保持服务器操作简洁： 将服务器操作集中于特定任务，以提高性能和可维护性。
• 考虑可访问性： 通过提供适当的标签、ARIA 属性和键盘导航支持，确保您的表单是可访问的。

高级用例

除了基本示例外，useFormStatus 还可以用于更复杂的场景：

• 渐进式增强： 使用服务器操作和 useFormStatus 来渐进式增强您的表单，为禁用 JavaScript 的用户提供基本体验，为启用 JavaScript 的用户提供更丰富的体验。
• 乐观更新： 在表单提交后立即更新 UI，假设提交会成功，从而实现乐观更新。如果提交失败，则回滚更新。
• 与表单库集成： 将 useFormStatus 与流行的表单库（如 Formik 或 React Hook Form）集成，以管理表单状态和验证。虽然这些库通常有自己的状态管理，但 useFormStatus 在最终提交到服务器操作的阶段会很有用。

国际化（i18n）的注意事项

为全球受众构建表单时，国际化（i18n）至关重要。以下是在使用 useFormStatus 时如何考虑 i18n：

• 本地化的错误消息： 确保向用户显示的错误消息已本地化为其首选语言。这可以通过将错误消息存储在翻译文件中并使用像 react-intl 或 i18next 这样的库来检索适当的翻译来实现。
• 日期和数字格式化： 根据用户的区域设置处理日期和数字的格式化。使用像 Intl.DateTimeFormat 和 Intl.NumberFormat 这样的库来正确格式化这些值。
• 从右到左（RTL）支持： 如果您的应用程序支持从右到左书写的语言（例如阿拉伯语、希伯来语），请确保您的表单样式正确，以适应 RTL 布局。
• 表单验证： 根据不同的区域设置调整表单验证规则。例如，电话号码的验证可能在不同国家之间差异很大。

本地化错误消息示例：

// translations/en.json
{
  "form.error.nameRequired": "Please enter your name.",
  "form.success.submission": "Thank you for your submission!"
}

// translations/fr.json
{
  "form.error.nameRequired": "Veuillez entrer votre nom.",
  "form.success.submission": "Merci pour votre soumission !"
}

// 使用 react-intl 的组件
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

可访问性注意事项

可访问性是构建包容性 Web 应用程序的关键方面。以下是使用 useFormStatus 时需要记住的几个可访问性注意事项：

• ARIA 属性： 使用 ARIA 属性为辅助技术提供有关表单状态的信息。例如，在表单处于待处理状态时，在提交按钮上使用 aria-busy="true"。
• 标签： 确保所有表单字段都有清晰且描述性的标签，并使用 <label> 元素与输入元素相关联。
• 错误消息： 以易于残障用户注意和理解的方式显示错误消息。使用像 aria-live="assertive" 这样的 ARIA 属性向屏幕阅读器播报错误消息。
• 键盘导航： 确保用户可以仅使用键盘导航表单。使用 tabindex 属性来控制元素接收焦点的顺序。
• 颜色对比度： 确保表单中使用的文本和背景颜色具有足够的对比度，以便视力障碍用户可以轻松阅读。

useFormStatus 与传统状态管理的比较

传统上，React 开发人员使用组件状态（useState）或更复杂的状态管理库（例如 Redux、Zustand）来管理表单提交状态。以下是这些方法与 useFormStatus 的比较：

功能	useFormStatus	useState	外部状态管理
复杂度	低	中	高
与服务器操作的集成	无缝	需要手动集成	需要手动集成
样板代码	最少	中等	大量
适用场景	直接提交到服务器操作的表单	状态有限的简单表单	跨组件共享状态的复杂表单

当您的表单直接与 React 服务器操作交互时，useFormStatus 的优势就显现出来了。它减少了样板代码并简化了流程。然而，对于需要在多个组件之间共享状态的非常复杂的表单，一个功能齐全的状态管理库可能仍然是必要的。

常见问题排查

以下是您在使用 useFormStatus 时可能遇到的一些常见问题以及如何排查它们：

• useFormStatus 没有更新：
  • 确保您在 <form> 元素内部使用 useFormStatus，并且该表单的 action 属性设置为服务器操作。
  • 验证服务器操作是否已正确定义和导出。
  • 检查服务器操作中是否有任何可能阻止其成功完成的错误。
• 错误消息未显示：
  • 确保您在服务器操作中正确捕获了错误并返回了错误消息。
  • 验证您是否在组件中使用 error 状态来显示错误消息。
• 加载指示器未出现：
  • 确保您使用 useFormStatus 中的 pending 状态来有条件地显示加载指示器。
  • 检查服务器操作是否确实需要一些时间才能完成（例如，通过模拟延迟）。

结论

useFormStatus 提供了一种简洁高效的方式来管理使用服务器组件的 React 应用程序中的表单提交状态。通过利用这个钩子，您可以简化代码、改善用户体验并与服务器操作无缝集成。本指南涵盖了 useFormStatus 的基础知识，提供了实践示例，并讨论了有效使用它的最佳实践。通过将 useFormStatus 融入您的 React 项目，您可以简化表单处理，为全球受众构建更健壮、更用户友好的应用程序。