react-19

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React 19.2 Core Features

React 19.2 核心特性

Agent Workflow (MANDATORY)

Agent 工作流（强制执行）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing React patterns and component structure
fuse-ai-pilot:research-expert - Verify latest React 19.2 docs via Context7/Exa
mcp__context7__query-docs - Check use(), useOptimistic, useActionState, Activity patterns

After implementation, run fuse-ai-pilot:sniper for validation.

在进行任何实现工作之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有React模式和组件结构
fuse-ai-pilot:research-expert - 通过Context7/Exa验证最新的React 19.2文档
mcp__context7__query-docs - 检查use()、useOptimistic、useActionState、Activity的使用模式

实现完成后，运行fuse-ai-pilot:sniper进行验证。

What's New in React 19.2

React 19.2 新特性

New Hooks

新Hooks

Hook	Purpose	Guide
`use()`	Read promises/context in render	`references/new-hooks.md`
`useOptimistic`	Optimistic UI updates	`references/new-hooks.md`
`useActionState`	Form action state management	`references/new-hooks.md`
`useFormStatus`	Form pending state (child components)	`references/new-hooks.md`
`useEffectEvent`	Non-reactive callbacks in effects	`references/new-hooks.md`

→ See

references/new-hooks.md

for detailed usage

Hook	用途	指南
`use()`	在渲染阶段读取Promise/上下文	`references/new-hooks.md`
`useOptimistic`	实现乐观UI更新	`references/new-hooks.md`
`useActionState`	表单动作状态管理	`references/new-hooks.md`
`useFormStatus`	表单加载状态（子组件中使用）	`references/new-hooks.md`
`useEffectEvent`	副作用中的非响应式回调	`references/new-hooks.md`

→ 详细用法请参阅

references/new-hooks.md

Classic Hooks (React 18+)

经典Hooks（React 18+）

State Hooks

状态Hooks

Hook	Purpose	Guide
`useState`	Local component state	`references/use-state.md`

→ For global state, see

react-state

skill

Hook	用途	指南
`useState`	组件本地状态管理	`references/use-state.md`

→ 全局状态管理请参阅

react-state

技能文档

Effect Hooks

副作用Hooks

Hook	Purpose	Guide
`useEffect`	Side effects after paint	`references/use-effect.md`
`useLayoutEffect`	Sync DOM before paint	`references/use-layout-effect.md`

Hook	用途	指南
`useEffect`	渲染完成后执行副作用	`references/use-effect.md`
`useLayoutEffect`	渲染前同步DOM操作	`references/use-layout-effect.md`

Ref Hooks

引用Hooks

Hook	Purpose	Guide
`useRef`	DOM access, mutable values	`references/use-ref.md`
`useImperativeHandle`	Customize ref API	`references/use-imperative-handle.md`

Hook	用途	指南
`useRef`	DOM访问与可变值存储	`references/use-ref.md`
`useImperativeHandle`	自定义Ref API	`references/use-imperative-handle.md`

Performance Hooks (Rare with Compiler)

性能优化Hooks（使用Compiler后基本无需）

Hook	Purpose	Guide
`useMemo`	Memoize expensive values	`references/use-memo.md`
`useCallback`	Memoize functions	`references/use-callback.md`

→ React Compiler handles most memoization automatically

Hook	用途	指南
`useMemo`	缓存计算开销大的值	`references/use-memo.md`
`useCallback`	缓存函数	`references/use-callback.md`

→ React Compiler会自动处理大部分缓存逻辑

Other Hooks

其他Hooks

Hook	Purpose	Guide
`useId`	Unique IDs for accessibility	`references/use-id.md`
`useSyncExternalStore`	External store subscription	`references/use-sync-external-store.md`

Hook	用途	指南
`useId`	生成无障碍访问所需的唯一ID	`references/use-id.md`
`useSyncExternalStore`	外部状态库订阅	`references/use-sync-external-store.md`

Custom Hooks

自定义Hooks

