用途
nextjs-form 用于构建生产级的 Next.js 16 表单,核心目标是把 Server Actions、渐进增强、全面校验和无障碍访问整合到一套可复用的实现流程中。当用户需要创建或改造 Next.js 表单时,可依据该技能给出的步骤与规范进行开发。
主要能力
- 共享 Zod schema:为表单校验定义 Zod schema,同一份 schema 同时用于客户端(改善用户体验)和服务端(保障安全)校验;schema 可与表单组件放在一起,或放入特定功能的 schema 文件;使用
z.infer<typeof schema>从 schema 推导 TypeScript 类型。 - Server Action 实现:使用
"use server"指令创建 Server Action,借助共享 Zod schema 提取并校验 FormData,返回带有成功/错误状态的结果对象(不直接抛出异常),使用revalidatePath/revalidateTag进行缓存失效,支持提交成功后重定向,并确保 Server Action 在渐进增强下可用。 - 表单组件构建:使用 React 19 的
useActionState管理表单状态与错误展示,使用useFormStatus处理提交中的状态,处理初始状态与来自 Server Action 的状态更新,展示字段级与表单级校验错误,在提交成功后正确重置表单,并在合适场景使用useOptimistic提供即时反馈。 - 渐进增强:确保表单在未启用 JavaScript 时仍可工作,使用
next/form增强表单行为,实现带 pending 指示的加载状态,并为 JavaScript 失效场景提供降级体验。 - 无障碍实现:添加正确的 ARIA 标签、描述与错误关联,支持完整的键盘导航,提供清晰的焦点指示并合理管理焦点,使用语义化 HTML 表单元素,确保屏幕阅读器能够导航并理解表单结构与错误,使用 ARIA live 区域播报加载状态,遵循 WCAG 2.1 AA 指南。
- 错误处理:为校验失败提供清晰、可操作的错误信息,优雅处理服务端错误,在 Server Action 中使用恰当的 try/catch,支持带正确 ARIA 属性的字段级错误展示,并建立一致的错误信息模式。
- 编码规范:遵循 TypeScript 规则(接口、类型推导、RORO 模式),使用 shadcn/ui 的 Form 组件,采用移动优先的响应式设计,并遵守 Biome + ESLint 的 lint 规则。
- 验证与测试:运行
pnpm lint:fix,在启用和禁用 JavaScript 两种情况下测试表单提交,验证键盘导航与屏幕阅读器兼容性,测试错误处理与校验信息,并确认缓存失效正常工作。
使用方式
该技能以流程化指引的形式给出实现步骤:先定义共享 Zod schema,再实现 Server Action,然后构建表单组件,接着补充渐进增强与无障碍支持,最后进行错误处理、编码规范检查与验证测试。具体安装命令、调用方式与集成细节在现有资料中暂未提供。
适用场景
适用于需要在 Next.js 16 中构建生产级表单的场景,尤其是要求服务端校验、渐进增强、无障碍访问与一致错误处理的项目。
限制
现有资料未提供该技能的安装命令、依赖版本要求、收费或价格信息、平台支持范围以及实际效果数据,这些内容暂未提供。