@samitouri / QOS-React-2 / commits / 7a316ab034

[docs] Sync up zh-CN docs

Sync up with current en docs.

iamchenxin committed Sep 24, 2015 at 22:48 UTC 7a316ab034fe29dcc2eb59b2ca1949ae2f074050

7 files changed +85 -57

docs/docs/02.2-jsx-spread.zh-CN.md

+1 -1

@@ -25,7 +25,7 @@ next: jsx-gotchas-zh-CN.html

26 这样是反模式，因为 React 不能帮你检查属性类型（propTypes）。这样即使你的属性类型有错误也不能得到清晰的错误提示。

28 -Props 应该被当作禁止修改的。修改 props 对象可能会导致预料之外的结果，所以最好不要去修改 props 对象。

28 +Props 应该被认为是不可变的。在别处修改 props 对象可能会导致预料之外的结果，所以原则上这将是一个冻结的对象。

31 ## 展开属性（Spread Attributes）

docs/docs/02.3-jsx-gotchas.zh-CN.md

+2 -2

@@ -46,7 +46,7 @@ HTML 实体可以插入到 JSX 的文本中。

46 <div>{['First ', <span>·</span>, ' Second']}</div>

47 ```

49 -万不得已，可以直接使用原始 HTML。

49 +万不得已，可以直接[插入原始HTML](/react/tips/dangerously-set-inner-html.html)。

51 ```javascript

52 <div dangerouslySetInnerHTML={{'{{'}}__html: 'First · Second'}} />

@@ -60,7 +60,7 @@ HTML 实体可以插入到 JSX 的文本中。

60 <div data-custom-attribute="foo" />

61 ```

63 -以 `aria-` 开头的 [网络无障碍] 属性可以正常使用。

63 +以 `aria-` 开头的 [网络无障碍](http://www.w3.org/WAI/intro/aria) 属性可以正常使用。

65 ```javascript

66 <div aria-hidden={true} />

docs/docs/03-interactivity-and-dynamic-uis.zh-CN.md

+1 -1

@@ -44,7 +44,7 @@ React 里只需把事件处理器（event handler）以骆峰命名（camelCased

45 在幕后，React 做了一些操作来让代码高效运行且易于理解。

47 -**Autobinding:** 在 JavaScript 里创建回调的时候，为了保证 `this` 的正确性，一般都需要显式地绑定方法到它的实例上。有了 React，所有方法被自动绑定到了它的组件实例上。React 还缓存这些绑定方法，所以 CPU 和内存都是非常高效。而且还能减少打字！

47 +**Autobinding:** 在 JavaScript 里创建回调的时候，为了保证 `this` 的正确性，一般都需要显式地绑定方法到它的实例上。在 React，所有方法被自动绑定到了它的组件实例上（除非使用ES6的class符号）。React 还缓存这些绑定方法，所以 CPU 和内存都是非常高效。而且还能减少打字！

49 **事件代理：** React 实际并没有把事件处理器绑定到节点本身。当 React 启动的时候，它在最外层使用唯一一个事件监听器处理所有事件。当组件被加载和卸载时，只是在内部映射里添加或删除事件处理器。当事件触发，React 根据映射来决定如何分发。当映射里处理器时，会当作空操作处理。参考 [David Walsh 很棒的文章](http://davidwalsh.name/event-delegate) 了解这样做高效的原因。

docs/docs/04-multiple-components.zh-CN.md

+4 -22

@@ -57,7 +57,7 @@ React.render(

57 ## 从属关系

59 上面例子中，`Avatar` 拥有 `ProfilePic` 和 `ProfileLink` 的实例。`拥有者` 就是给其它组件设置 `props` 的那个组件。更正式地说，

60 -如果组件 `Y` 在 `render()` 方法是创建了组件 `X`，那么 `Y` 就拥有 `X`。上面讲过，组件不能修改自身的 `props` - 它们总是与它们拥有者设置的保持一致。这是保持用户界面一致性的关键性原则。

60 +如果组件 `Y` 在 `render()` 方法是创建了组件 `X`，那么 `Y` 就拥有 `X`。上面讲过，组件不能修改自身的 `props` - 它们总是与它们拥有者设置的保持一致。这是保持用户界面一致性的基本不变量。

62 把从属关系与父子关系加以区别至关重要。从属关系是 React 特有的，而父子关系简单来讲就是DOM 里的标签的关系。在上一个例子中，`Avatar` 拥有 `div`、`ProfilePic` 和 `ProfileLink` 实例，`div` 是 `ProfilePic` 和 `ProfileLink` 实例的**父级**（但不是拥有者）。

@@ -147,7 +147,8 @@ var MyComponent = React.createClass({

147 );

148 }

149 });

