typescript-react-patterns

TypeScript React 模式

使用 TypeScript 编写类型安全的 React。包含 7 个类别中的 33 条规则，涵盖组件类型、Hook、事件处理、引用、泛型、上下文和工具类型。

元数据

• 版本： 2.0.0
• 规则数： 7 个类别中的 33 条规则
• 许可证： MIT

适用场景

在以下情况参考这些指南：

• 为 React 组件的属性添加类型
• 使用 TypeScript 创建自定义 Hook
• 使用正确的类型处理事件
• 使用引用（DOM、可变值、命令式操作）
• 构建泛型、可复用的组件
• 设置类型化的 Context 提供程序
• 修复 React 代码中的 TypeScript 错误

按优先级划分的规则类别

优先级	类别	影响	前缀
1	组件类型	严重	comp-
2	Hook 类型	严重	hook-
3	事件处理	高	event-
4	引用类型	高	ref-
5	泛型组件	中	generic-
6	Context 与状态	中	ctx-
7	工具类型	低	util-

快速参考

1. 组件类型（严重）

• comp-props-interface - 属性使用 interface，联合类型使用 type
• comp-children-types - 正确的 children 类型（ReactNode、ReactElement）
• comp-default-props - 使用解构默认值设置默认属性
• comp-forward-ref - 为 forwardRef 组件添加类型
• comp-polymorphic - 多态 "as" 属性的类型
• comp-fc-vs-function - 函数声明与 React.FC
• comp-display-name - 用于调试的显示名称
• comp-rest-props - 使用正确类型展开剩余属性

2. Hook 类型（严重）

• hook-usestate - 为 useState 指定正确的泛型类型
• hook-useref - 使用 useRef 引用 DOM 元素和可变值
• hook-use-reducer - 使用可辨识联合类型的 action 编写 useReducer
• hook-use-callback - 为 useCallback 指定参数类型
• hook-use-memo - 为 useMemo 指定返回值类型
• hook-use-context - 为 useContext 添加 null 检查
• hook-custom-hooks - 自定义 Hook 的返回类型
• hook-generic-hooks - 泛型自定义 Hook

3. 事件处理（高）

• event-handler-types - 事件处理器的类型模式
• event-click-handler - 点击事件的类型
• event-form - 表单事件处理（提交、更改、选择）
• event-keyboard - 键盘事件类型

4. 引用类型（高）

• ref-dom-elements - 使用 useRef 引用特定 HTML 元素类型
• ref-callback - 用于测量 DOM 的回调引用模式
• ref-imperative-handle - 为 useImperativeHandle 添加类型

5. 泛型组件（中）

• generic-list - 泛型列表组件
• generic-select - 泛型选择器/下拉菜单
• generic-table - 使用类型化列的泛型表格
• generic-constraints - 使用 extends 添加泛型约束

6. Context 与状态（中）

• ctx-create - 创建类型化 Context
• ctx-provider - 使用 null 检查 Hook 的 Provider 模式
• ctx-reducer - 在 Context 中使用 useReducer

7. 工具类型（低）

• util-component-props - 使用 ComponentPropsWithoutRef 指定 HTML 属性
• util-pick-omit - 使用 Pick、Omit、Partial 派生属性类型
• util-discriminated-unions - 使用可辨识联合类型构建状态机

核心模式

组件属性

interface ButtonProps {
  variant: 'primary' | 'secondary' | 'danger'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
  onClick?: () => void
}

function Button({ variant, size = 'md', children, onClick }: ButtonProps) {
  return (
    <button className={`btn-${variant} btn-${size}`} onClick={onClick}>
      {children}
    </button>
  )
}

带 null 检查的类型化 Context

interface AuthContextType {
  user: User | null
  login: (credentials: Credentials) => Promise<void>
  logout: () => void
}

const AuthContext = createContext<AuthContextType | null>(null)

function useAuth() {
  const context = useContext(AuthContext)
  if (!context) throw new Error('useAuth must be used within AuthProvider')
  return context
}

泛型组件

interface ListProps<T> {
  items: T[]
  renderItem: (item: T) => React.ReactNode
  keyExtractor: (item: T) => string
}

function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
  return <ul>{items.map(item => <li key={keyExtractor(item)}>{renderItem(item)}</li>)}</ul>
}

使用方法

阅读各条规则文件，了解详细说明：

rules/comp-props-interface.md
rules/hook-usestate.md
rules/event-form.md
rules/ref-dom-elements.md
rules/util-discriminated-unions.md

参考资料

• React TypeScript 速查表
• React + TypeScript 指南
• TypeScript 手册

完整编译文档

完整指南（包含所有展开的规则）：AGENTS.md