React useActionState 怎样展示异步表单状态

我在把一个“保存资料”表单改成异步提交时，最容易失控的不是请求本身，而是提交中、校验失败和成功结果分别由三套状态驱动：按钮在转圈，错误却没有清掉，输入框还被自动重置。React 的 useActionState 适合把这三件事收拢到一个 Action 返回值里。

官方地址：https://react.dev/reference/react/useActionState

把异步表单函数写成“接收上一份状态，返回下一份状态”，再用 [state, formAction, isPending] 连接表单。isPending 管提交中的反馈，state.error 管已知校验错误，submitted 可以保留失败时的用户输入。

先把 Action 返回值设计成状态对象

我会先固定状态形状，再写 JSX。这样成功和失败都返回同一种对象，组件不需要猜测某次请求到底返回了字符串还是异常。浏览器端示例中，Action 的第二个参数是表单提交得到的 FormData；第一个参数始终是上一次返回的状态。

import { useActionState } from 'react';

// 中文注释：统一返回结构，避免成功和失败分支让 UI 失去可预测性。
const initialState = { error: null, submitted: null, savedName: null };

async function saveName(previousState, formData) {
  const name = String(formData.get('name') ?? '').trim();

  // 中文注释：已知校验错误作为状态返回，调用方可以继续显示表单。
  if (name.length 

这里的关键不是把所有异常都塞进 error。例如后端明确返回“名称已存在”属于可展示的业务错误；而代码中的未定义函数、网络层未处理异常，则更适合抛出后交给最近的错误边界。这样用户能区分“输入需要修改”和“页面需要恢复”。

用三个返回值接住表单提交状态

Hook 必须在组件顶层调用。返回数组的三个位置分别是当前状态、Action dispatcher 和 pending 标志；把第二项直接交给 form 的 action 属性后，React 会自动处理提交的 Transition。

export default function ProfileForm() {
  // 中文注释：state 管结果，formAction 管提交，isPending 管提交中的 UI。
  const [state, formAction, isPending] = useActionState(
    saveName,
    initialState
  );

  return (
    

      姓名
      
        {isPending ? '保存中…' : '保存'}
      
      {state.error && 
{state.error}
}
      {state.savedName && 
已保存：{state.savedName}
}
    
  );
}

提交中的界面只做两件事：给按钮明确反馈，并暂时阻止同一个表单重复点击。不要把 isPending 写成“请求一定成功”的暗示，它只表示这个 Hook 还有 Action 在处理；成功与否仍以 state 为准。

把 pending、错误与回填放进表单 UI

校验失败时返回原始 FormData，再用 defaultValue 读取它，能避免 React 的自动表单重置把用户刚输入的内容抹掉。成功时把 submitted 置为 null，表单才回到清空状态。这个约定比在多个 useState 之间手动同步更容易复查。

如果同一个 Action 连续触发多次，React 会按顺序排队，因为后一次会接收前一次的返回状态。需要“立即显示数量变化”时，可以额外使用 useOptimistic；如果每次操作必须并行，useActionState 就不是最合适的抽象，应改用 useState 与 useTransition 自己组织并发关系。

上线前按边界做一次复查

最后再看状态类型：Action 返回值必须和初始状态保持一致；如果使用 Server Function，状态与 action payload 还需要可序列化。对我来说，最稳的落地顺序是先让状态对象稳定，再接入真实请求，最后才增加乐观更新或取消排队。这样每个界面状态都有清楚的来源。

相关问题

useActionState 能替代 useReducer 吗？

不能简单替代。useReducer 更适合纯粹管理 UI 状态；useActionState 的 Action 可以执行异步副作用，并按前一次结果顺序处理提交。

已知接口错误应该 throw 吗？

如果错误需要用户修改输入，返回包含 error 的状态更合适；不可预期的程序异常再抛出，让 Error Boundary 负责兜底。