modern-best-practice-react-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing React Components

编写React组件

We're using modern React (19+) and we're following common best practices focused on clarity, correctness, and maintainability.

我们使用现代React（19+），并遵循以清晰性、正确性和可维护性为核心的通用最佳实践。

Component Structure & Style

组件结构与风格

PREFER small, focused components with a single responsibility
PREFER named
```
function
```
components over arrow functions
- Exception: anonymous callbacks, inline render props, and closures
PREFER explicit return types and props typing (TypeScript) where applicable
Keep components flat and readable; avoid deeply nested JSX
Group related logic together (event handlers, derived values, helpers)

优先选择职责单一的小型专注组件
优先选择具名
```
function
```
组件而非箭头函数
- 例外：匿名回调、内联渲染属性和闭包
优先选择在适用场景下使用显式返回类型和属性类型定义（TypeScript）
保持组件扁平且易读；避免深度嵌套的JSX
将相关逻辑分组（事件处理程序、派生值、辅助函数）

State Management

状态管理

AVOID
```
useEffect()
```
- See the "You Might Not Need An Effect" guide for detailed guidance
- PREFER deriving values during render instead of synchronizing state
- Fetch data via TanStack Query (
```
@tanstack/react-query
```
  )
AVOID unnecessary
```
useState()
```
or
```
useReducer()
```
usage
- Derive state from props or other state when possible
- Localize state to the lowest possible component
DO NOT mirror props in state unless absolutely necessary
Prefer controlled components over syncing uncontrolled state

避免使用
```
useEffect()
```
- 详见“你可能不需要Effect”指南获取详细指导
- 优先选择在渲染期间派生值而非同步状态
- 通过TanStack Query（
```
@tanstack/react-query
```
  ）获取数据
避免不必要地使用
```
useState()
```
或
```
useReducer()
```
- 尽可能从属性或其他状态派生状态
- 将状态本地化到尽可能底层的组件
除非绝对必要，否则不要在状态中镜像属性
优先选择受控组件而非同步非受控状态

Rendering & Derivation

渲染与派生

PREFER computing derived values inline or via helper functions
Use
```
useMemo()
```
sparingly and only for proven performance issues
AVOID premature optimization
Keep render logic deterministic and free of side effects

优先选择内联计算派生值或通过辅助函数实现
谨慎使用
```
useMemo()
```
，仅在已证实存在性能问题时使用
避免过早优化
保持渲染逻辑确定性且无副作用

Event Handling

事件处理

AVOID in-line event handlers in JSX

PREFER:

tsx

function handleClick() {
  // ...
}

<button onClick={handleClick} />;

Over:

tsx

<button
  onClick={() => {
    /* ... */
  }}
/>

Name handlers clearly (
```
handleSubmit
```
,
```
handleChange
```
,
```
handleClose
```
)
Keep handlers small; extract complex logic into helpers

避免在JSX中使用内联事件处理程序

优先选择：

tsx

function handleClick() {
  // ...
}

<button onClick={handleClick} />;

而非：

tsx

<button
  onClick={() => {
    /* ... */
  }}
/>

清晰命名处理程序（
```
handleSubmit
```
、
```
handleChange
```
、
```
handleClose
```
）
保持处理程序简洁；将复杂逻辑提取到辅助函数中

Effects, Data, and Side Effects

副作用、数据与异步操作

AVOID effects for:
- Derived state
- Data transformations
- Event-based logic that can live in handlers
If side effects are unavoidable, keep them minimal, isolated, and well-documented
Prefer framework-level or external abstractions (routers, data libraries) over raw effects

避免将Effect用于以下场景：
- 派生状态
- 数据转换
- 可在处理程序中实现的基于事件的逻辑
如果副作用不可避免，应尽量精简、隔离并做好充分文档
优先选择框架级或外部抽象（路由、数据库）而非原生Effect

Props & Composition

属性与组合

PREFER composition over configuration
AVOID excessive boolean props; prefer expressive APIs
Use
```
children
```
intentionally and document expected structure
Keep prop names semantic and predictable

优先选择组合而非配置
避免过多布尔属性；优先选择表达性强的API
有意使用
```
children
```
并记录预期结构
保持属性名称语义化且可预测

Performance & Stability

性能与稳定性

PREFER stable references only when required (not by default)
AVOID unnecessary memoization (
```
memo
```
,
```
useCallback
```
) unless absolutely required
Keep keys stable and meaningful when rendering lists

仅在必要时使用稳定引用（非默认操作）
避免不必要的记忆化（
```
memo
```
、
```
useCallback
```
），除非绝对必要
渲染列表时使用稳定且有意义的key

General Principles

通用原则

Write code for humans first, compilers second
Prefer explicitness over cleverness
Optimize for readability and long-term maintenance
If a pattern feels complex, reconsider the component boundary

代码编写优先考虑人类可读性，其次是编译器需求
优先选择显式而非技巧性写法
以可读性和长期可维护性为优化目标
如果某种模式过于复杂，重新审视组件边界