docs-voice

React 文档语气与风格

通用规则

• 提及 React 概念时，在标题或将其作为独立概念时使用首字母大写：
  • 核心概念：Hook、Effect、State、Context、Ref、Component、Fragment
  • 并发功能：Transition、Action、Suspense
  • 服务端：Server Component、Client Component、Server Function、Server Action
  • 模式：Error Boundary
  • Canary：Activity、View Transition、Transition Type
  • 在正文中： 与描述词搭配时使用小写：“state variable”“state updates”“event handler”。概念独立出现或用于标题时使用首字母大写：“State is isolated and private”
  • 一般用法保持小写：“the page transitions”“takes an action”
• 产品名称： ESLint、TypeScript、JavaScript、Next.js（不要使用小写）
• 关键概念使用粗体： state variable、event handler
• 新定义的术语使用斜体： event handlers
• API 使用行内代码： useState、startTransition、<Suspense>
• 避免使用： “simple”“easy”“just”以及时间估算
• 将差异描述为“功能”，而非“优点/缺点”
• 避免被动语态和行话

不同页面类型的语气

类型	语气	示例
学习	对话式	“下面来看看它是什么样的……”“你可能会好奇……”
参考	技术性	“在顶层调用 useState……”、“这个 Hook 会返回……”
博客	准确	聚焦事实，而非营销

注意： Pitfall 和 DeepDive 组件即使出现在参考页面中，也可以使用稍微偏对话式的表达（如“你可能会想……”“你可能会想尝试……”），因为它们属于解释性补充内容。

避免行话

模式： 先解释行为，再介绍术语。

✅ “React 会等事件处理函数中的所有代码运行完毕后，再处理状态更新。这称为 批处理。”

❌ “React 使用批处理，以原子方式处理状态更新。”

应避免或解释的术语：

行话	通俗表达
atomic（原子性）	全有或全无、合并处理
idempotent（幂等）	输入相同，输出相同
deterministic（确定性）	结果可预测、每次都相同
memoize（记忆化）	记住结果，跳过重新计算
referentially transparent（引用透明）	（避免使用——描述具体行为）
invariant（不变量）	必须始终成立的规则
reify（具体化）	（避免使用——描述所创建的内容）

参考页面中允许使用的技术术语：

• “stale closures”——标准的 JS/React 术语，可在 Caveats 中使用
• “stable identity”——React 术语，指在多次渲染之间保持一致的对象引用
• “reactive”——React 术语，指发生变化时会触发重新渲染的值
• 在参考页面中无需解释这些术语（读者通常已了解）

谨慎使用已有的类比——引入概念时使用一次，不要反复使用：

概念	类比
Components/React	厨房（组件是厨师，React 是服务员）
渲染阶段	餐厅点餐（触发/渲染/提交）
状态批处理	服务员收齐订单后再送到厨房
状态行为	某一时刻的快照/照片
状态存储	React 将状态“放在架子上”
状态用途	组件的记忆
纯函数	食谱（相同食材 → 相同菜肴）
纯函数	数学公式（y = 2x）
Props	可调节的“旋钮”
Children prop	由父级填充的“空位”
Keys	文件夹中的文件名
JSX 中的花括号	“通向 JavaScript 的窗口”
声明式 UI	出租车司机（告诉司机目的地，而不是逐步指路）
命令式 UI	逐步导航
状态结构	数据库规范化
Refs	React 不会跟踪的“秘密口袋”
Effects/Refs	React 的“逃生口”
Context	CSS 继承 /“传送”
自定义 Hooks	设计系统

常见正文模式

错误与正确的代码：

\`\`\`js
// 🚩 Don't mutate state:
obj.x = 10;
\`\`\`

\`\`\`js
// ✅ Replace with new object:
setObj({ ...obj, x: 10 });
\`\`\`

表格对比：

| passing a function | calling a function |
| `onClick={handleClick}` | `onClick={handleClick()}` |

链接：

[Read about state](/learn/state-a-components-memory)
[See `useState` reference](/reference/react/useState)

代码风格

• 优先使用 JSX，而非 createElement
• 使用 const/let，绝不使用 var
• 顶层函数优先使用具名函数声明
• 对于需要保留 this 的回调，使用箭头函数

版本文档

当 API 在不同版本间发生变化时：

Starting in React 19, render `<Context>` as a provider:
\`\`\`js
<SomeContext value={value}>{children}</SomeContext>
\`\`\`

In older versions:
\`\`\`js
<SomeContext.Provider value={value}>{children}</SomeContext.Provider>
\`\`\`

模式：

• 对于新 API，使用“从 React 19 开始……”
• 对于旧模式，使用“在较旧版本的 React 中……”