React TypeScript 类型安全开发
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/softaworks-agent-toolkit-react-dev。
技能介绍
要解决什么问题
在 React 项目里接 TypeScript,最容易踩坑的不是「会不会写类型」,而是重构时类型跟不住:事件处理写成 any、子组件 props 用联合类型却不做判别、useRef 对 DOM 漏掉 null、React 19 里还在用 forwardRef 和 useFormState。路由参数和 search 若没有编译期约束,改路径或改 query 只能在运行时报错。
本技能围绕「类型安全的 React」:在编译期把组件、Hooks、表单与路由的常见模式钉死,让改代码时有把握,而不是靠运行时试错。
技能覆盖的核心能力
- 组件与 Props:用
ComponentPropsWithoutRef扩展原生元素;子节点用ReactNode;变体 props 用判别联合;泛型组件从 props 推断类型,调用处不必手填注解。 - Hooks:
useState对联合/null 写显式类型;DOMuseRef处理null;useReducer动作用判别联合;自定义 Hook 用as const返回元组;useContext做空值守卫。 - 事件与表单:使用
MouseEvent、ChangeEvent等具体事件类型;表单侧在 React 19 用useActionState(替代已废弃的useFormState)。 - React 19:
ref作为 prop(不再依赖forwardRef);use()解包 Promise/Context(传给use()的 Promise 不要在传递前await);Server Components 可async取数,Server Actions 用'use server';客户端与同文件 Server/Client 混写要避免。 - 路由:TanStack Router(含 Zod 校验的编译期类型安全)与 React Router v7 Framework Mode 的类型生成;详见技能内
tanstack-router.md、react-router.md。 - 延伸阅读:
hooks.md、event-handlers.md、react-19-patterns.md、generic-components.md、server-components.md分主题展开 Table/Select/List/Modal、流式与错误边界等。
适用边界与注意点
- 适用:已在用或准备用 React + TypeScript 的组件库、业务前端、需要迁移 React 19 的存量项目。
- 不适用:纯 Node/脚本里的 TypeScript(非 React)、或坚持用 JavaScript 写 React 且不接 TS 的团队。
- React 19 破坏性变更需要按迁移清单处理;Server 与 Client 组件职责要分清,不要把两种组件堆在同一文件里随心混用。
使用场景
- 存量 React 18 项目要升到 React 19,需要把 forwardRef、useFormState 等用法对照技能里的迁移清单逐项改掉
- 设计系统里要做 Table、Select、Modal 等泛型组件,希望调用方 props 能自动推断列 key 和 render 回调类型
- TanStack Router 或 React Router v7 新页面上线前,要把路由 params、search 和 loader/action 的类型生成规则对齐团队规范
- 表单提交改用 Server Actions,要在客户端用 useActionState 接住 pending/错误状态且事件处理不用 any
适合人员
- 维护中大型 React 组件库、每周都要改公共 API 且害怕破坏下游类型推断的前端工程师
- 负责 React 19 升级里程碑的技术负责人,需要统一 ref-as-prop、use() 与 Server/Client 边界写法
- 用 TanStack Router 做多级嵌套路由与 Zod 校验的产品前端,追求改 URL 结构时编译期就能报错
- 在 App Router 或混合架构里写 async Server Component 与 Server Actions 的全栈/React 工程师