react-best-practices

React 最佳实践

配合 TypeScript 使用

使用 React 时，始终同时加载此技能和 typescript-best-practices。TypeScript 模式（类型优先开发、可辨识联合、Zod 验证）同样适用于 React 代码。

核心原则：Effect 是逃生出口

Effect 让你能够“走出” React，与外部系统同步。大多数组件逻辑都不应使用 Effect。 编写 Effect 前，先问自己：“有没有办法不使用 Effect 来实现？”

决策树

1. 需要响应用户交互？ 使用事件处理程序
2. 需要根据 props/state 计算值？ 在渲染期间计算
3. 需要缓存开销较大的计算？ 使用 useMemo
4. 需要在 prop 变化时重置 state？ 使用 key prop
5. 需要与外部系统同步？ 使用带清理逻辑的 Effect
6. 需要在 Effect 中编写非响应式代码？ 使用 useEffectEvent
7. 需要不会触发渲染的可变值？ 使用 ref

何时使用 Effects

用于与外部系统同步：浏览器 API（WebSocket、IntersectionObserver）、第三方非 React 库、window/document 事件监听器、非 React DOM 元素（视频、地图）。

何时不使用 Effects

• 派生 state——在渲染期间计算
• 开销较大的计算——使用 useMemo
• 在 prop 变化时重置 state——使用 key prop
• 响应用户事件——使用事件处理程序
• 通知父组件 state 变化——在同一个事件处理程序中同时更新两者
• 一连串的 effects——计算派生 state，并在一个事件处理程序中完成更新

Refs

• 用于不影响渲染的值（计时器 ID、DOM 节点引用）
• 渲染期间绝不读取或写入 ref.current；仅在事件处理程序和 effects 中操作
• 对动态列表使用 ref 回调（不要在循环中使用 useRef）
• 使用 useImperativeHandle 限制父组件可访问的内容

自定义 Hooks

• 共享逻辑，而非 state——每次调用都会获得独立的 state 实例
• 只有在实际调用其他 hooks 时才命名为 useXxx；否则使用普通函数
• 避免使用生命周期 hooks（useMount、useEffectOnce）——直接使用 useEffect，以便 linter 检查缺失的依赖项
• 专注于单一、具体的使用场景

组件模式

• 受控组件：state 由父组件管理；非受控组件：state 由组件自身管理
• 优先使用 children 组合，而不是逐层传递 props
• 将切换大型组件树的布尔 props（isEditing、isThread、hideAttachments）视为组合设计异味；对于不同使用场景，优先使用单独组合的组件
• 对于复杂且可复用的 UI，优先使用由 provider 作用域内的 state/actions 驱动的复合组件，而不是带有许多可选 props 的单体组件
• 当 Context 定义了由后代组件使用的本地接口时，既可用于有作用域的组件族，也可用于真正的全局 state
• 对于 UI 差异，直接渲染 JSX；除非配置确实属于领域数据，否则避免使用基于配置数组的迷你框架
• 当同级或外部控件需要访问相同的 state/actions 时，提升 provider 边界
• 当需要在 state 更新后同步读取 DOM 时，使用 flushSync

代码示例和详细模式请参阅 react-patterns.md。