Back to Details

react-19

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to Use

适用场景

Triggers: When building React components, using hooks, working with forms, or server/client components.
Load when: writing React components, using hooks, handling forms, working with Server/Client components, or migrating from React 18.
触发场景：构建 React 组件、使用 Hooks、处理表单或开发服务端/客户端组件时。
加载时机：编写 React 组件、使用 Hooks、处理表单、开发 Server/Client 组件，或从 React 18 迁移时。

Critical Patterns

核心模式

Pattern 1: React Compiler — No manual memoization

模式1：React Compiler — 无需手动记忆化

typescript
// ✅ React Compiler optimizes this automatically
function ExpensiveComponent({ data }: { data: number[] }) {
  const result = data.reduce((acc, n) => acc + n, 0); // Compiler memoizes it
  return <div>{result}</div>;
}

// ❌ Unnecessary in React 19 with Compiler enabled
function ExpensiveComponent({ data }: { data: number[] }) {
  const result = useMemo(() => data.reduce((acc, n) => acc + n, 0), [data]);
  return <div>{result}</div>;
}
typescript
// ✅ React Compiler 会自动优化这段代码
function ExpensiveComponent({ data }: { data: number[] }) {
  const result = data.reduce((acc, n) => acc + n, 0); // Compiler 会自动记忆化该计算
  return <div>{result}</div>;
}

// ❌ 在启用 Compiler 的 React 19 中无需这么做
function ExpensiveComponent({ data }: { data: number[] }) {
  const result = useMemo(() => data.reduce((acc, n) => acc + n, 0), [data]);
  return <div>{result}</div>;
}

Pattern 2: Named Imports

模式2：命名导入

typescript
// ✅ Always named imports
import { useState, useEffect, use, useActionState } from 'react';
import { Suspense } from 'react';

// ❌ Never default or namespace imports
import React from 'react';
import * as React from 'react';
typescript
// ✅ 始终使用命名导入
import { useState, useEffect, use, useActionState } from 'react';
import { Suspense } from 'react';

// ❌ 不要使用默认导入或命名空间导入
import React from 'react';
import * as React from 'react';

Pattern 3: Server Components by default

模式3：默认使用 Server Components

typescript
// ✅ Server Component (default — no directive needed)
async function UserProfile({ userId }: { userId: string }) {
  const user = await db.users.findById(userId); // Direct DB access
  return <div>{user.name}</div>;
}

// ✅ Client Component — only when you need interactivity
'use client';
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}
typescript
// ✅ Server Component（默认无需指令）
async function UserProfile({ userId }: { userId: string }) {
  const user = await db.users.findById(userId); // 直接访问数据库
  return <div>{user.name}</div>;
}

// ✅ Client Component — 仅在需要交互性时使用
'use client';
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

Code Examples

代码示例

use() hook — Promises and conditional Context

use() hook — 处理 Promise 和条件上下文

typescript
'use client';
import { use, Suspense } from 'react';

// Read promise in render
function UserData({ promise }: { promise: Promise<User> }) {
  const user = use(promise); // Suspends until resolved
  return <div>{user.name}</div>;
}

// Usage with Suspense
function App() {
  const userPromise = fetchUser(userId);
  return (
    <Suspense fallback={<Skeleton />}>
      <UserData promise={userPromise} />
    </Suspense>
  );
}

// Conditional context (impossible with useContext)
function ConditionalTheme({ show }: { show: boolean }) {
  if (!show) return null;
  const theme = use(ThemeContext); // ✅ conditional usage OK
  return <div style={{ color: theme.primary }}>themed</div>;
}
typescript
'use client';
import { use, Suspense } from 'react';

// 在渲染中读取 promise
function UserData({ promise }: { promise: Promise<User> }) {
  const user = use(promise); // 会挂起直到 promise 解析完成
  return <div>{user.name}</div>;
}

// 搭配 Suspense 使用
function App() {
  const userPromise = fetchUser(userId);
  return (
    <Suspense fallback={<Skeleton />}>
      <UserData promise={userPromise} />
    </Suspense>
  );
}

// 条件上下文（useContext 无法实现）
function ConditionalTheme({ show }: { show: boolean }) {
  if (!show) return null;
  const theme = use(ThemeContext); // ✅ 条件使用是允许的
  return <div style={{ color: theme.primary }}>主题化内容</div>;
}

Server Actions with useActionState

搭配 useActionState 的 Server Actions

typescript
'use server';
async function createUser(prevState: State, formData: FormData) {
  const name = formData.get('name') as string;
  if (!name) return { error: 'Name required' };
  await db.users.create({ name });
  revalidatePath('/users');
  return { success: true };
}

// Client Component
'use client';
import { useActionState } from 'react';

function CreateUserForm() {
  const [state, action, isPending] = useActionState(createUser, null);
  return (
    <form action={action}>
      <input name="name" />
      <button disabled={isPending}>
        {isPending ? 'Creating...' : 'Create'}
      </button>
      {state?.error && <p>{state.error}</p>}
    </form>
  );
}
typescript
'use server';
async function createUser(prevState: State, formData: FormData) {
  const name = formData.get('name') as string;
  if (!name) return { error: '请输入名称' };
  await db.users.create({ name });
  revalidatePath('/users');
  return { success: true };
}

// Client Component
'use client';
import { useActionState } from 'react';

