useFormStatus

核心概述

在 React 19 之前,如果你想在表单按钮中显示"提交中..."状态, 必须通过 props 将 pending 状态从父组件传递到子组件,这导致:

• Props 穿透问题:需要在多个层级传递 pending 状态
• 组件耦合:子组件依赖父组件传递的状态
• 代码冗余:每个按钮组件都需要接收 pending prop

useFormStatus 是 React 19 引入的 Hook, 专门用于解决表单内子组件获取提交状态的问题。它会自动返回最近父级 <form> 的状态信息, 无需手动传递 props。

典型应用场景:

• 显示按钮的 loading 状态(禁用按钮 + 显示"提交中...")
• 显示提交进度或加载动画
• 根据提交状态禁用表单输入(防止重复提交)
• 访问提交的 FormData 数据(用于日志或预览)

技术规格

类型签名

function useFormStatus(): {
  pending: boolean;
  data: FormData | null;
  method: 'GET' | 'POST' | undefined;
  action: string | ((formData: FormData) => void) | undefined;
}

返回值说明

使用限制

运行机制

useFormStatus 的实现依赖于 React 的上下文传播机制:

1. 当你在组件中调用 useFormStatus 时,React 会向上遍历组件树查找最近的<form> 元素
2. <form> 元素内部维护一个状态上下文(FormStatusContext), 存储 pending、data、method、action 等信息
3. 当表单提交时,React 会自动更新 FormStatusContext 的值,触发所有使用了 useFormStatus 的子组件重新渲染
4. 子组件通过 useFormStatus 读取最新的状态信息,无需父组件手动传递 props

实战演练

示例 1: 基础按钮状态

显示按钮的 loading 状态,防止重复提交:

import { useFormStatus } from 'react-dom';

function SubmitButton() {
  // 获取最近父表单的提交状态
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending} // 提交期间禁用按钮
      className="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
    >
      {pending ? '提交中...' : '提交'}
    </button>
  );
}

function ContactForm() {
  const handleSubmit = async (formData: FormData) => {
    // 模拟异步提交
    await new Promise((resolve) => setTimeout(resolve, 2000));
  };

  return (
    <form action={handleSubmit}>
      <input name="email" type="email" placeholder="请输入邮箱" />
      <SubmitButton /> {/* 无需传递 pending prop */}
    </form>
  );
}

示例 2: 生产级表单(完整类型 + 错误处理)

结合 useActionState 和 useFormStatus 实现完整的表单状态管理:

'use client';

import { useFormStatus } from 'react-dom';
import { useActionState } from 'react';

// ============ 类型定义 ============
type FormState = {
  success: boolean;
  error: string | null;
  errors: Record<string, string[]>;
};

// ============ Server Action ============
async function submitForm(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  // 模拟网络请求
  await new Promise((resolve) => setTimeout(resolve, 1500));

  const email = formData.get('email') as string;

  // 简单验证
  if (!email || !email.includes('@')) {
    return {
      success: false,
      error: '请输入有效的邮箱地址',
      errors: { email: ['邮箱格式不正确'] },
    };
  }

  // 提交成功
  return {
    success: true,
    error: null,
    errors: {},
  };
}

// ============ 提交按钮组件 ============
function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className="w-full py-2 px-4 bg-blue-600 text-white font-medium rounded-lg
                 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500
                 disabled:opacity-50 disabled:cursor-not-allowed
                 transition-colors duration-200"
    >
      {pending ? (
        <span className="flex items-center justify-center gap-2">
          <svg className="animate-spin h-5 w-5" viewBox="0 0 24 24">
            <circle
              className="opacity-25"
              cx="12"
              cy="12"
              r="10"
              stroke="currentColor"
              strokeWidth="4"
              fill="none"
            />
            <path
              className="opacity-75"
              fill="currentColor"
              d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
            />
          </svg>
          提交中...
        </span>
      ) : (
        '订阅'
      )}
    </button>
  );
}

