@samitouri / QOS-React / commits / 28caa8882b

[DOCS] Update zh-docs to v15-rc.1 (with #3240c09)

iamchenxin committed Mar 13, 2016 at 15:05 UTC 28caa8882bbd8902d498b57cd3acf06921c43fe2
8 files changed +698 -56
docs/docs/01-why-react.zh-CN.md
-3
@@ -4,7 +4,6 @@ title: 为什么使用 React?
4 permalink: why-react-zh-CN.html
5 next: displaying-data-zh-CN.html
6 ---
7 -
7 React 是一个 Facebook 和 Instagram 用来创建用户界面的 JavaScript 库。很多人选择将 React 认为是 **[MVC](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)** 中的 **V**（视图）。
8
9 我们创造 React 是为了解决一个问题：**构建随着时间数据不断变化的大规模应用程序**。
@@ -28,5 +27,3 @@ React挑战了很多传统的知识，第一眼看上去可能很多想法有点
27 ## 了解更多
28
29 你可以从这篇[博客](/react/blog/2013/06/05/why-react.html)了解更多我们创造 React 的动机。
31 -
32 -
docs/docs/10.4-test-utils.zh-CN.md new
+244
@@ -0,0 +1,244 @@
1 +---
2 +id: test-utils-zh-CN
3 +title: 测试工具
4 +permalink: test-utils-zh-CN.html
5 +prev: two-way-binding-helpers-zh-CN.html
6 +next: clone-with-props-zh-CN.html
7 +---
8 +
9 +`ReactTestUtils` 使你在你选择的测试框架中 (我们使用 [Jest](https://facebook.github.io/jest/)) 测试 React 组件变得容易。
10 +
11 +```
12 +var ReactTestUtils = require('react-addons-test-utils');
13 +```
14 +
15 +### Simulate
16 +
17 +```javascript
18 +Simulate.{eventName}(
19 + DOMElement element,
20 + [object eventData]
21 +)
22 +```
23 +
24 +模拟一个在 DOM 节点上带有可选 `eventData` 事件数据的事件派遣（event dispatch）。**这可能是 `ReactTestUtils` 里单独最有用的工具。**
25 +
26 +**点击一个元素**
27 +
28 +```javascript
29 +// <button ref="button">...</button>
30 +var node = this.refs.button;
31 +ReactTestUtils.Simulate.click(node);
32 +```
33 +
34 +**改变 input 域的值然后点击 回车。**
35 +
36 +```javascript
37 +// <input ref="input" />
38 +var node = this.refs.input;
39 +node.value = 'giraffe'
40 +ReactTestUtils.Simulate.change(node);
41 +ReactTestUtils.Simulate.keyDown(node, {key: "Enter", keyCode: 13, which: 13});
42 +```
43 +
44 +*注意你将必须提供任何你在你的组件里使用的事件属性（例如 keyCode, which, 等等）因为React没有为你创建任何这类东西。*
45 +
46 +`Simulate` has a method for [every event that React understands](/react/docs/events.html#supported-events).
47 +
48 +### renderIntoDocument
49 +
50 +```javascript
51 +ReactComponent renderIntoDocument(
52 + ReactElement instance
53 +)
54 +```
55 +
56 +渲染一个组件到 document 里的 detached DOM 节点。**这个函数需要一个 DOM。**
57 +
58 +> 注意:
59 +>
60 +> 在你 import React **之前**，你需要让 `window`, `window.document` 和 `window.document.createElement` 全局可用。
61 +不然 React 会认为它不能访问 DOM 然后类似 `setState` 的方法会不工作。
62 +
63 +### mockComponent
64 +
65 +```javascript
66 +object mockComponent(
67 + function componentClass,
68 + [string mockTagName]
69 +)
70 +```
71 +
72 +传入一个 mocked 组件模块到这个方法来给它增加有用的方法，使它可以被用作 dummy React 组件。代替像通常一样的渲染，组件会成为一个简单的包含了任意被提供的子级的 `<div>` （或者其他 tag 名，如果提供了 `mockTagName`）
73 +
74 +### isElement
75 +
76 +```javascript
77 +boolean isElement(
78 + ReactElement element
79 +)
80 +```
81 +
82 +返回 `true` 如果 `element` 是任意的 ReactElement。
83 +
84 +### isElementOfType
85 +
86 +```javascript
87 +boolean isElementOfType(
88 + ReactElement element,
89 + function componentClass
90 +)
91 +```
92 +
93 +返回 `true` 如果 `element` 是一个类型是 React `componentClass` 的 ReactElement。
94 +
95 +### isDOMComponent
96 +
97 +```javascript
98 +boolean isDOMComponent(
99 + ReactComponent instance
100 +)
101 +```
102 +
103 +返回 `true` 如果 `instance` 是一个 DOM 组件 （比如一个 `<div>` 或者 `<span>`）。
104 +
105 +### isCompositeComponent
106 +
107 +```javascript
108 +boolean isCompositeComponent(
109 + ReactComponent instance
110 +)
111 +```
112 +
113 +返回 `true` 如果 `instance` 是一个复合组件 （由 `React.createClass()` 创建）。
114 +
115 +### isCompositeComponentWithType
116 +
117 +```javascript
118 +boolean isCompositeComponentWithType(
119 + ReactComponent instance,
120 + function componentClass
121 +)
122 +```
123 +
124 +返回 `true` 如果 `instance` 是一个类型为 React `componentClass` 的复合组件 （由 `React.createClass()` 创建）。
125 +
126 +### findAllInRenderedTree
127 +
128 +```javascript
129 +array findAllInRenderedTree(
130 + ReactComponent tree,
131 + function test
132 +)
133 +```
134 +
135 +遍历 `tree` 里所有的组件，并累积所有 `test(component)` 为 `true` 的组件。它本身并没有什么用，但是它被用作其他测试工具的基本元素。
136 +
137 +### scryRenderedDOMComponentsWithClass
138 +
139 +```javascript
140 +array scryRenderedDOMComponentsWithClass(
141 + ReactComponent tree, string className
142 +)
143 +```
144 +
145 +在渲染的树中查找所有 DOM组件的类名匹配`className` 的组件实例。
146 +
147 +### findRenderedDOMComponentWithClass
148 +
149 +```javascript
150 +ReactComponent findRenderedDOMComponentWithClass(
151 + ReactComponent tree,
152 + string className
153 +)
154 +```
155 +
156 +类似 `scryRenderedDOMComponentsWithClass()` 除了只有一个返回结果，并且要么返回这个结果，要么如果还有其他的匹配项就抛出一个异常。
157 +
158 +### scryRenderedDOMComponentsWithTag
159 +
160 +```javascript
161 +array scryRenderedDOMComponentsWithTag(
162 + ReactComponent tree,
163 + string tagName
164 +)
165 +```
166 +
167 +在渲染的树中查找所有 DOM 组件的 tag 名匹配 `tagName` 的组件实例。
168 +
169 +### findRenderedDOMComponentWithTag
170 +
171 +```javascript
172 +ReactComponent findRenderedDOMComponentWithTag(
173 + ReactComponent tree,
174 + string tagName
175 +)
176 +```
177 +
178 +类似 `scryRenderedDOMComponentsWithTag()` 除了只有一个返回结果，并且要么返回这个结果，要么如果还有其他的匹配项就抛出一个异常。
179 +
180 +### scryRenderedComponentsWithType
181 +
182 +```javascript
183 +array scryRenderedComponentsWithType(
184 + ReactComponent tree,
185 + function componentClass
186 +)
187 +```
188 +
189 +查找所有类型等于 `componentClass` 的组件实例。
190 +
191 +### findRenderedComponentWithType
192 +
193 +```javascript
194 +ReactComponent findRenderedComponentWithType(
195 + ReactComponent tree, function componentClass
196 +)
197 +```
198 +
199 +类似 `scryRenderedComponentsWithType()` 除了只有一个返回结果，并且要么返回这个结果，要么如果还有其他的匹配项就抛出一个异常。
200 +
201 +## Shallow rendering（浅渲染）
202 +
203 +浅渲染是一个实验性特性，让你渲染一个组件为 "one level deep" 并且断言渲染方法返回的内容，不用担心子组件的行为，它们没有被实例化或者渲染。这个方式不需要一个 DOM。
204 +
205 +```javascript
206 +ReactShallowRenderer createRenderer()
207 +```
208 +
209 +在你的测试里调用它来创建一个浅渲染器。你可以把它想做是一个你渲染你要测试的组件的 "地方"，它可以自己响应事件并更新。
210 +
211 +```javascript
212 +shallowRenderer.render(
213 + ReactElement element
214 +)
215 +```
216 +
217 +类似于 `ReactDOM.render`。
218 +
219 +```javascript
220 +ReactElement shallowRenderer.getRenderOutput()
221 +```
222 +
223 +在 `render` 被调用后，返回一个浅渲染的输出。你可以接着断言输出的内容。例如，如果你的组件的渲染方法返回：
224 +
225 +```javascript
226 +<div>
227 + <span className="heading">Title</span>
228 + <Subcomponent foo="bar" />
229 +</div>
230 +```
231 +
232 +然后你可以断言：
233 +
234 +```javascript
235 +var renderer = ReactTestUtils.createRenderer();
236 +result = renderer.getRenderOutput();
237 +expect(result.type).toBe('div');
238 +expect(result.props.children).toEqual([
239 + <span className="heading">Title</span>,
240 + <Subcomponent foo="bar" />
241 +]);
242 +```
243 +
244 +浅测试现在有一些限制，即不支持 refs。我们在早期发布这个特性，并感激 React 社区关于它应该如何演化的反馈。
docs/docs/10.5-clone-with-props.zh-CN.md new
+36
@@ -0,0 +1,36 @@
1 +---
2 +id: clone-with-props-zh-CN
3 +title: 克隆 ReactElements
4 +permalink: clone-with-props-zh-CN.html
5 +prev: test-utils-zh-CN.html
6 +next: create-fragment-zh-CN.html
7 +---
8 +
9 +> 注意:
10 +> `cloneWithProps` 被弃用了. 用 [React.cloneElement](top-level-api.html#react.cloneelement) 代替.
11 +
12 +在很罕见的情况下，你可能需要创建一个 React 元素的拷贝，它与初始的元素有不同的 props。一个例子是克隆这些传递到 `this.props.children` 的元素并用不同的 props 渲染他们。
13 +
14 +```js
15 +var cloneWithProps = require('react-addons-clone-with-props');
16 +
17 +var _makeBlue = function(element) {
18 + return cloneWithProps(element, {style: {color: 'blue'}});
19 +};
20 +
21 +var Blue = React.createClass({
22 + render: function() {
23 + var blueChildren = React.Children.map(this.props.children, _makeBlue);
24 + return <div>{blueChildren}</div>;
25 + }
26 +});
27 +
28 +ReactDOM.render(
29 + <Blue>
30 + <p>This text is blue.</p>
31 + </Blue>,
32 + document.getElementById('container')
33 +);
34 +```
35 +
36 +`cloneWithProps` 不传递 `key` 或者 `ref` 到被克隆的元素。`className` 和 `style` props 被自动合并。
docs/docs/10.6-create-fragment.zh-CN.md new
+75
@@ -0,0 +1,75 @@
1 +---
2 +id: create-fragment-zh-CN
3 +title: Keyed Fragments
4 +permalink: create-fragment-zh-CN.html
5 +prev: clone-with-props-zh-CN.html
6 +next: update-zh-CN.html
7 +---
8 +
9 +在大多数情况下，你可以使用 `key` prop 指定你从 `render` 返回的元素的 keys。然而，这在一个情况下会失败：如果你有两组你需要记录的子级，将没有办法在不使用包裹元素的情况下放置一个 key 到每组上。
10 +
11 +即是，如果你有一个像这样的组件：
12 +
13 +```js
14 +var Swapper = React.createClass({
15 + propTypes: {
16 + // `leftChildren` and `rightChildren` can be a string, element, array, etc.
17 + leftChildren: React.PropTypes.node,
18 + rightChildren: React.PropTypes.node,
19 +
20 + swapped: React.PropTypes.bool
21 + },
22 + render: function() {
23 + var children;
24 + if (this.props.swapped) {
25 + children = [this.props.rightChildren, this.props.leftChildren];
26 + } else {
27 + children = [this.props.leftChildren, this.props.rightChildren];
28 + }
29 + return <div>{children}</div>;
30 + }
31 +});
32 +```
33 +
34 +这些子级会在当你改变 `swapped` prop 时加载和卸载，因为没有任何的 key 标记在这两组子级上。
35 +
36 +要解决这个问题，你可以使用 `createFragment` 插件来给予这两组子级 keys.
37 +
38 +#### `Array<ReactNode> createFragment(object children)`
39 +
40 +代替创建数组，我们这样写：
41 +
42 +```js
43 +var createFragment = require('react-addons-create-fragment');
44 +
45 +if (this.props.swapped) {
46 + children = createFragment({
47 + right: this.props.rightChildren,
48 + left: this.props.leftChildren
49 + });
50 +} else {
51 + children = createFragment({
52 + left: this.props.leftChildren,
53 + right: this.props.rightChildren
54 + });
55 +}
56 +```
57 +
58 +被传入对象的 keys （即 `left` 和 `right`）被用作为整组子级的 keys，并且对象 keys 的顺序被用于决定渲染子级的顺序。通过这个改变，这两个子级将会恰当的在 DOM 里排序，而不被卸载。
59 +
60 +`createFragment` 的返回值应该被对待为一个不透明的对象;你可以使用 `React.Children` 来遍历一个 fragment 但是不应该直接访问它。同样注意，我们依赖于 JavaScript 引擎保留了对象的枚举顺序，这点在 spec 上是不保证的，但是所有主要的浏览器和 VMs 都对非数字键的对象实现了这个特性。
61 +
62 +> **注意:**
63 +>
64 +> 将来，`createFragment` 也许会被替换为如下的API：
65 +>
66 +> ```js
67 +> return (
68 +> <div>
69 +> <x:frag key="right">{this.props.rightChildren}</x:frag>,
70 +> <x:frag key="left">{this.props.leftChildren}</x:frag>
71 +> </div>
72 +> );
73 +> ```
74 +>
75 +> 允许你直接在 JSX 里赋值 keys 而不用添加包裹元素。
docs/docs/10.7-update.zh-CN.md new
+102
@@ -0,0 +1,102 @@
1 +---
2 +id: update-zh-CN
3 +title: immutability 助手
4 +permalink: update-zh-CN.html
5 +prev: create-fragment-zh-CN.html
6 +next: pure-render-mixin-zh-CN.html
7 +---
8 +
9 +React 让你可以使用任何你想要的数据管理方式，包括 mutation。然而，如果你可以在你的应用的性能关键性部分里使用 immutable 数据，将会易于实现一个快速的 `shouldComponentUpdate()` 方法来显著加速你的 app。
10 +
11 +在 JavaScript 里处理 immutable 数据比在为此设计的语言中要难的多，比如 [Clojure](http://clojure.org/)。然而，我们提供了一个简单的 immutability 助手，`update()`，它使处理这类数据容易多了，*不用* 根本性的改变你的数据的表达方式。你也同样可以看一看 Facebook 的 [Immutable-js](https://facebook.github.io/immutable-js/docs/) 和[Advanced Performance](/react/docs/advanced-performance.html) 了解更多关于 Immutable-js 的信息。
12 +
13 +## 主要的思路
14 +
15 +如果你像这样变动数据：
16 +
17 +```js
18 +myData.x.y.z = 7;
19 +// or...
20 +myData.a.b.push(9);
21 +```
22 +
23 +你将没有任何办法决定哪个数据被改变了，因为之前的拷贝已经被覆盖。作为替代，你需要创建一个新的 `myData` 的拷贝并且只修改需要改变的地方。然后你可以用三个等于在 `shouldComponentUpdate()` 里比较旧的 `myData` 拷贝与新的拷贝：
24 +
25 +```js
26 +var newData = deepCopy(myData);
27 +newData.x.y.z = 7;
28 +newData.a.b.push(9);
29 +```
30 +
31 +不幸的是，深拷贝很昂贵，并且有时候不可能。你可以通过仅仅拷贝需要被改变和重用没有改变的对象来缓解这个情况。不幸的是，在当今的 JavaScript 里这会很笨重：
32 +
33 +```js
34 +var newData = extend(myData, {
35 + x: extend(myData.x, {
36 + y: extend(myData.x.y, {z: 7}),
37 + }),
38 + a: extend(myData.a, {b: myData.a.b.concat(9)})
39 +});
40 +```
41 +
42 +虽然这相当高性能（因为只对 `log n` 的对象进行了浅拷贝并重用了剩下的），但它写起来很痛苦。看看所有重复的代码！这不仅仅是烦人的，同时也提供了一大片 bugs 区域。
43 +
44 +`update()` 提供了这个模式的简单语法糖来使写这类代码更容易。上面的代码变成：
45 +
46 +```js
47 +var update = require('react-addons-update');
48 +
49 +var newData = update(myData, {
50 + x: {y: {z: {$set: 7}}},
51 + a: {b: {$push: [9]}}
52 +});
53 +```
54 +
55 +虽然这个语法需要花一些时间来适应（它的灵感来自于 [MongoDB's query language](http://docs.mongodb.org/manual/core/crud-introduction/#query)），但是没有冗余，它可静态分析并且没有 mutative 版本那么多键入。
56 +
57 +`$`-前缀的 keys 被称为 *命令*。被 "变动的" 数据结构被称为 *目标*。
58 +
59 +## 有效的命令
60 +
61 + * `{$push: array}` 在目标上 `push()` 所有 `array` 里的项目。
62 + * `{$unshift: array}` 在目标上 `unshift()` 所有 `array` 里的项目。
63 + * `{$splice: array of arrays}` 在目标上对于每一个 `arrays` 里的项目使用项目提供的参数调用 `splice()`。
64 + * `{$set: any}` 整个替换目标.
65 + * `{$merge: object}` 合并 目标和 `object` 的 keys.
66 + * `{$apply: function}` 传递当前的值给 function 并用返回值更新它。
67 +
68 +## 例子
69 +
70 +### 简单的 push
71 +
72 +```js
73 +var initialArray = [1, 2, 3];
74 +var newArray = update(initialArray, {$push: [4]}); // => [1, 2, 3, 4]
75 +```
76 +`initialArray` is still `[1, 2, 3]`.
77 +
78 +### 嵌套的 collections
79 +
80 +```js
81 +var collection = [1, 2, {a: [12, 17, 15]}];
82 +var newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}});
83 +// => [1, 2, {a: [12, 13, 14, 15]}]
84 +```
85 +本例访问了 `collection` 的`2`索引下的键`a`，并且拼接了一个从索引`1`开始（移除`17`）并插入`13`和`14`的项目。
86 +
87 +### 基于当前的值更新新值
88 +
89 +```js
90 +var obj = {a: 5, b: 3};
91 +var newObj = update(obj, {b: {$apply: function(x) {return x * 2;}}});
92 +// => {a: 5, b: 6}
93 +// This is equivalent, but gets verbose for deeply nested collections:
94 +var newObj2 = update(obj, {b: {$set: obj.b * 2}});
95 +```
96 +
97 +### (浅) 合并
98 +
99 +```js
100 +var obj = {a: 5, b: 3};
101 +var newObj = update(obj, {$merge: {b: 6, c: 7}}); // => {a: 5, b: 6, c: 7}
102 +```
docs/docs/10.8-pure-render-mixin.zh-CN.md new
+46
@@ -0,0 +1,46 @@
1 +---
2 +id: pure-render-mixin-zh-CN
3 +title: PureRenderMixin
4 +permalink: pure-render-mixin-zh-CN.html
5 +prev: update-zh-CN.html
6 +next: perf-zh-CN.html
7 +---
8 +
9 +如果你的 React 组件的 render 函数是 "纯净" 的（换句话说，它的渲染在给定相同的 props 和 state 时返回相同的结果），你可以使用这个 mixin 在某些情况下进行性能加速。
10 +
11 +例子:
12 +
13 +```js
14 +var PureRenderMixin = require('react-addons-pure-render-mixin');
15 +React.createClass({
16 + mixins: [PureRenderMixin],
17 +
18 + render: function() {
19 + return <div className={this.props.className}>foo</div>;
20 + }
21 +});
22 +```
23 +
24 +使用 ES6 class 语法的例子:
25 +
26 +```js
27 +import PureRenderMixin from 'react-addons-pure-render-mixin';
28 +class FooComponent extends React.Component {
29 + constructor(props) {
30 + super(props);
31 + this.shouldComponentUpdate = PureRenderMixin.shouldComponentUpdate.bind(this);
32 + }
33 +
34 + render() {
35 + return <div className={this.props.className}>foo</div>;
36 + }
37 +}
38 +```
39 +
40 +在内部, mixin 实现了 [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate), 它对当前及下一步的 props 和 state 进行比较，并当相等时返回 `false`。
41 +
42 +> 注意:
43 +>
44 +> 它仅仅浅比较对象。如果包含了复杂的对象，可能会对于深层的不同产生 false-negatives。只 mix 到那些含有简单 props 和 state 的组件，或者在你知道深层对象改变时使用 `forceUpdate()` 。或者，考虑使用[immutable objects](https://facebook.github.io/immutable-js/) 来促进快速的嵌套数据比较。
45 +>
46 +> 此外， `shouldComponentUpdate` 跳过了整个子树的更新。确保所有的子组件都是 "纯净" 的。
docs/docs/10.9-perf.zh-CN.md new
+74
@@ -0,0 +1,74 @@
1 +---
2 +id: perf-zh-CN
3 +title: 性能工具
4 +permalink: perf-zh-CN.html
5 +prev: pure-render-mixin-zh-CN.html
6 +next: shallow-compare-zh-CN.html
7 +---
8 +
9 +React 通常是相当快的。然而，在你需要压榨你的 app 的每一分性能的情况下，它提供了一个[shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate) 钩子，在此你可以添加优化提示到 React 的 diff 算法里。
10 +
11 +除了给予你一个你的 app 的整体性能概览外，ReactPerf 还是一个准确告诉你，你需要在哪里放置这些钩子的分析工具。
12 +
13 +## General API
14 +
15 +这里陈述的 `Perf` 对象被用 `require('react-addons-perf')` 暴露，并且只能被使用在 React 的开发模式。你不应在生产环境下在你的 app 包含这个包。
16 +
17 +> 注意:
18 +>
19 +> 开发版的 React 慢于生产版，因为所有额外提供的逻辑，例如，React 的友好的控制台警告 （在生产版中被除去）。因此，分析工具仅服务于指示你的 app _相对_ 昂贵的部分。
20 +
21 +### `Perf.start()` and `Perf.stop()`
22 +开始/停止测量。其间的React操作被记录用于之后的分析。产生无关紧要时间的操作被忽略。
23 +
24 +在停止以后，你将需要 `Perf.getLastMeasurements()` （下面将介绍）来获取测量结果。
25 +
26 +### `Perf.printInclusive(measurements)`
27 +打印总体花费的时间。如果没有传入参数，默认是从上次记录的所有测量数据。它在控制台里打印良好格式化的结果，像这样：
28 +
29 +![](/react/img/docs/perf-inclusive.png)
30 +
31 +### `Perf.printExclusive(measurements)`
32 +"独占的"时间不包括花费于加载组件的时间： 处理 props, `getInitialState`, 调用 `componentWillMount` 及 `componentDidMount`, 等等。
33 +
34 +![](/react/img/docs/perf-exclusive.png)
35 +
36 +### `Perf.printWasted(measurements)`
37 +
38 +**分析工具里最有用的部分**.
39 +
40 +"垃圾"时间是花费在组件上实际没有绘制任何东西的时间，例如渲染结果总是相同，所以 DOM 没有被触碰到。
41 +
42 +![](/react/img/docs/perf-wasted.png)
43 +
44 +### `Perf.printDOM(measurements)`
45 +打印底层的 DOM 操纵，例如 "set innerHTML" 和 "remove".
46 +
47 +![](/react/img/docs/perf-dom.png)
48 +
49 +## Advanced API
50 +
51 +以上的打印方法使用 `Perf.getLastMeasurements()` 来美观的打印结果。
52 +
53 +### `Perf.getLastMeasurements()`
54 +从最后的 start-stop 会话获取测量数据数据。这个数组包含对象，每个看起来像这样：
55 +
56 +```js
57 +{
58 + // The term "inclusive" and "exclusive" are explained below
59 + "exclusive": {},
60 + // '.0.0' is the React ID of the node
61 + "inclusive": {".0.0": 0.0670000008540228, ".0": 0.3259999939473346},
62 + "render": {".0": 0.036999990697950125, ".0.0": 0.010000003385357559},
63 + // Number of instances
64 + "counts": {".0": 1, ".0.0": 1},
65 + // DOM touches
66 + "writes": {},
67 + // Extra debugging info
68 + "displayNames": {
69 + ".0": {"current": "App", "owner": "<root>"},
70 + ".0.0": {"current": "Box", "owner": "App"}
71 + },
72 + "totalTime": 0.48499999684281647
73 +}
74 +```
docs/docs/tutorial.zh-CN.md
+121 -53
@@ -44,6 +44,7 @@ next: thinking-in-react-zh-CN.html
44 <script src="https://cdnjs.cloudflare.com/ajax/libs/react/{{site.react_version}}/react-dom.js"></script>
45 <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.23/browser.min.js"></script>
46 <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script>
47 + <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/0.3.5/marked.min.js"></script>
48 </head>
49 <body>
50 <div id="content"></div>
@@ -96,7 +97,7 @@ ReactDOM.render(
97
98 #### JSX 语法
99
99 -首先你会注意到你的 JavaScript 中 XML 式的语法。我们有一个简单的预编译器，将这种语法糖转换成单纯的 JavaScript ：
100 +首先你会注意到你的 JavaScript 中 XML 式的语法。我们有一个简单的预编译器，将语法糖转换成这种纯的JavaScript：
101
102 ```javascript
103 // tutorial1-raw.js
@@ -127,6 +128,10 @@ ReactDOM.render(
128
129 `ReactDOM.render()` 实例化根组件，启动框架，注入标记到原始的 DOM 元素中，作为第二个参数提供。
130
131 +`ReactDOM` 模块暴露了 DOM 相关的方法， 而 `React` 保有被不同平台的 React 共享的核心工具 （例如 [React Native](http://facebook.github.io/react-native/)）。
132 +
133 +对于本教程 `ReactDOM.render` 保持在脚本底部是很重要的。`ReactDOM.render` 应该只在复合组件被定义之后被调用。
134 +
135 ## 组合组件
136
137 让我们为 `CommentList` 和 `CommentForm` 建造骨架，它们将会，再一次的，是一些简单的 `<div>`。添加这两个组件到你的文件里，保持现存的 `CommentBox` 声明和 `ReactDOM.render` 调用:
@@ -219,22 +224,7 @@ var CommentList = React.createClass({
224
225 Markdown 是一种简单的内联格式化你的文字的方法。例如，用星号包围文本将会使其强调突出。
226
222 -首先，添加第三方库 **marked** 到你的应用。这是一个JavaScript库，接受 Markdown 文本并且转换为原始的 HTML。这需要在你的头部有一个 script 标签（那个我们已经在 React 操场上包含了的标签）：
223 -
224 -```html{9}
225 -<!-- index.html -->
226 -<head>
227 - <meta charset="utf-8" />
228 - <title>React Tutorial</title>
229 - <script src="https://cdnjs.cloudflare.com/ajax/libs/react/{{site.react_version}}/react.js"></script>
230 - <script src="https://cdnjs.cloudflare.com/ajax/libs/react/{{site.react_version}}/react-dom.js"></script>
231 - <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.23/browser.min.js"></script>
232 - <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
233 - <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/0.3.5/marked.min.js"></script>
234 -</head>
235 -```
236 -
237 -然后，让我们转换评论文本为 Markdown 并输出它：
227 +在本教程中我们使用第三方库 **marked**，它接受 Markdown 文本并且转换为原始的 HTML。我们已经在初始的页面标记里包含了这个库，所以我们可以直接开始使用它，让我们转换评论文本为 Markdown 并输出它：
228
229 ```javascript{9}
230 // tutorial6.js
@@ -290,12 +280,12 @@ var Comment = React.createClass({
280 ```javascript
281 // tutorial8.js
282 var data = [
293 - {author: "Pete Hunt", text: "This is one comment"},
294 - {author: "Jordan Walke", text: "This is *another* comment"}
283 + {id: 1, author: "Pete Hunt", text: "This is one comment"},
284 + {id: 2, author: "Jordan Walke", text: "This is *another* comment"}
285 ];
286 ```
287
298 -我们需要以一种模块化的方式将这个数据传入到 `CommentList`。修改 `CommentBox` 和 `ReactDOM.render()` 方法，以通过 props 传入数据到 `CommentList`：
288 +我们需要以一种模块化的方式将这个数据传入到 `CommentList`。修改 `CommentBox` 和 `ReactDOM.render()` 方法，以便于通过 props 传入数据到 `CommentList`：
289
290 ```javascript{7,15}
291 // tutorial9.js
@@ -323,9 +313,9 @@ ReactDOM.render(
313 // tutorial10.js
314 var CommentList = React.createClass({
315 render: function() {
326 - var commentNodes = this.props.data.map(function (comment) {
316 + var commentNodes = this.props.data.map(function(comment) {
317 return (
328 - <Comment author={comment.author}>
318 + <Comment author={comment.author} key={comment.id}>
319 {comment.text}
320 </Comment>
321 );
@@ -386,7 +376,7 @@ var CommentBox = React.createClass({
376 `getInitialState()` 在生命周期里只执行一次，并设置组件的初始状态。
377
378 #### 更新状态
389 -当组件第一次创建时，我们想从服务器获取一些 JSON 并且更新状态以反映最新的数据。我们将用 jQuery 来发送一个异步请求到我们刚才启动的服务器以获取我们需要的数据。看起来像这样：
379 +当组件第一次创建时，我们想从服务器获取一些 JSON 并且更新状态以反映最新的数据。我们将用 jQuery 来发送一个异步请求到我们刚才启动的服务器以获取我们需要的数据。这些数据已经被包含在了你已启动的服务器里（基于`comments.json`文件），所以一旦被获取，`this.state.data` 会看起来像这样：
380
381 ```json
382 [
@@ -490,28 +480,91 @@ var CommentForm = React.createClass({
480 });
481 ```
482
493 -让我们做一个交互式的表单。当用户提交表单时，我们应该清空它，提交一个请求给服务器，和刷新评论列表。要开始，让我们监听表单的提交事件并清空它。
483 +#### 受控组件
484
495 -```javascript{3-14,16-19}
485 +对于传统的 DOM， `input` 元素被渲染并且浏览器管理它的状态（它的渲染值）。结果是，DOM的实际值会和组件不同。这是不理想的，因为视图的值会和组件的值不同。在React中，组件应该总是表示视图的值而不只是在初始化时。
486 +
487 +因此，我们将使用 `this.state` 来在用户输入时保存输入。我们定义一个初始 `state`，它带有 `author` 和 `text` 两个属性并将他们设置为空字符串。在我们的 `<input>` 元素里，我们设置 `value` prop 来反映组件的 `state` 并给他们附加 `onChange` 事件处理。这些带有设置了 `value` 的 `<input>` 元素被称为受控组件。更多关于受控组件请阅读 [Forms article](/react/docs/forms.html#controlled-components)。
488 +
489 +```javascript{3-11,15-26}
490 // tutorial16.js
491 var CommentForm = React.createClass({
492 + getInitialState: function() {
493 + return {author: '', text: ''};
494 + },
495 + handleAuthorChange: function(e) {
496 + this.setState({author: e.target.value});
497 + },
498 + handleTextChange: function(e) {
499 + this.setState({text: e.target.value});
500 + },
501 + render: function() {
502 + return (
503 + <form className="commentForm">
504 + <input
505 + type="text"
506 + placeholder="Your name"
507 + value={this.state.author}
508 + onChange={this.handleAuthorChange}
509 + />
510 + <input
511 + type="text"
512 + placeholder="Say something..."
513 + value={this.state.text}
514 + onChange={this.handleTextChange}
515 + />
516 + <input type="submit" value="Post" />
517 + </form>
518 + );
519 + }
520 +});
521 +```
522 +
523 +##### 事件
524 +
525 +React使用小驼峰命名规范(camelCase)给组件绑定事件处理器。我们附加 `onChange` 给两个 `<input>` 元素。现在，当用户输入文本到 `<input>` 中，被附加的 `onChange` 回调函数被激发并且组件的 `state` 被修改。然后，被渲染的 `input` 元素的值将会更新以反映当前组件的 `state`。
526 +
527 +#### 提交表单
528 +
529 +让我们使表单具有交互性。当用户提交表单时，我们应该清除它，提交一个请求到服务器，并刷新评论列表。让我们监听表单的提交事件并清除它。
530 +
531 +```javascript{12-21,24}
532 +// tutorial17.js
533 +var CommentForm = React.createClass({
534 + getInitialState: function() {
535 + return {author: '', text: ''};
536 + },
537 + handleAuthorChange: function(e) {
538 + this.setState({author: e.target.value});
539 + },
540 + handleTextChange: function(e) {
541 + this.setState({text: e.target.value});
542 + },
543 handleSubmit: function(e) {
544 e.preventDefault();
500 - var author = React.findDOMNode(this.refs.author).value.trim();
501 - var text = React.findDOMNode(this.refs.text).value.trim();
545 + var author = this.state.author.trim();
546 + var text = this.state.text.trim();
547 if (!text || !author) {
548 return;
549 }
550 // TODO: send request to the server
506 - React.findDOMNode(this.refs.author).value = '';
507 - React.findDOMNode(this.refs.text).value = '';
508 - return;
551 + this.setState({author: '', text: ''});
552 },
553 render: function() {
554 return (
555 <form className="commentForm" onSubmit={this.handleSubmit}>
513 - <input type="text" placeholder="Your name" ref="author" />
514 - <input type="text" placeholder="Say something..." ref="text" />
556 + <input
557 + type="text"
558 + placeholder="Your name"
559 + value={this.state.author}
560 + onChange={this.handleAuthorChange}
561 + />
562 + <input
563 + type="text"
564 + placeholder="Say something..."
565 + value={this.state.text}
566 + onChange={this.handleTextChange}
567 + />
568 <input type="submit" value="Post" />
569 </form>
570 );
@@ -519,16 +572,10 @@ var CommentForm = React.createClass({
572 });
573 ```
574
522 -##### 事件
523 -
524 -React使用驼峰命名规范(camelCase)给组件绑定事件处理器。我们给表单绑定一个`onSubmit`处理器，它在表单提交了合法的输入后清空表单字段。
575 +我们给表单绑定一个`onSubmit`处理器，它在表单提交了合法的输入后清空表单字段。
576
577 在事件中调用`preventDefault()`来阻止浏览器提交表单的默认行为。
578
528 -##### Refs
529 -
530 -我们利用`ref`属性给子组件赋予名字，`this.refs`-引用组件。我们可以在组件上调用 `React.findDOMNode(component)` 获取原生的浏览器DOM元素。
531 -
579 ##### 回调函数作为属性
580
581 当用户提交评论时，我们需要刷新评论列表来包含这条新评论。在`CommentBox`中完成所有逻辑是有道理的，因为`CommentBox` 拥有代表了评论列表的状态(state)。
@@ -536,7 +583,7 @@ React使用驼峰命名规范(camelCase)给组件绑定事件处理器。我们
583 我们需要从子组件传回数据到它的父组件。我们在父组件的`render`方法中以传递一个新的回调函数（`handleCommentSubmit`）到子组件完成这件事，绑定它到子组件的 `onCommentSubmit` 事件上。无论事件什么时候触发，回调函数都将被调用：
584
585 ```javascript{16-18,31}
539 -// tutorial17.js
586 +// tutorial18.js
587 var CommentBox = React.createClass({
588 loadCommentsFromServer: function() {
589 $.ajax({
@@ -573,28 +620,45 @@ var CommentBox = React.createClass({
620 });
621 ```
622
576 -当用户提交表单时，让我们从 `CommentForm` 调用这个回调函数：
623 +既然 `CommentBox` 已经通过 `onCommentSubmit` prop 使回调函数对于 `CommentForm` 可用，`CommentForm` 就可以在用户提交表单时调用回调函数：
624
578 -```javascript{10}
579 -// tutorial18.js
625 +```javascript{19}
626 +// tutorial19.js
627 var CommentForm = React.createClass({
628 + getInitialState: function() {
629 + return {author: '', text: ''};
630 + },
631 + handleAuthorChange: function(e) {
632 + this.setState({author: e.target.value});
633 + },
634 + handleTextChange: function(e) {
635 + this.setState({text: e.target.value});
636 + },
637 handleSubmit: function(e) {
638 e.preventDefault();
583 - var author = React.findDOMNode(this.refs.author).value.trim();
584 - var text = React.findDOMNode(this.refs.text).value.trim();
639 + var author = this.state.author.trim();
640 + var text = this.state.text.trim();
641 if (!text || !author) {
642 return;
643 }
644 this.props.onCommentSubmit({author: author, text: text});
589 - React.findDOMNode(this.refs.author).value = '';
590 - React.findDOMNode(this.refs.text).value = '';
591 - return;
645 + this.setState({author: '', text: ''});
646 },
647 render: function() {
648 return (
649 <form className="commentForm" onSubmit={this.handleSubmit}>
596 - <input type="text" placeholder="Your name" ref="author" />
597 - <input type="text" placeholder="Say something..." ref="text" />
650 + <input
651 + type="text"
652 + placeholder="Your name"
653 + value={this.state.author}
654 + onChange={this.handleAuthorChange}
655 + />
656 + <input
657 + type="text"
658 + placeholder="Say something..."
659 + value={this.state.text}
660 + onChange={this.handleTextChange}
661 + />
662 <input type="submit" value="Post" />
663 </form>
664 );
@@ -605,7 +669,7 @@ var CommentForm = React.createClass({
669 既然现在回调函数已经就绪，我们所需要做的就是提交到服务器然后刷新列表：
670
671 ```javascript{17-28}
608 -// tutorial19.js
672 +// tutorial20.js
673 var CommentBox = React.createClass({
674 loadCommentsFromServer: function() {
675 $.ajax({
@@ -657,8 +721,8 @@ var CommentBox = React.createClass({
721
722 我们的应用现在已经功能完备，但是它感觉很慢，因为在评论出现在列表前必须等待请求完成。我们可以优化添加这条评论到列表以使应用感觉更快。
723
660 -```javascript{17-19,29}
661 -// tutorial20.js
724 +```javascript{17-23,33}
725 +// tutorial21.js
726 var CommentBox = React.createClass({
727 loadCommentsFromServer: function() {
728 $.ajax({
@@ -675,6 +739,10 @@ var CommentBox = React.createClass({
739 },
740 handleCommentSubmit: function(comment) {
741 var comments = this.state.data;
742 + // Optimistically set an id on the new comment. It will be replaced by an
743 + // id generated by the server. In a production application you would likely
744 + // not use Date.now() for this and would have a more robust system in place.
745 + comment.id = Date.now();
746 var newComments = comments.concat([comment]);
747 this.setState({data: newComments});
748 $.ajax({