function CreateUserForm() {
  const [state, action, isPending] = useActionState(createUser, null);
  return (
    <form action={action}>
      <input name="name" />
      <button disabled={isPending}>
        {isPending ? '创建中...' : '创建'}
      </button>
      {state?.error && <p>{state.error}</p>}
    </form>
  );
}

ref as prop (without forwardRef)

将 ref 作为 props 传递（无需 forwardRef）

typescript
// ✅ React 19 — ref is a standard prop
function Input({ ref, ...props }: React.InputHTMLAttributes<HTMLInputElement> & {
  ref?: React.Ref<HTMLInputElement>
}) {
  return <input ref={ref} {...props} />;
}

// ❌ No longer needed
const Input = forwardRef<HTMLInputElement, Props>((props, ref) => (
  <input ref={ref} {...props} />
));
typescript
// ✅ React 19 — ref 是标准 props
function Input({ ref, ...props }: React.InputHTMLAttributes<HTMLInputElement> & {
  ref?: React.Ref<HTMLInputElement>
}) {
  return <input ref={ref} {...props} />;
}

// ❌ 不再需要这种写法
const Input = forwardRef<HTMLInputElement, Props>((props, ref) => (
  <input ref={ref} {...props} />
));

Parallel Data Fetching

并行数据获取

typescript
// ✅ Server Component with parallel fetching
async function Dashboard() {
  const [user, posts, stats] = await Promise.all([
    fetchUser(),
    fetchPosts(),
    fetchStats(),
  ]);

  return (
    <div>
      <UserCard user={user} />
      <PostList posts={posts} />
      <StatsPanel stats={stats} />
    </div>
  );
}
typescript
// ✅ 支持并行获取的 Server Component
async function Dashboard() {
  const [user, posts, stats] = await Promise.all([
    fetchUser(),
    fetchPosts(),
    fetchStats(),
  ]);

  return (
    <div>
      <UserCard user={user} />
      <PostList posts={posts} />
      <StatsPanel stats={stats} />
    </div>
  );
}

Anti-Patterns

反模式

❌ Unnecessary useMemo/useCallback (with Compiler)

❌ 在启用 Compiler 时使用不必要的 useMemo/useCallback

typescript
// ❌ Redundant with React Compiler
const value = useMemo(() => compute(data), [data]);
const handler = useCallback(() => doThing(id), [id]);

// ✅ Simple and direct
const value = compute(data);
const handler = () => doThing(id);
typescript
// ❌ React Compiler 已处理，此写法冗余
const value = useMemo(() => compute(data), [data]);
const handler = useCallback(() => doThing(id), [id]);

// ✅ 简洁直接的写法
const value = compute(data);
const handler = () => doThing(id);

❌ Excessive 'use client'

❌ 过度使用 'use client'

typescript
// ❌ Makes the entire tree client-side
'use client';
export default function Page() { /* ... */ }

// ✅ Only the interactive component
// page.tsx (Server Component)
export default function Page() {
  return (
    <div>
      <StaticContent />
      <InteractiveWidget /> {/* 'use client' only here */}
    </div>
  );
}
typescript
// ❌ 会让整个组件树变为客户端组件
'use client';
export default function Page() { /* ... */ }

// ✅ 仅在交互组件上使用
// page.tsx（Server Component）
export default function Page() {
  return (
    <div>
      <StaticContent />
      <InteractiveWidget /> {/* 仅在此处使用 'use client' */}
    </div>
  );
}

Quick Reference

速查表

FeatureReact 18React 19
MemoizationManual useMemo/useCallbackAutomatic (Compiler)
PromisesuseEffect + useStateuse() hook
FormsonSubmit handlerServer Actions + useActionState
Refs in componentsforwardRefref as prop
Conditional context❌ Not possible✅ use()
特性React 18React 19
记忆化手动使用 useMemo/useCallback自动完成（Compiler）
Promise 处理useEffect + useStateuse() hook
表单处理onSubmit 处理器Server Actions + useActionState
组件中的 RefsforwardRef将 ref 作为 props 传递
条件上下文❌ 无法实现✅ 使用 use()

Rules

规则

  • Do not add 
    useMemo
    or 
    useCallback
    when React Compiler is active — the compiler handles memoization automatically and manual wrapping is redundant
  • 'use client'
    must be applied at the lowest possible component in the tree; never mark a page or layout as a Client Component
  • forwardRef
    is no longer needed — pass 
    ref
    as a regular prop; using 
    forwardRef
    in new React 19 code is unnecessary legacy syntax
  • The 
    use()
    hook can be called conditionally (unlike all other hooks); this is intentional and must be used instead of conditional 
    useContext
    workarounds
  • Server Actions must use 
    useActionState
    for form state management; managing form submission state manually with 
    useState
    + 
    useEffect
    is the old pattern
  • 当 React Compiler 启用时，不要添加 
    useMemo
    或 
    useCallback
    —— Compiler 会自动处理记忆化，手动包裹属于冗余写法
  • 'use client'
    必须应用在组件树中尽可能底层的组件上；绝不要将页面或布局标记为 Client Component
  • forwardRef
    不再需要 —— 将 
    ref
    作为常规 props 传递；在新的 React 19 代码中使用 
    forwardRef
    属于不必要的遗留语法
  • use()
    hook 可以被条件调用（与其他所有 Hooks 不同）；这是有意设计的，必须用它替代条件使用 
    useContext
    的变通方案
  • Server Actions 必须使用 
    useActionState
    进行表单状态管理；使用 
    useState
    + 
    useEffect
    手动管理表单提交状态是旧模式