From 85b053db0316f127b02b9ccb1ea191e714c0c59f Mon Sep 17 00:00:00 2001 From: scloudyy Date: Tue, 26 Jul 2016 03:23:45 +0800 Subject: [PATCH] Update docs zh cn (#7254) * update 03-interactivity-and-dynamic-uis.zh-CN * update 04-multiple-components.zh-CN * update 05-reusable-components.zh-CN * updat 06-transferring-props.zh-CN * update 07-forms.zh-CN * update 08-working-with-the-browser.zh-CN * update 08 and 08.1 * update 09-tooling-integration.zh-CN * revise * don't use ES6 --- .../03-interactivity-and-dynamic-uis.zh-CN.md | 12 +-- docs/04-multiple-components.zh-CN.md | 13 ++-- docs/05-reusable-components.zh-CN.md | 45 ++++++++--- docs/06-transferring-props.zh-CN.md | 8 +- docs/07-forms.zh-CN.md | 12 +-- docs/08-working-with-the-browser.zh-CN.md | 59 +++------------ docs/08.1-more-about-refs.zh-CN.md | 10 +-- docs/09-tooling-integration.zh-CN.md | 75 +------------------ 8 files changed, 79 insertions(+), 155 deletions(-) diff --git a/docs/03-interactivity-and-dynamic-uis.zh-CN.md b/docs/03-interactivity-and-dynamic-uis.zh-CN.md index 09548c10..e6ece97d 100644 --- a/docs/03-interactivity-and-dynamic-uis.zh-CN.md +++ b/docs/03-interactivity-and-dynamic-uis.zh-CN.md @@ -42,9 +42,9 @@ React 里只需把事件处理器（event handler）以骆峰命名（camelCased 在幕后，React 做了一些操作来让代码高效运行且易于理解。 -**Autobinding:** 在 JavaScript 里创建回调的时候，为了保证 `this` 的正确性，一般都需要显式地绑定方法到它的实例上。在 React，所有方法被自动绑定到了它的组件实例上（除非使用ES6的class符号）。React 还缓存这些绑定方法，所以 CPU 和内存都是非常高效。而且还能减少打字！ +**自动绑定:** 在 JavaScript 里创建回调的时候，为了保证 `this` 的正确性，一般都需要显式地绑定方法到它的实例上。在 React 中，所有方法被自动绑定到了它的组件实例上（[除非使用ES6的class符号](/react/docs/reusable-components.html#no-autobinding)）。React 还缓存这些绑定方法，所以 CPU 和内存都是非常高效。而且还能减少打字！ -**事件代理 ：** React 实际并没有把事件处理器绑定到节点本身。当 React 启动的时候，它在最外层使用唯一一个事件监听器处理所有事件。当组件被加载和卸载时，只是在内部映射里添加或删除事件处理器。当事件触发，React 根据映射来决定如何分发。当映射里处理器时，会当作空操作处理。参考 [David Walsh 很棒的文章](http://davidwalsh.name/event-delegate) 了解这样做高效的原因。 +**事件代理:** React 实际并没有把事件处理器绑定到节点本身。当 React 启动的时候，它在最外层使用唯一一个事件监听器处理所有事件。当组件被加载和卸载时，只是在内部映射里添加或删除事件处理器。当事件触发，React 根据映射来决定如何分发。当映射里没有事件处理函数时，会当作空操作处理。参考 [David Walsh 很棒的文章](http://davidwalsh.name/event-delegate) 了解这样做高效的原因。 ## 组件其实是状态机（State Machines） @@ -54,7 +54,7 @@ React 里，只需更新组件的 state，然后根据新的 state 重新渲染 ## State 工作原理 -常用的通知 React 数据变化的方法是调用 `setState(data, callback)`。这个方法会合并（merge） `data` 到 `this.state`，并重新渲染组件。渲染完成后，调用可选的 `callback` 回调。大部分情况下不需要提供 `callback`，因为 React 会负责把界面更新到最新状态。 +常用的通知 React 数据变化的方法是调用 `setState(data, callback)`。这个方法会合并（merge） `data` 到 `this.state`，并重新渲染组件。重新渲染完成后，调用可选的 `callback` 回调。大部分情况下不需要提供 `callback`，因为 React 会负责把界面更新到最新状态。 ## 哪些组件应该有 State？ @@ -66,12 +66,12 @@ React 里，只需更新组件的 state，然后根据新的 state 重新渲染 ## 哪些 *应该* 作为 State？ -**State 应该包括那些可能被组件的事件处理器改变并触发用户界面更新的数据。** 真实的应用中这种数据一般都很小且能被 JSON 序列化。当创建一个状态化的组件时，想象一下表示它的状态最少需要哪些数据，并只把这些数据存入 `this.state`。在 `render()` 里再根据 state 来计算你需要的其它数据。你会发现以这种方式思考和开发程序最终往往是正确的，因为如果在 state 里添加冗余数据或计算所得数据，需要你经常手动保持数据同步，不能让 React 来帮你处理。 +**State 应该包括那些可能被组件的事件处理器改变并触发用户界面更新的数据。** 真实的应用中这种数据一般都很小且能被 JSON 序列化。当创建一个状态化的组件时，思考一下表示它的状态最少需要哪些数据，并只把这些数据存入 `this.state`。在 `render()` 里再根据 state 来计算你需要的其它数据。你会发现以这种方式思考和开发程序最终往往是正确的，因为如果在 state 里添加冗余数据或计算所得数据，那么你就需要经常手动保持数据同步，而不能让 React 来帮你处理。 ## 哪些 *不应该* 作为 State？ -`this.state` 应该仅包括能表示用户界面状态所需的最少数据。因些，它不应该包括： +`this.state` 应该仅包括能表示用户界面状态所需的最少数据。因此，它不应该包括： * **计算所得数据：** 不要担心根据 state 来预先计算数据 —— 把所有的计算都放到 `render()` 里更容易保证用户界面和数据的一致性。例如，在 state 里有一个数组（listItems），我们要把数组长度渲染成字符串， 直接在 `render()` 里使用 `this.state.listItems.length + ' list items'` 比把它放到 state 里好的多。 * **React 组件：** 在 `render()` 里使用当前 props 和 state 来创建它。 -* **基于 props 的重复数据：** 尽可能使用 props 来作为实际状态的源。把 props 保存到 state 的一个有效的场景是需要知道它以前值的时候，因为 props 可能因为父组件重绘的结果而变化。 +* **基于 props 的重复数据：** 尽可能使用 props 来作为实际状态的源。把 props 保存到 state 的一个有效的场景是需要知道它以前值的时候，因为 props 可能因为父组件的重绘而变化。 diff --git a/docs/04-multiple-components.zh-CN.md b/docs/04-multiple-components.zh-CN.md index 502fe8b4..84e2e479 100644 --- a/docs/04-multiple-components.zh-CN.md +++ b/docs/04-multiple-components.zh-CN.md @@ -54,9 +54,9 @@ ReactDOM.render( ## 从属关系 -上面例子中，`Avatar` 拥有 `PagePic` 和 `PageLink` 的实例。`拥有者` 就是给其它组件设置 `props` 的那个组件。更正式地说，如果组件 `Y` 在 `render()` 方法是创建了组件 `X`，那么 `Y` 就拥有 `X`。上面讲过，组件不能修改自身的 `props` - 它们总是与它们拥有者设置的保持一致。这是保持用户界面一致性的基本不变量。 +上面例子中，`Avatar` 拥有 `PagePic` 和 `PageLink` 的实例。`拥有者` 就是给其它组件设置 `props` 的那个组件。更正式地说，如果组件 `Y` 在 `render()` 方法是创建了组件 `X`，那么 `Y` 就拥有 `X`。上面讲过，组件不能修改自身的 `props` - 它们总是与它们的拥有者所设置的值保持一致。这是保持用户界面一致性的基本不变量。 -把从属关系与父子关系加以区别至关重要。从属关系是 React 特有的，而父子关系简单来讲就是DOM 里的标签的关系。在上一个例子中，`Avatar` 拥有 `div`、`PagePic` 和 `PageLink` 实例，`div` 是 `PagePic` 和 `PageLink` 实例的**父级**（但不是拥有者）。 +把从属关系与父子关系加以区别至关重要。从属关系是 React 特有的，而父子关系简单来讲就是 DOM 里的标签的关系。在上一个例子中，`Avatar` 拥有 `div`、`PagePic` 和 `PageLink` 实例，`div` 是 `PagePic` 和 `PageLink` 实例的**父级**（但不是拥有者）。 ## 子级 @@ -66,7 +66,7 @@ ReactDOM.render( ``` -`Parent` 能通过专门的 `this.props.children` props 读取子级。**`this.props.children` 是一个不透明的数据结构：** 通过 [React.Children 工具类](/react/docs/top-level-api.html#react.children) 来操作。 +`Parent` 能通过专门的 `this.props.children` prop 读取子级。**`this.props.children` 是一个不透明的数据结构：** 通过 [React.Children 工具类](/react/docs/top-level-api.html#react.children) 来操作。 ### 子级校正（Reconciliation） @@ -123,7 +123,8 @@ ReactDOM.render( ``` 当 React 校正带有 key 的子级时，它会确保它们被重新排序（而不是破坏）或者删除（而不是重用）。 -`务必` 把 `key` 添加到子级数组里组件本身上，而不是每个子级内部最外层 HTML 上： + +务必把 `key` 添加到子级数组中的组件本身上，而不是数组中每个子级组件内部的最外层 HTML 上： ```javascript // 错误！ @@ -164,11 +165,11 @@ var MyComponent = React.createClass({ }); ``` -也可以传递ReactFragment 对象 来做有 key 的子级。详见[Keyed Fragments](create-fragment.html) +也可以传递 ReactFragment 对象来做有 key 的子级。详见[Keyed Fragments](create-fragment.html) ## 数据流 -React 里，数据通过上面介绍过的 `props` 从拥有者流向归属者。这就是高效的单向数据绑定(one-way data binding)：拥有者通过它的 `props` 或 `state` 计算出一些值，并把这些值绑定到它们拥有的组件的 props 上。因为这个过程会递归地调用，所以数据变化会自动在所有被使用的地方自动反映出来。 +React 里，数据通过上面介绍过的 `props` 从拥有者流向归属者。这就是高效的单向数据绑定(one-way data binding)：拥有者们通过它们的 `props` 或 `state` 计算出一些值，并把这些值绑定到它们拥有的组件的 props 上。因为这个过程会递归地调用，所以数据变化会自动在所有它们被使用的地方反映出来。 ## 性能提醒 diff --git a/docs/05-reusable-components.zh-CN.md b/docs/05-reusable-components.zh-CN.md index c0ecd2a9..8c31b75a 100644 --- a/docs/05-reusable-components.zh-CN.md +++ b/docs/05-reusable-components.zh-CN.md @@ -119,7 +119,7 @@ var ComponentWithDefaultProps = React.createClass({ ## 传递 Props：捷径 -有一些常用的 React 组件只是对 HTML 做简单扩展。通常，你想 复制任何传进你的组件的HTML属性 到底层的HTML元素上。为了减少输入，你可以用 JSX _spread_ 语法来完成： +有一些常用的 React 组件只是对 HTML 做简单扩展。通常，你想复制任何传进你的组件的HTML属性到底层的HTML元素上。为了减少输入，你可以用 JSX _spread_ 语法来完成： ```javascript var CheckLink = React.createClass({ @@ -139,9 +139,9 @@ ReactDOM.render( ## Mixins -组件是 React 里复用代码最佳方式，但是有时一些复杂的组件间也需要共用一些功能。有时会被称为 [跨切面关注点](https://en.wikipedia.org/wiki/Cross-cutting_concern)。React 使用 `mixins` 来解决这类问题。 +组件是 React 里复用代码的最佳方式，但是有时一些不同的组件间也需要共用一些功能。有时会被称为 [跨切面关注点](https://en.wikipedia.org/wiki/Cross-cutting_concern)。React 使用 `mixins` 来解决这类问题。 -一个通用的场景是：一个组件需要定期更新。用 `setInterval()` 做很容易，但当不需要它的时候取消定时器来节省内存是非常重要的。React 提供 [生命周期方法](/react/docs/working-with-the-browser.html#component-lifecycle) 来告知组件创建或销毁的时间。下面来做一个简单的 mixin，使用 `setInterval()` 并保证在组件销毁时清理定时器。 +一个通用的场景是：一个组件需要定期更新。用 `setInterval()` 做很容易，但当不需要它的时候取消定时器来节省内存是非常重要的。React 提供 [生命周期方法](/react/docs/working-with-the-browser.html#component-lifecycle) 来告知你组件创建或销毁的时间。下面来做一个简单的 mixin，使用 `setInterval()` 并保证在组件销毁时清理定时器。 ```javascript var SetIntervalMixin = { @@ -186,7 +186,7 @@ ReactDOM.render( ## ES6 Classes -你也可以以一个简单的JavaScript 类来定义你的React classes。使用ES6 class的例子: +你也可以以一个简单的 JavaScript 类来定义你的React classes。使用ES6 class的例子: ```javascript class HelloMessage extends React.Component { @@ -197,9 +197,9 @@ class HelloMessage extends React.Component { ReactDOM.render(, mountNode); ``` -API近似于 `React.createClass` 除了 `getInitialState`。 你应该在构造函数里设置你的`state`，而不是提供一个单独的 `getInitialState` 方法。 +API近似于 `React.createClass` 除了 `getInitialState`。 你应该在构造函数里设置你的`state`，而不是提供一个单独的 `getInitialState` 方法。就像 `getInitialState` 的返回值，你赋给 `this.state` 的值会被作为组件的初始 state。 -另一个不同是 `propTypes` 和 `defaultProps` 在构造函数而不是class body里被定义为属性。 +另一个不同是 `propTypes` 和 `defaultProps` 是在构造函数里被定义为属性，而不是在 class body 里。 ```javascript export class Counter extends React.Component { @@ -224,11 +224,38 @@ Counter.defaultProps = { initialCount: 0 }; ### 无自动绑定 -方法遵循正式的ES6 class的语义，意味着它们不会自动绑定`this`到实例上。你必须显示的使用`.bind(this)` or [箭头函数](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Functions/Arrow_functions) `=>`. +方法遵循正式的ES6 class的语义，意味着它们不会自动绑定`this`到实例上。你必须显示的使用`.bind(this)` or [箭头函数](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Functions/Arrow_functions) `=>`： + +```javascript +// 你可以使用 bind() 来绑定 `this` +
+ +// 或者你可以使用箭头函数 +
this.tick()}> +``` + +我们建议你在构造函数中绑定事件处理器，这样对于所有实例它们只需绑定一次： + +```javascript +constructor(props) { + super(props); + this.state = {count: props.initialCount}; + this.tick = this.tick.bind(this); +} +``` + +现在你可以直接使用 `this.tick` 因为它已经在构造函数里绑定过一次了。 + +```javascript +// 它已经在构造函数里绑定过了 +
+``` + +这对应用的性能有帮助，特别是当你用 [浅层比较](/react/docs/shallow-compare.html) 实现 [shouldComponentUpdate()](/react/docs/component-specs.html#updating-shouldcomponentupdate) 时。 ### 没有 Mixins -不幸的是ES6的发布没有任何mixin的支持。因此，当你在ES6 classes下使用React时不支持mixins。作为替代，我们正在努力使它更容易支持这些用例不依靠mixins。 +不幸的是ES6的发布没有任何mixin的支持。因此，当你在ES6 classes下使用React时不支持mixins。作为替代，我们正在努力使它更容易不依靠mixins支持这些用例。 ## 无状态函数 @@ -249,7 +276,7 @@ ReactDOM.render(, mountNode); ``` 这个简化的组件API旨在用于那些纯函数态的组件 。这些组件必须没有保持任何内部状态，没有备份实例，也没有组件生命周期方法。他们纯粹的函数式的转化他们的输入，没有引用。 -然而，你仍然可以以设置为函数的properties的方式来指定 `.propTypes` 和 `.defaultProps`，就像你在ES6类里设置他们那样。 +然而，你仍然可以以设置函数 properties 的方式来指定 `.propTypes` 和 `.defaultProps`，就像你在ES6类里设置他们那样。 > 注意： > diff --git a/docs/06-transferring-props.zh-CN.md b/docs/06-transferring-props.zh-CN.md index 4b92c19f..a276427c 100644 --- a/docs/06-transferring-props.zh-CN.md +++ b/docs/06-transferring-props.zh-CN.md @@ -6,7 +6,7 @@ prev: reusable-components-zh-CN.html next: forms-zh-CN.html --- -React 里有一个非常常用的模式就是对组件做一层抽象。组件对外公开一个简单的属性（Props）来实现功能，但内部细节可能有非常复杂的实现。 +React 里有一个非常常用的模式就是对组件做一层抽象。组件对外公开一个简单的属性（Props）来实现功能，但内部的实现可能非常复杂。 可以使用 [JSX 展开属性](/react/docs/jsx-spread-zh-CN.html) 来合并现有的 props 和其它值： @@ -53,7 +53,7 @@ ReactDOM.render( 有时把所有属性都传下去是不安全或啰嗦的。这时可以使用 [解构赋值](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) 中的剩余属性特性来把未知属性批量提取出来。 -列出所有要当前使用的属性，后面跟着 `...other`。 +列出所有当前要使用的属性，后面跟着 `...other`。 ```javascript var { checked, ...other } = props; @@ -118,11 +118,11 @@ function FancyCheckbox(props) { > 注意: > -> 顺序很重要，把 `{...other}` 放到 JSX props 前面会使它不被覆盖。上面例子中我们可以保证 input 的 type 是 `"checkbox"`。 +> 顺序很重要，把 `{...other}` 放到 JSX props 前面会使 props 不会被覆盖。上面例子中我们可以保证 input 的 type 是 `"checkbox"`。 ## 剩余属性和展开属性 `...` -剩余属性可以把对象剩下的属性提取到一个新的对象。会把所有在解构赋值中列出的属性剔除。 +剩余属性可以把对象剩下的属性提取到一个新的对象。这会把所有在解构赋值中列出的属性剔除。 这是 [ECMAScript 草案](https://github.com/sebmarkbage/ecmascript-rest-spread) 中的试验特性。 diff --git a/docs/07-forms.zh-CN.md b/docs/07-forms.zh-CN.md index e7cd5a1c..61e6242f 100644 --- a/docs/07-forms.zh-CN.md +++ b/docs/07-forms.zh-CN.md @@ -6,7 +6,7 @@ prev: transferring-props-zh-CN.html next: working-with-the-browser-zh-CN.html --- -诸如 ``、` ``` -对 HTML 而言，让开发者设置多行的值很容易。但是，React 是 JavaScript，没有字符串限制，可以使用 `\n` 实现换行。简言之，React 已经有 `value`、`defaultValue` 属性，`` 组件的子节点扮演什么角色就有点模棱两可了。基于此， 设置 `