150 -

150 +```

151 +```javascript

152 // 正确 :)

153 var ListItemWrapper = React.createClass({

154 render: function() {

@@ -167,26 +168,7 @@ var MyComponent = React.createClass({

168 });

169 ```

170

170 -也可以传递 object 来做有 key 的子级。object 的 key 会被当作每个组件的 `key`。但是一定要牢记 JavaScript 并不总是保证属性的顺序会被保留。实际情况下浏览器一般会保留属性的顺序，**除了** 使用 32位无符号数字做为 key 的属性。数字型属性会按大小排序并且排在其它属性前面。一旦发生这种情况，React 渲染组件的顺序就是混乱。可能在 key 前面加一个字符串前缀来避免：

171 -

172 -```javascript

173 - render: function() {

174 - var items = {};

175 -

176 - this.props.results.forEach(function(result) {

177 - // 如果 result.id 看起来是一个数字（比如短哈希），那么

178 - // 对象字面量的顺序就得不到保证。这种情况下，需要添加前缀

179 - // 来确保 key 是字符串。

180 - items['result-' + result.id] = <li>{result.text}</li>;

181 - });

182 -

183 - return (

184 - <ol>

185 - {items}

186 - </ol>

187 - );

188 - }

189 -```

171 +也可以传递ReactFragment 对象来做有 key 的子级。详见[Keyed Fragments](create-fragment.html)

172

173 ## 数据流

174

docs/docs/05-reusable-components.zh-CN.md

+49 -2

@@ -26,7 +26,7 @@ React.createClass({

26 optionalString: React.PropTypes.string,

28 // 所有可以被渲染的对象：数字，

29 - // 字符串，DOM 元素或包含这些类型的数组。

29 + // 字符串，DOM 元素或包含这些类型的数组(or fragment) 。

30 optionalNode: React.PropTypes.node,

32 // React 元素

@@ -150,7 +150,7 @@ var SetIntervalMixin = {

150 this.intervals.push(setInterval.apply(null, arguments));

151 },

152 componentWillUnmount: function() {

153 - this.intervals.map(clearInterval);

153 + this.intervals.forEach(clearInterval);

154 }

155 };

156

@@ -181,3 +181,50 @@ React.render(

181 ```

182

183 关于 mixin 值得一提的优点是，如果一个组件使用了多个 mixin，并用有多个 mixin 定义了同样的生命周期方法（如：多个 mixin 都需要在组件销毁时做资源清理操作），所有这些生命周期方法都保证会被执行到。方法执行顺序是：首先按 mixin 引入顺序执行 mixin 里方法，最后执行组件内定义的方法。

184 +

185 +## ES6 Classes

186 +

187 +你也可以以一个简单的JavaScript 类来定义你的React classes。使用ES6 class的例子:

188 +

189 +```javascript

190 +class HelloMessage extends React.Component {

191 + render() {

192 + return <div>Hello {this.props.name}</div>;

193 + }

194 +}

195 +React.render(<HelloMessage name="Sebastian" />, mountNode);

196 +```

197 +

198 +API近似于 `React.createClass` 除了 `getInitialState`。你应该在构造函数里设置你的`state`，而不是提供一个单独的 `getInitialState` 方法。

199 +

200 +另一个不同是 `propTypes` 和 `defaultProps` 在构造函数而不是class body里被定义为属性。

201 +

202 +```javascript

203 +export class Counter extends React.Component {

204 + constructor(props) {

205 + super(props);

206 + this.state = {count: props.initialCount};

207 + }

208 + tick() {

209 + this.setState({count: this.state.count + 1});

210 + }

211 + render() {

212 + return (

213 + <div onClick={this.tick.bind(this)}>

214 + Clicks: {this.state.count}

215 + </div>

216 + );

217 + }

218 +}

219 +Counter.propTypes = { initialCount: React.PropTypes.number };

220 +Counter.defaultProps = { initialCount: 0 };

221 +```

222 +

223 +### 无自动绑定

224 +

225 +方法遵循正式的ES6 class的语义，意味着它们不会自动绑定`this`到实例上。你必须显示的使用`.bind(this)` or [箭头函数](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Functions/Arrow_functions) `=>`.

226 +

227 +### 没有 Mixins

228 +

229 +不幸的是ES6的发布没有任何mixin的支持。因此，当你在ES6 classes下使用React时不支持mixins。作为替代，我们正在努力使它更容易支持这些用例不依靠mixins。

230 +

docs/docs/06-transferring-props.zh-CN.md

+6 -4

@@ -11,18 +11,17 @@ React 里有一个非常常用的模式就是对组件做一层抽象。组件

11 可以使用 [JSX 展开属性](/react/docs/jsx-spread-zh-CN.html) 来合并现有的 props 和其它值：

13 ```javascript

14 -return <Component {...this.props} more="values" />;

14 +<Component {...this.props} more="values" />

15 ```

17 如果不使用 JSX，可以使用一些对象辅助方法如 ES6 的 `Object.assign` 或 Underscore `_.extend`。

19 ```javascript

20 -return Component(Object.assign({}, this.props, { more: 'values' }));

20 +React.createElement(Component, Object.assign({}, this.props, { more: 'values' }));

21 ```

23 下面的教程介绍一些最佳实践。使用了 JSX 和 ES7 的还在试验阶段的特性。

25 -

25 ## 手动传递

27 大部分情况下你应该显式地向下传递 props。这样可以确保只公开你认为是安全的内部 API 的子集。

@@ -48,9 +47,12 @@ React.render(

48 但 `name` 这个属性怎么办？还有 `title`、`onMouseOver` 这些 props？

51 -

50 ## 在 JSX 里使用 `...` 传递

52 +> 注意:

53 +>

54 +> 在下面的例子中，`--harmony ` 标志是必须的因为这个语法是ES7的实验性语法。如果用浏览器中的JSX转换器，以 `<script type="text/jsx;harmony=true">`简单的打开你脚本就行了。详见[Rest and Spread Properties ...](/react/docs/transferring-props.html#rest-and-spread-properties-...)

55 +

56 有时把所有属性都传下去是不安全或啰嗦的。这时可以使用 [解构赋值](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) 中的剩余属性特性来把未知属性批量提取出来。

58 列出所有要当前使用的属性，后面跟着 `...other`。

docs/docs/07-forms.zh-CN.md

+22 -25

@@ -27,7 +27,11 @@ next: working-with-the-browser-zh-CN.html

27 * `<option>` 的 `selected` 状态改变时。

29 和所有 DOM 事件一样，所有的 HTML 原生组件都支持 `onChange` 属性，而且可以用来监听冒泡的 `change` 事件。

30 -

30 +

31 +> 注意:

32 +>

33 +> 对于 `<input>` and `<textarea>`， `onChange` 替代 — 一般应该用来替代 — the DOM's 内建的 [`oninput`](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/oninput) 事件处理。

34 +

36 ## 受限组件

@@ -64,6 +68,10 @@ next: working-with-the-browser-zh-CN.html

69 上面的代码接受用户输入，并截取前 140 个字符。

71 +### 复选框与单选按钮的潜在问题

72 +

73 +当心，在力图标准化复选框与单选按钮的变换处理中，React使用`click` 事件代替 `change` 事件。在大多数情况下它们表现的如同预期，除了在`change` handler中调用`preventDefault` 。`preventDefault` 阻止了浏览器视觉上更新输入，即使`checked`被触发。变通的方式是要么移除`preventDefault`的调用，要么把`checked` 的触发放在一个`setTimeout`里。

74 +

76 ## 不受限组件

@@ -77,6 +85,8 @@ next: working-with-the-browser-zh-CN.html

86 上面的代码将渲染出一个空值的输入框，用户输入将立即反应到元素上。和受限元素一样，使用 `onChange` 事件可以监听值的变化。

88 +### 默认值

89 +

90 如果想给组件设置一个非空的初始值，可以使用 `defaultValue` 属性。例如：

92 ```javascript

@@ -85,40 +95,27 @@ next: working-with-the-browser-zh-CN.html

95 }

96 ```

88 -上面的代码渲染出来的元素和**受限组件**一样有一个初始值，但这个值用户可以改变并会反应到界面上。

98 +这个例子会像上面的**Controlled Components** 例子一样运行。

90 -同样地，类型为 `radio`、`checkbox` 的`<input>` 支持 `defaultChecked` 属性， `<select>` 支持 `defaultValue` 属性。

91 -

92 -```javascript

93 - render: function() {

94 - return (

95 - <div>

96 - <input type="radio" name="opt" defaultChecked /> Option 1

97 - <input type="radio" name="opt" /> Option 2

98 - <select defaultValue="C">

99 - <option value="A">Apple</option>

100 - <option value="B">Banana</option>

101 - <option value="C">Cranberry</option>

102 - </select>

103 - </div>

104 - );

105 - }

106 -```

100 +同样的， `<input>` 支持 `defaultChecked` 、 `<select>` 支持 `defaultValue`.

101

102 +> 注意:

103 +>

104 +> `defaultValue` 和 `defaultChecked` props 只能在内部渲染时被使用。如果你需要在随后的渲染更新值, 你需要使用 [受限组件](#受限组件).

105 +

106

107 ## 高级主题

108 +

109

110 ### 为什么使用受限组件？

111

113 -在 React 中使用诸如 `<input>` 的表单组件时，遇到了一个在传统 HTML 中没有的挑战。

114 -

115 -比如下面的代码：

112 +在 React 中使用诸如 `<input>` 的表单组件时，遇到了一个在传统 HTML 中没有的挑战。比如下面的代码：

113

114 ```html

115 <input type="text" name="title" value="Untitled" />

116 ```

117

121 -在 HTML 中将渲染初始值为 `Untitled` 的输入框。用户改变输入框的值时，节点的 `value` 属性（*property*）将随之变化，但是 `node.getAttribute('value')` 还是会返回初始设置的值 `Untitled`.

118 +在 HTML 中将渲染 *初始值* 为 `Untitled` 的输入框。用户改变输入框的值时，节点的 `value` 属性( *property*)将随之变化，但是 `node.getAttribute('value')` 还是会返回初始设置的值 `Untitled`.

119

120 与 HTML 不同，React 组件必须在任何时间点描绘视图的状态，而不仅仅是在初始化时。比如在 React 中：

121

@@ -128,7 +125,7 @@ next: working-with-the-browser-zh-CN.html

125 }

126 ```

127

131 -该方法在任何时间点渲染组件以后，输入框的值就应该*始终*为 `Untitled`。

128 +该方法在任何时间点渲染组件以后，输入框的值就应该 *始终* 为 `Untitled`。

129

130

131 ### 为什么 `<textarea>` 使用 `value` 属性？

@@ -146,7 +143,7 @@ next: working-with-the-browser-zh-CN.html

143 <textarea name="description" value="This is a description." />

144 ```

145

149 -如果*非要**使用子节点，效果和使用 `defaultValue` 一样。

146 +如果 *非要* 使用子节点，效果和使用 `defaultValue` 一样。

147

148

149 ### 为什么 `<select>` 使用 `value` 属性