react-19

涵盖 React 19.3 的 Hooks 和功能：用于在渲染期间读取 Promise/Context 的 `use()`、用于即时更新 UI 的 `useOptimistic`、用于表单 Action 状态的 `useActionState`、用于子组件待处理状态的 `useFormStatus`、用于非响应式 Effect 回调的 `useEffectEvent`、可在保留状态的同时隐藏/显示 UI 的 `Activity` 组件、`` + `addTransitionType` 动画、Fragment refs 和 `use(browser())` 仅浏览器端渲染（19.3 新增），以及 React Compiler 的自动记忆化（使手动使用 `useMemo`/`useCallback` 基本过时）。

还介绍所有经典 Hooks（useState、useEffect、useLayoutEffect、useRef、useImperativeHandle、useMemo、useCallback、useId、useSyncExternalStore），以及 React 18→19 的破坏性变更（将 ref 作为 prop，而不是使用 forwardRef；使用 <Context value={}>，而不是 <Context.Provider>）。这是 React Hooks/功能的核心技能；全局状态请参阅 react-state，表单请参阅 react-forms，SOLID 架构规则请参阅 solid-react。

React 19.3 核心功能

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 调用一次，并指定 name：

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

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

---

React 19.3 新增内容

19.3 中稳定可用（react/react-dom 19.3.0，2026-09-09；@types/react 19.3 需要 TypeScript ≥ 5.6）：

API	用途	指南
<ViewTransition>	通过浏览器 View Transition API 为进入/退出/更新/共享添加动画	references/suspense-patterns.md
addTransitionType(type)	为 Transition 添加标记，以选择不同的动画	references/suspense-patterns.md
<Fragment ref>	无需包装 <div> 即可使用 FragmentInstance（事件、焦点、观察器）	references/ref-as-prop.md
use(browser(reason?))（react-dom）	仅浏览器端渲染：在服务端挂起，并在 HTML 中显示 Suspense 回退内容	references/new-hooks.md

行为变更：Transitions 不再相互纠缠，StrictMode 在 hydration 期间会双重调用 Effect，条件式 use() 解除阻塞时会在 DEV 中发出警告 → references/migration-18-19.md。

RSC 安全性： react-server-dom-* 必须为 ≥ 19.2.4（CVE-2025-55182 RCE 及后续 DoS CVE）；建议使用 ≥ 19.2.7 或 19.3.0。

新增 Hooks（19.0–19.2）

Hook	用途	指南
use()	在渲染期间读取 Promise/Context	references/new-hooks.md
useOptimistic	乐观 UI 更新	references/new-hooks.md
useActionState	表单 Action 状态管理	references/new-hooks.md
useFormStatus	表单待处理状态（子组件）	references/new-hooks.md
useEffectEvent	Effect 中的非响应式回调	references/new-hooks.md

→ 详细用法请参阅 references/new-hooks.md

---

经典 Hooks（React 18+）

状态 Hooks

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

→ 全局状态请参阅 react-state 技能

Effect Hooks

Hook	用途	指南
useEffect	绘制后执行副作用	references/use-effect.md
useLayoutEffect	绘制前同步 DOM	references/use-layout-effect.md

Ref Hooks

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

性能 Hook（使用 Compiler 后较少需要）

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

→ React Compiler 会自动处理大多数缓存

其他 Hook

Hook	用途	指南
useId	用于无障碍功能的唯一 ID	references/use-id.md
useSyncExternalStore	订阅外部存储	references/use-sync-external-store.md

自定义 Hook

→ 模式请参阅 references/custom-hooks-patterns.md → 实现请参阅 references/templates/custom-hooks.md

---

Activity 组件（自 19.2 起稳定）

隐藏/显示组件，同时保留状态：

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

→ 模式请参阅 references/activity-component.md

React Compiler（1.0 稳定版，2025 年 10 月 — React 17+）

自动缓存——useMemo/useCallback 大多已过时：

• 构建时优化
• 大多数情况下无需再手动缓存
• 据报告，交互速度提升 2.5×

→ 详情请参阅 references/react-compiler.md

---

快速参考

use() Hook

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

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

→ 请参阅 references/templates/use-promise.md

useOptimistic

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

→ 请参阅 references/templates/optimistic-update.md

useActionState

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

→ 请参阅 references/templates/action-form.md

useEffectEvent（自 19.2 起稳定）

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

→ 请参阅 references/new-hooks.md

---

从 18 迁移时的破坏性变更

变更	迁移方式
ref 是一个 prop	移除 forwardRef 包装器
Context 是 provider	直接使用 <Context value={}>
useFormStatus	从 react-dom 导入

→ 请参阅 references/migration-18-19.md

---

最佳实践

1. 数据获取：使用 use() + Suspense，而非 useEffect
2. 表单：使用 Actions + useActionState
3. 乐观 UI：使用 useOptimistic 实现即时反馈
4. 标签页/模态框：使用 <Activity> 保留状态
5. Effect 事件：使用 useEffectEvent 编写非响应式回调
6. 缓存：交由 React Compiler 处理

---

模板

React 19 模式

模板	使用场景
templates/action-form.md	使用 useActionState 的表单
templates/optimistic-update.md	useOptimistic 模式
templates/activity-tabs.md	Activity 组件标签页
templates/use-promise.md	在 Promise 中使用 use()

经典 Hook 模式

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

性能模式

模板	使用场景
templates/virtual-list.md	使用 TanStack Virtual 处理长列表
templates/lazy-components.md	代码拆分和延迟加载
templates/profiling-devtools.md	React DevTools Profiler

---

性能

虚拟化

对于大型列表（100+ 项），仅渲染可见项。 → 请参阅 references/virtualization.md

延迟加载

拆分路由和大型组件的代码，以减小打包体积。 → 请参阅 references/lazy-loading.md

性能分析

使用 DevTools Profiler 衡量渲染性能。 → 请参阅 references/profiling.md

注意： 使用 React Compiler（1.0+）后，手动进行 memo/useMemo/useCallback 优化大多已过时。请先进行性能分析，确认是否需要优化。

---

禁止使用（过时模式）

• ❌ 使用 useEffect 获取数据 → 改用 use() + Suspense
• ❌ 使用 forwardRef → 改用 ref 作为 prop
• ❌ 使用 <Context.Provider> → 改用 <Context value={}>
• ❌ 到处手动使用 useMemo/useCallback → 交由 Compiler 处理
• ❌ 使用条件渲染保留状态 → 改用 <Activity>