Agent Skills
返回列表
💻

React TypeScript 类型安全开发

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 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 写显式类型;DOM useRef 处理 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 工程师