→ See

references/custom-hooks-patterns.md

for patterns → See

references/templates/custom-hooks.md

for implementations

→ 实现模式请参阅

references/custom-hooks-patterns.md

→ 代码实现请参阅

references/templates/custom-hooks.md

Activity Component (19.2)

Activity 组件（19.2版本新增）

Hide/show components while preserving state:

typescript

<Activity mode={isActive ? 'visible' : 'hidden'}>
  <TabContent />
</Activity>

→ See

references/activity-component.md

for patterns

在隐藏/显示组件时保留其状态：

typescript

<Activity mode={isActive ? 'visible' : 'hidden'}>
  <TabContent />
</Activity>

→ 使用模式请参阅

references/activity-component.md

React Compiler (19.1+)

React Compiler（19.1版本及以上）

Automatic memoization - useMemo/useCallback mostly obsolete:

Build-time optimization
No more manual memoization in most cases
2.5× faster interactions reported

→ See

references/react-compiler.md

for details

自动缓存优化 - useMemo/useCallback基本过时：

构建阶段优化
大多数场景下无需手动缓存
据报告交互速度提升2.5倍

→ 详细信息请参阅

references/react-compiler.md

Quick Reference

快速参考

use() Hook

typescript

// Read promise in render (with Suspense)
const data = use(dataPromise)

// Read context conditionally (unique to use())
if (condition) {
  const theme = use(ThemeContext)
}

→ See

references/templates/use-promise.md

typescript

// 在渲染阶段读取Promise（配合Suspense使用）
const data = use(dataPromise)

// 条件式读取上下文（use()独有的特性）
if (condition) {
  const theme = use(ThemeContext)
}

→ 示例请参阅

references/templates/use-promise.md

useOptimistic

typescript

const [optimisticValue, setOptimistic] = useOptimistic(actualValue)
// Update UI immediately, server updates later

→ See

references/templates/optimistic-update.md

typescript

const [optimisticValue, setOptimistic] = useOptimistic(actualValue)
// 立即更新UI，后续同步服务器数据

→ 示例请参阅

references/templates/optimistic-update.md

useActionState

typescript

const [state, action, isPending] = useActionState(asyncFn, initialState)

→ See

references/templates/action-form.md

typescript

const [state, action, isPending] = useActionState(asyncFn, initialState)

→ 示例请参阅

references/templates/action-form.md

useEffectEvent (19.2)

typescript

const onEvent = useEffectEvent(() => {
  // Always has fresh props/state, doesn't trigger re-run
})

useEffect(() => {
  connection.on('event', onEvent)
}, []) // No need to add onEvent to deps

→ See

references/new-hooks.md

typescript

const onEvent = useEffectEvent(() => {
  // 始终获取最新的props/state，不会触发副作用重跑
})

useEffect(() => {
  connection.on('event', onEvent)
}, []) // 无需将onEvent加入依赖数组

→ 详细用法请参阅

references/new-hooks.md

Breaking Changes from 18

从React 18升级的破坏性变更

Change	Migration
`ref` is a prop	Remove `forwardRef` wrapper
`Context` is provider	Use `<Context value={}>` directly
`useFormStatus`	Import from `react-dom`

→ See

references/migration-18-19.md

变更内容	迁移方案
`ref` 作为属性传递	移除 `forwardRef` 包装
`Context` 直接作为提供者	直接使用 `<Context value={}>`
`useFormStatus` 导入路径变更	从 `react-dom` 导入

→ 迁移指南请参阅

references/migration-18-19.md

Best Practices

最佳实践

Data fetching: Use
```
use()
```
+ Suspense, NOT useEffect
Forms: Use Actions + useActionState
Optimistic UI: Use
```
useOptimistic
```
for instant feedback
Tabs/Modals: Use
```
<Activity>
```
to preserve state
Effect events: Use
```
useEffectEvent
```
for non-reactive callbacks
Memoization: Let React Compiler handle it

