贡献指南

感谢你对 React 文档的关注与贡献！

行为准则

Facebook 采用了一套行为准则，希望所有项目参与者共同遵守。请阅读完整文本，以便了解哪些行为是被容忍的，哪些行为不会被容忍。

技术写作建议

这是一份很好的总结，列出了编写技术文档时需要注意的事项。

文本编写指南

不同的章节有意采用不同的风格。

文档被划分为多个章节，以满足不同的学习风格和使用场景。在编辑文章时，尽量在语气和风格上匹配周围的文本。在创建新文章时，尽量匹配同一章节中其他文章的风格。请了解以下各章节背后的动机。

学习 React 旨在以循序渐进的方式介绍基本概念。学习 React 中的每一篇文章都建立在前一篇文章的知识基础上，因此请确保不要添加任何“循环依赖”。重要的是，读者可以从第一篇文章开始，一路读到最后一篇学习 React 的文章，而无需“提前查阅”任何定义。这解释了某些排序选择（例如，先讲解 state，再讲解 events；或者说“以 React 的方式思考”不使用 refs）。学习 React 同时也充当 React 概念的手册，因此对其定义以及概念之间的关系必须非常严格。

API 参考 按 API 而非概念组织。它旨在做到详尽无遗。任何在学习 React 中因简洁而跳过的边界情况或建议，都应在对应 API 的参考文档中提及。

尝试遵循你自己编写的步骤说明。

在编写分步说明（例如如何安装某物）时，尝试忘掉你对主题所知的一切，然后逐步遵循你编写的说明。你往往会发现，有些隐含的知识被遗漏了，或者说明中存在缺失或顺序颠倒的步骤。如果你能让其他人按照步骤操作，并观察他们在哪里遇到困难，那就更好了。通常，问题会是一些非常简单但你未曾预料到的点。

代码示例指南

语法

优先使用 JSX 而不是 createElement。

如果你专门在描述 createElement，可以忽略此规则。

尽可能使用 const，否则使用 let。不要使用 var。

如果你专门在讲解 ES5，可以忽略此规则。

当 ES5 功能与 ES6 功能效果相当且没有缺点时，不要使用 ES6 功能。

请记住，ES6 对很多人来说仍然是新事物。虽然我们在许多地方使用它（const / let、类、箭头函数），但如果等价的 ES5 代码同样简单易读，请考虑使用 ES5。

特别是，对于顶层函数，你应该优先使用具名 function 声明，而不是 const myFunction = () => ... 箭头函数。然而，当箭头函数能带来切实改进时（例如在组件内部保持 this 上下文），你可以使用箭头函数。在决定是否使用新特性时，请考虑两方面的取舍。

不要使用尚未标准化的特性。

例如，不要这样写：

class MyComponent extends React.Component {
  state = {value: ''};
  handleChange = (e) => {
    this.setState({value: e.target.value});
  };
}

而是应该这样写：

class MyComponent extends React.Component {
  constructor(props) {
    super(props);
    this.handleChange = this.handleChange.bind(this);
    this.state = {value: ''};
  }
  handleChange(e) {
    this.setState({value: e.target.value});
  }
}

如果你专门在描述一个实验性提案，可以忽略此规则。请务必在代码和周围的文本中说明其实验性质。

风格

• 使用分号。
• 函数名与括号之间不要有空格（method() {} 而不是 method () {}）。
• 拿不准时，使用 Prettier 偏好的默认风格。
• 始终将 React 概念大写，例如 Hooks、Effects 和 Transitions。

高亮

在 Markdown 代码块中使用 js 作为高亮语言：

```js
// code
```

有时你会看到带数字的代码块。
它们用于告诉网站高亮特定的行。

你可以高亮单行：

```js {2}
function hello() {
  // this line will get highlighted
}
```

高亮一个范围：

```js {2-4}
function hello() {
  // these lines
  // will get
  // highlighted
}
```

甚至可以高亮多个范围：

```js {2-4,6}
function hello() {
  // these lines
  // will get
  // highlighted
  console.log('hello');
  // also this one
  console.log('there');
}
```

请注意，如果你移动了带有高亮标记的示例中的代码，也需要同步更新高亮标记。

不要害怕经常使用高亮功能！当你需要将读者的注意力集中到某个容易被忽略的细节上时，它非常有价值。