// ============ 输入框组件 ============
function EmailInput() {
  const { pending } = useFormStatus();

  return (
    <div>
      <label htmlFor="email" className="block text-sm font-medium mb-2">
        邮箱地址
      </label>
      <input
        id="email"
        name="email"
        type="email"
        required
        disabled={pending} // 提交期间禁用输入框
        className="w-full px-3 py-2 border border-gray-300 rounded-lg
                   focus:outline-none focus:ring-2 focus:ring-blue-500
                   disabled:opacity-50 disabled:cursor-not-allowed"
        placeholder="your@email.com"
      />
    </div>
  );
}

// ============ 主表单组件 ============
export default function SubscribeForm() {
  const [state, formAction] = useActionState(submitForm, {
    success: false,
    error: null,
    errors: {},
  });

  if (state.success) {
    return (
      <div className="p-6 bg-green-50 border border-green-200 rounded-lg">
        <h3 className="text-green-800 font-semibold mb-2">订阅成功!</h3>
        <p className="text-green-700">感谢您的订阅。</p>
      </div>
    );
  }

  return (
    <form action={formAction} className="space-y-4 max-w-md">
      <EmailInput />

      {state.error && (
        <div className="p-3 bg-red-50 border border-red-200 rounded-lg">
          <p className="text-red-800 text-sm">{state.error}</p>
        </div>
      )}

      {state.errors.email && (
        <p className="text-red-600 text-sm">{state.errors.email[0]}</p>
      )}

      <SubmitButton />
    </form>
  );
}

示例 3: 访问提交数据

使用 data 属性访问表单提交的数据:

import { useFormStatus } from 'react-dom';

function FormDataLogger() {
  const { pending, data } = useFormStatus();

  // 只在提交期间显示数据
  if (!pending || !data) {
    return null;
  }

  // 读取 FormData 中的字段
  const email = data.get('email');
  const name = data.get('name');

  return (
    <div className="mt-4 p-4 bg-blue-50 border border-blue-200 rounded-lg">
      <p className="text-sm text-blue-800 font-semibold mb-2">正在提交的数据:</p>
      <ul className="text-sm text-blue-700 space-y-1">
        <li>姓名: {name}</li>
        <li>邮箱: {email}</li>
      </ul>
    </div>
  );
}

function FormWithLogger() {
  return (
    <form action={submitAction}>
      <input name="name" placeholder="姓名" />
      <input name="email" placeholder="邮箱" />
      <button type="submit">提交</button>

      <FormDataLogger /> {/* 自动显示提交中的数据 */}
    </form>
  );
}

示例 4: 嵌套表单的状态隔离

每个 useFormStatus 只能访问自己所在的表单状态:

import { useFormStatus } from 'react-dom';

function StatusDisplay({ formName }: { formName: string }) {
  const { pending } = useFormStatus();

  return (
    <div className="text-sm">
      {formName} 状态: {pending ? '提交中...' : '空闲'}
    </div>
  );
}

function FormA() {
  return (
    <form action={actionA} className="p-4 border">
      <h3>表单 A</h3>
      <StatusDisplay formName="表单 A" />
      <button type="submit">提交表单 A</button>
    </form>
  );
}

function FormB() {
  return (
    <form action={actionB} className="p-4 border">
      <h3>表单 B</h3>
      <StatusDisplay formName="表单 B" />
      <button type="submit">提交表单 B</button>
    </form>
  );
}

function NestedForms() {
  return (
    <div>
      <FormA />
      <FormB />
      {/* 两个表单的状态完全独立 */}
    </div>
  );
}

避坑指南

function SubmitButton() {
  const { pending } = useFormStatus(); // 不在任何 form 内部!

  return <button disabled={pending}>提交</button>;
}

function App() {
  return <SubmitButton />; // ❌ 始终返回 { pending: false, data: null }
}

function SubmitButton() {
  const { pending } = useFormStatus(); // 在 form 内部

  return <button disabled={pending}>提交</button>;
}