数据获取：使用
```
use()
```
+ Suspense，而非useEffect
表单处理：使用Actions + useActionState
乐观UI：使用
```
useOptimistic
```
实现即时反馈
标签页/模态框：使用
```
<Activity>
```
组件保留状态
副作用事件：使用
```
useEffectEvent
```
处理非响应式回调
缓存优化：交由React Compiler自动处理

Templates

模板参考

React 19 Patterns

React 19 开发模式

Template	Use Case
`templates/action-form.md`	Form with useActionState
`templates/optimistic-update.md`	useOptimistic pattern
`templates/activity-tabs.md`	Activity component tabs
`templates/use-promise.md`	use() with promises

模板	使用场景
`templates/action-form.md`	基于useActionState的表单实现
`templates/optimistic-update.md`	useOptimistic 实现模式
`templates/activity-tabs.md`	Activity组件实现标签页
`templates/use-promise.md`	use()配合Promise的实现

Classic Hooks Patterns

经典Hooks开发模式

Template	Use Case
`templates/state-patterns.md`	useState patterns
`templates/effect-patterns.md`	useEffect patterns
`templates/ref-patterns.md`	useRef patterns
`templates/custom-hooks.md`	Custom hooks implementations
`templates/external-store.md`	useSyncExternalStore patterns

模板	使用场景
`templates/state-patterns.md`	useState 实现模式
`templates/effect-patterns.md`	useEffect 实现模式
`templates/ref-patterns.md`	useRef 实现模式
`templates/custom-hooks.md`	自定义Hooks实现
`templates/external-store.md`	useSyncExternalStore 实现模式

Performance Patterns

性能优化模式

Template	Use Case
`templates/virtual-list.md`	TanStack Virtual for long lists
`templates/lazy-components.md`	Code splitting and lazy loading
`templates/profiling-devtools.md`	React DevTools Profiler

模板	使用场景
`templates/virtual-list.md`	使用TanStack Virtual实现长列表
`templates/lazy-components.md`	代码分割与懒加载
`templates/profiling-devtools.md`	React DevTools 性能分析

Performance

性能优化建议

Virtualization

虚拟列表渲染

Render only visible items for large lists (100+ items). → See

references/virtualization.md

对于大型列表（100条以上数据），仅渲染可见区域的元素。 → 详细指南请参阅

references/virtualization.md

Lazy Loading

懒加载

Code split routes and heavy components for smaller bundles. → See

references/lazy-loading.md

对路由和重型组件进行代码分割，减小打包体积。 → 详细指南请参阅

references/lazy-loading.md

Profiling

性能分析

Measure render performance with DevTools Profiler. → See

references/profiling.md

Note: With React Compiler (19.1+), manual memo/useMemo/useCallback optimizations are mostly obsolete. Profile first to verify if optimization is needed.

使用DevTools Profiler测量渲染性能。 → 详细指南请参阅

references/profiling.md

注意：在使用React Compiler（19.1+）后，手动使用useMemo/useCallback进行缓存优化的场景基本消失。请先进行性能分析，再决定是否需要优化。

Forbidden (Outdated Patterns)

禁用（过时模式）

❌
```
useEffect
```
for data fetching → use
```
use()
```
+ Suspense
❌
```
forwardRef
```
→ use
```
ref
```
as prop
❌
```
<Context.Provider>
```
→ use
```
<Context value={}>
```
❌ Manual useMemo/useCallback everywhere → let Compiler handle it
❌ Conditional rendering for state preservation → use
```
<Activity>
```

❌ 使用
```
useEffect
```
进行数据获取 → 改用
```
use()
```
+ Suspense
❌ 使用
```
forwardRef
```
→ 直接将
```
ref
```
作为属性传递
❌ 使用
```
<Context.Provider>
```
→ 直接使用
```
<Context value={}>
```
❌ 到处手动使用useMemo/useCallback → 交由Compiler自动处理
❌ 使用条件渲染保留组件状态 → 改用
```
<Activity>
```
组件