在 next-safe-action…

在 next-safe-action 项目中为表单选择并实现合适的集成方式（原生表单、useStateAction 或 React Hook Form 适配器）。

适用场景

解决思路

1. 根据场景选择方案：简单表单、无复杂校验 UI、需程序化触发时用 `useAction` + 原生表单；需要状态跟踪、访问 `prevResult`、完整回调时用 `useStateAction` + `<form action={formAction}>`；复杂表单、字段级错误、change/blur 校验时用 `useHookFormAction`（RHF 适配器）；需要乐观 UI 更新的 RHF 表单用 `useHookFormOptimisticAction`；需要即时 UI 且重叠写入必须排队累积时用 `useOptimisticStateAction`。
2. useStateAction 表单：从 `next-safe-action/hooks` 导入 `useStateAction`，传入 server action 并配置 `onSuccess` 等回调，解构出 `formAction`、`result`、`isPending`、`hasSucceeded`，在 `<form action={formAction}>` 中使用，并渲染 `result.validationErrors?.email._errors?.[0]`、`result.serverError`、`hasSucceeded` 提示，提交按钮用 `isPending` 控制 disabled 与文案。
3. 注意 `useStateAction` 要求 server action 用 `.stateAction()` 而非 `.action()` 定义，且 `<form action={formAction}>` 传入原始 `FormData`，其输入 schema 必须能解析 `FormData`（如 `zod-form-data` 的 `zfd.formData({...})`）。
4. 原生表单：从 `next-safe-action/hooks` 导入 `useAction`，解构 `execute`、`result`、`isPending`，在 `<form onSubmit>` 中 `e.preventDefault()`，用 `new FormData(e.currentTarget)` 读取字段并调用 `execute({...})`，渲染 `result.validationErrors`、`result.serverError`、`result.data`，按钮用 `isPending` 控制。
5. React Hook Form 适配器：从 `@next-safe-action/adapter-react-hook-form/hooks` 导入 `useHookFormAction`，配合 `zodResolver` 与 zod schema，传入 server action、resolver 和 `actionProps`（如 `onSuccess`），解构 `form`、`handleSubmitWithAction`、`action`，在 `<form onSubmit={handleSubmitWithAction}>` 中用 `form.register` 注册字段，渲染 `form.formState.errors.<field>.message` 与 `action.result.serverError`，按钮用 `action.isPending` 控制。
6. 参考支持文档：原生表单提交模式见 `./form-actions.md`，RHF 适配器深入见 `./react-hook-form.md`，文件上传见 `./file-uploads.md`。
7. 入口点：`@next-safe-action/adapter-react-hook-form` 默认入口导出 `mapToHookFormErrors` 与类型；`@next-safe-action/adapter-react-hook-form/hooks` 导出 `useHookFormAction`、`useHookFormOptimisticAction`、`useHookFormActionErrorMapper`。