function App() {
  return (
    <form action={handleSubmit}>
      <SubmitButton /> {/* ✅ 可以正确获取状态 */}
    </form>
  );
}

// ❌ 缺少 'use client' 指令

import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending } = useFormStatus(); // 运行时报错!
  return <button disabled={pending}>提交</button>;
}

// ✅ 添加 'use client' 指令
'use client';

import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending } = useFormStatus(); // 正常工作
  return <button disabled={pending}>提交</button>;
}

function SubmitButton() {
  const { pending } = useFormStatus();

  const handleClick = () => {
    if (pending) {
      // ❌ 这样无法阻止表单提交!
      return;
    }
  };

  return <button onClick={handleClick}>提交</button>;
}

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending} // ✅ 使用 disabled 属性阻止提交
    >
      提交
    </button>
  );
}

// 或者在 action 函数中处理验证逻辑
async function handleSubmit(formData: FormData) {
  const email = formData.get('email');

  if (!email || !email.includes('@')) {
    // ✅ 返回错误信息
    return { success: false, error: '邮箱格式不正确' };
  }

  // 提交逻辑...
}

function SubmitButton() {
  // ❌ 在条件语句中使用 Hook
  if (someCondition) {
    const { pending } = useFormStatus();
    return <button disabled={pending}>提交</button>;
  }

  return <button>提交</button>;
}

function SubmitButton() {
  // ✅ 在组件顶层调用 Hook
  const { pending } = useFormStatus();

  // 然后在条件语句中使用返回值
  if (someCondition) {
    return <button disabled={pending}>提交</button>;
  }

  return <button>提交</button>;
}

最佳实践

✅ 推荐模式

function SubmitButton({ children }: { children: React.ReactNode }) {
  const { pending } = useFormStatus();

  return (
    <button disabled={pending} aria-busy={pending}>
      {pending ? '提交中...' : children}
    </button>
  );
}

// 使用时无需传递任何 props
<form action={handleSubmit}>
  <SubmitButton>提交</SubmitButton>
</form>

// useActionState: 管理表单结果状态
const [state, formAction] = useActionState(submitForm, initialState);

// useFormStatus: 管理提交过程状态
function SubmitButton() {
  const { pending } = useFormStatus();
  return <button disabled={pending}>提交</button>;
}

function FormInput({ name, ...props }: InputProps) {
  const { pending } = useFormStatus();

  return (
    <input
      name={name}
      disabled={pending} // 提交期间禁用
      {...props}
    />
  );
}

function Select({ name, children }: SelectProps) {
  const { pending } = useFormStatus();

  return (
    <select name={name} disabled={pending}>
      {children}
    </select>
  );
}

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      aria-busy={pending} // 辅助技术识别
      className="flex items-center justify-center gap-2"
    >
      {pending && (
        <LoadingSpinner className="animate-spin h-4 w-4" />
      )}
      {pending ? '提交中...' : '提交'}
    </button>
  );
}

function StatusDisplay() {
  const { pending, data, method, action } = useFormStatus();

  // pending: boolean
  // data: FormData | null
  // method: 'GET' | 'POST' | undefined
  // action: string | function | undefined

  if (pending && data) {
    // TypeScript 知道这里 data 不是 null
    const email = data.get('email');
    // email: string | File | null
  }

  return <div>{pending ? '提交中' : '空闲'}</div>;
}

useFormStatus vs useActionState 对比

使用建议

• 优先使用 useFormStatus 处理子组件的 loading 状态,避免 props 穿透
• 在父组件使用 useActionState 管理表单的完整状态(成功/失败/错误)
• 结合两者使用,构建用户体验优秀的表单
• 记住 useFormStatus 只能读取状态,不能修改表单行为
• 确保 useFormStatus 在 <form> 内部使用,否则无法获取状态

延伸阅读

• useActionState - 管理 Server Actions 的完整状态
• use - 读取资源(包括表单提交状态)
• <form> - 表单组件参考
• Server Actions - 服务端表单处理