React19的useFormStatus和useActionState怎么区分？

职责定位：状态管理 vs 上下文监听

在 React 19 之前，表单提交通常依赖手写的 useState、onSubmit 拦截以及复杂的防抖节流逻辑。React 19 引入了基于 Action 的异步状态调度机制，并把对表单的支持拆分为两个专职 Hook：一个用于处理“业务逻辑与状态结果”，另一个用于处理“表单交互中的 UI 状态感知”。

useActionState（由之前的实验性 API useFormState 演进并重命名而来）直接隶属于 react 核心包。它的目标是围绕一个异步或同步的 Action 函数维护状态机。无论是表单提交、乐观更新还是普通的按钮异步触发，它都会接收旧状态和输入参数，并在 Action 完成后更新组件中的响应数据。

与之不同，useFormStatus 隶属于 react-dom 包。它不处理具体的业务数据流转，也不产生新的状态值，而是通过 React 内部注入的 Form Context 隐式读取离它最近的父级 <form> 标签的实时运行信息。它专门解决子组件无法获知父表单提交进度的通信难题。

调用位置与层级约束

很多开发者在初学 React 19 时遇到的第一个错误，往往是在同一个组件内部同时声明 <form> 并调用 useFormStatus。这种写法会导致 pending 永远保持为 false。

useFormStatus 的上下文限制

当 React 渲染 <form action={formAction}> 时，React DOM 内部会在该 DOM 节点处建立一个隐式的上下文提供者（Form Context Provider）。只有在这个 <form> 树状分支内部被渲染的子组件，才能通过 useFormStatus() 读取到挂起状态：

useActionState 的自由声明

useActionState 并不依赖任何 Form Context。它的地位与普通的 useReducer 或 useState 类似，可以在任意组件顶层调用。调用后，它会生成一个经过包装的 formAction 函数，你可以将它直接挂载在 <form action={formAction}> 上，也可以挂载在具体按钮的 formAction 属性上。

签名结构与返回值边界对比

理解两个 Hook 的入参与返回值，能帮助我们清晰划定它们在日常编码中的能力边界。

返回值属性细节

在 useActionState 中，返回的 state 具有状态持久性。当 Action 完成并返回 { error: '邮箱格式错误' } 时，该对象会被保存在当前组件中，直到下一次提交重置。

而在 useFormStatus 中，返回的四个属性完全是瞬态的：

• pending：布尔值。父级表单处于提交中时为 true，提交结束即刻恢复 false。
• data：FormData 实例。包含当前提交的所有字段数据。如果表单未在提交中，则为 null。
• method：字符串。父表单的提交方式，默认为 'get' 或 'post'。
• action：函数引用。指向传给父表单 action 属性的实际处理函数。

表单提交生命周期与流转时序

当用户在页面上点击提交按钮时，两个 Hook 并不是割裂工作的，而是沿着表单的生命周期协同演进。了解具体的执行时序，有助于排查界面交互时因状态更新先后引起的逻辑问题。

整个流程可以细分为五个关键阶段：

1. 触发阶段：用户在表单内填写完毕后触发提交事件，React 内部接管原生行为，准备将表单数据封装为 FormData。
2. UI 锁定阶段：React 激活 Form Context，useFormStatus 的 pending 率先转为 true，此时子组件中的提交按钮立即被禁用，展示加载文案，从源头上阻断重复点击。
3. Action 调度阶段：useActionState 内部开启过渡更新，其返回的 isPending 变为 true，开始异步调用与网络通信。
4. 结果回传阶段：服务端或异步逻辑执行完毕，Action 函数返回最新的响应数据，useActionState 捕获新数据并赋值给 state。
5. 生命周期复位：pending 与 isPending 同步恢复为 false，子组件解除禁用，父组件根据最新的 state 显示提示信息或重置表单。

实战代码：两者协同的最佳实践

下面展示一个完整的用户信息修改表单。在这个示例中，父组件利用 useActionState 处理接口请求和错误提示，子组件 <SubmitButton /> 利用 useFormStatus 独立实现按钮状态切换与禁用控制，无需任何 props 传递。

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

// 模拟异步服务端 Action 逻辑
async function updateProfile(previousState, formData) {
  const nickname = formData.get('nickname');
  await new Promise((resolve) => setTimeout(resolve, 1000));

  if (!nickname || nickname.trim().length < 2) {
    return { success: false, message: '昵称不能少于2个字符' };
  }
  return { success: true, message: '个人资料更新成功' };
}

// 独立的提交按钮组件（利用 useFormStatus 读取表单 Context）
function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button 
      type="submit" 
      disabled={pending}
      style={{
        backgroundColor: pending ? '#CBD5E1' : '#477DAD',
        color: '#FFFFFF',
        padding: '8px 18px',
        border: 'none',
        borderRadius: '6px',
        cursor: pending ? 'not-allowed' : 'pointer'
      }}
    >
      {pending ? '正在保存...' : '保存设置'}
    </button>
  );
}

// 表单主容器（利用 useActionState 管理业务状态）
export default function ProfileEditor() {
  const [state, formAction] = useActionState(updateProfile, {
    success: null,
    message: ''
  });

  return (
    <div style={{ padding: '24px', maxWidth: '400px' }}>
      <h3>修改个人昵称</h3>

      <form action={formAction}>
        <div style={{ marginBottom: '16px' }}>
          <label htmlFor="nickname">昵称：</label>
          <input 
            id="nickname" 
            name="nickname" 
            type="text" 
            required 
            style={{ width: '100%', padding: '6px', marginTop: '6px' }}
          />
        </div>

        <SubmitButton />
      </form>

      {state.message && (
        <p style={{ 
          marginTop: '14px', 
          color: state.success ? '#16A34A' : '#DC2626' 
        }}>
          {state.message}
        </p>
      )}
    </div>
  );
}

选型决策与协同法则

在面对不同类型的表单交互需求时，可以参照以下决策路径进行技术选型：

单独使用 useActionState 的情况

当表单结构非常精炼（例如只有一个简单的单行搜索框或简短的订阅输入），且提交按钮就直接写在表单组件内部时，你可以直接解构 useActionState 提供的第三个参数 isPending：

const [state, formAction, isPending] = useActionState(searchAction, initial);

return (
  <form action={formAction}>
    <input name="query" />
    <button disabled={isPending}>搜索</button>
  </form>
);

在这种极简结构下，无需为了使用 useFormStatus 而刻意抽离一个独立的按钮组件，直接使用 isPending 即可达到相同的防重复提交效果。

必须使用 useFormStatus 的情况

当项目遵循通用组件库（Design System）规范，所有的提交按钮、乐观指示器或表单状态栏都必须封装为可复用的公共组件时，useFormStatus 是唯一的优雅解法。它让公共按钮不需要定义 isLoading 或 disabled 的繁琐 props，只要放进任何 <form>，便能自动感知状态并生效。