用途:帮助在 Next.js/Supabase 应用中按既有模式构建客户端表单,避免偏离约定导致的问题,如缺少加载指示导致重复提交、静默吞掉重定向错误、样式不一致、E2E 测试找不到元素等。
主要能力与约定:表单结构使用 react-hook-form 的 useForm,配合 zodResolver 时不要添加多余泛型;Zod 校验 schema 放在 _lib/schema/ 目录,客户端与服务端共享同一份 schema 作为单一事实来源;UI 使用 @/components/ui/form 等 shadcn/ui 组件;用 useTransition 管理 pending 状态(而非用 useState 管理 loading);用 try/catch 与 isRedirectError 处理重定向错误;用 sonner 的 toast 或 toast.promise 提供用户反馈;用 @/components/ui/alert 展示错误。校验建议 mode: 'onChange' 与 reValidateMode: 'onChange',并给出友好错误消息。可访问性上要求 FormLabel、FormDescription、FormMessage,提交按钮在 pending 时禁用,交互元素添加 data-test 属性。
必要用法:表单组件文件首行必须是 'use client';server action 调用包裹在 startTransition 中;重定向错误判断使用 isRedirectError;成功后可调用 form.reset() 并确保 server action 中调用 revalidatePath。导入规范:toast 来自 'sonner',表单组件来自 '@/components/ui/form'。
限制:面向已建立该套模式的 Next.js/Supabase 代码库,不适用于其它框架或未采用这些约定的项目;.refine() 会改变 ZodObject 类型导致 zodResolver 类型不匹配,需拆分基础 schema 与校验 schema;useEffect 在表单中被视为坏味道,校验应由 schema 驱动。表单字段级示例(Select、Checkbox、Switch、Textarea 等)需另见 Components,未在此提供。平台、费用与价格信息暂未提供。