From badc15e3c045a59adc3fe1acb76c7c98015e8927 Mon Sep 17 00:00:00 2001 From: iamchenxin Date: Thu, 24 Dec 2015 13:57:07 +0800 Subject: [PATCH] update zh-docs (v0.14.3+) --- .gitignore | 1 + docs/docs/10.10-shallow-compare.zh-CN.md | 32 +++ .../10.2-form-input-binding-sugar.zh-CN.md | 117 ++++++++++ .../10.3-class-name-manipulation.zh-CN.md | 11 + docs/docs/12-context.zh-CN.md | 173 ++++++++++++++ docs/docs/conferences.zh-CN.md | 29 +++ docs/docs/getting-started.zh-CN.md | 44 ++-- docs/docs/ref-01-top-level-api.zh-CN.md | 136 ++++++----- docs/docs/ref-02-component-api.zh-CN.md | 30 +-- docs/docs/ref-03-component-specs.zh-CN.md | 217 ++++++++++++++++++ docs/docs/ref-04-tags-and-attributes.zh-CN.md | 90 ++++++++ docs/docs/ref-05-events.zh-CN.md | 50 +++- docs/docs/ref-06-dom-differences.zh-CN.md | 16 ++ ...ref-07-special-non-dom-attributes.zh-CN.md | 13 ++ docs/docs/ref-10-glossary.zh-CN.md | 193 ++++++++++++++++ docs/docs/thinking-in-react.zh-CN.md | 2 +- docs/docs/videos.zh-CN.md | 173 ++++++++++++++ 17 files changed, 1233 insertions(+), 94 deletions(-) create mode 100644 docs/docs/10.10-shallow-compare.zh-CN.md create mode 100644 docs/docs/10.2-form-input-binding-sugar.zh-CN.md create mode 100644 docs/docs/10.3-class-name-manipulation.zh-CN.md create mode 100644 docs/docs/12-context.zh-CN.md create mode 100644 docs/docs/conferences.zh-CN.md create mode 100644 docs/docs/ref-03-component-specs.zh-CN.md create mode 100644 docs/docs/ref-04-tags-and-attributes.zh-CN.md create mode 100644 docs/docs/ref-06-dom-differences.zh-CN.md create mode 100644 docs/docs/ref-07-special-non-dom-attributes.zh-CN.md create mode 100644 docs/docs/ref-10-glossary.zh-CN.md create mode 100644 docs/docs/videos.zh-CN.md diff --git a/.gitignore b/.gitignore index 927b40333d0db..348b88dc414a4 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,4 @@ chrome-user-data *.sublime-workspace .idea *.iml +.vscode diff --git a/docs/docs/10.10-shallow-compare.zh-CN.md b/docs/docs/10.10-shallow-compare.zh-CN.md new file mode 100644 index 0000000000000..6ed9a161bb7c7 --- /dev/null +++ b/docs/docs/10.10-shallow-compare.zh-CN.md @@ -0,0 +1,32 @@ +--- +id: shallow-compare-zh-CN +title: 浅比较 +permalink: shallow-compare-zh-CN.html +prev: perf-zh-CN.html +next: advanced-performance-zh-CN.html +--- + +`shallowCompare` 是一个辅助函数 在以ES6类使用React时，完成和 `PureRenderMixin` 相同的功能。 + +如果你的React组件的绘制函数是 “干净的” （换句话说，它在给定的 props 和 state 下绘制相同的结果）,你可以使用这个辅助函数以在某些情况下提升性能。 + +例如: + +```js +var shallowCompare = require('react-addons-shallow-compare'); +export class SampleComponent extends React.Component { + shouldComponentUpdate(nextProps, nextState) { + return shallowCompare(this, nextProps, nextState); + } + + render() { + return
foo
; + } +} +``` + +`shallowCompare` 对当前的 `props` 和 `nextProps`对象 执行一个浅的相等检查，同样对于 `state` 和 `nextState`对象。 +它 通过迭代比较对象的keys 并在 对象的key值不严格相等时返回false 实现此功能. + +`shallowCompare` 返回 `true` 如果对 props 或 state的浅比较失败，因此组件应该更新。 +`shallowCompare` 返回 `false` 如果对 props 或 state的浅比较都通过了，因此组件不应该更新。 diff --git a/docs/docs/10.2-form-input-binding-sugar.zh-CN.md b/docs/docs/10.2-form-input-binding-sugar.zh-CN.md new file mode 100644 index 0000000000000..2828415187ceb --- /dev/null +++ b/docs/docs/10.2-form-input-binding-sugar.zh-CN.md @@ -0,0 +1,117 @@ +--- +id: two-way-binding-helpers-zh-CN +title: 双向绑定辅助 +permalink: two-way-binding-helpers-zh-CN.html +prev: animation-zh-CN.html +next: test-utils-zh-CN.html +--- + +`ReactLink` 是一个用React表达双向绑定的简单方法。 + +> 注意： +> +> 如果你刚学这个框架，注意 `ReactLink` 对大多数应用是不需要的，应该慎重的使用。 + +在React里，数据单向流动： 从拥有者到子级。这是因为数据只单向流动[the Von Neumann model of computing](https://en.wikipedia.org/wiki/Von_Neumann_architecture)。你可以把它想象为 “单向数据绑定”。 + +然而，有很多应用需要你去读某些数据并回流他们到你的程序。例如，当开发forms，你会常常想更新一些React `state` 当你收到用户输入的时候。或者也许你想在JavaScript完成布局并相应一些DOM元素大小的变化。 + +在React里，你可以用监听 "change" 事件来实现它，从你的数据源（通常是DOM）读取并在你的某个组件调用 `setState()` 。明确的"Closing the data flow loop" 致使了更容易理解和维护的程序。更多信息见[our forms documentation](/react/docs/forms.html). + +双向绑定 -- 隐含的强迫DOM里的某些值总是和某些React `state` 同步 -- 简洁并支持大量多样的应用。 我们提供了 `ReactLink`：设置如上描述的通用数据回流模式的语法糖，或者 "linking" 某些数据结构到 React `state`. + +> 注意: +> +> `ReactLink` 只是一层对 `onChange`/`setState()` 模式的薄包装。它没有根本性的改变你的React应用里数据如何流动。 + +## ReactLink: 之前和之后 + +这里有一个简单的 不用 `ReactLink` 的 form 例子： + +```javascript +var NoLink = React.createClass({ + getInitialState: function() { + return {message: 'Hello!'}; + }, + handleChange: function(event) { + this.setState({message: event.target.value}); + }, + render: function() { + var message = this.state.message; + return ; + } +}); +``` + +这个工作的很好并且数据如何流动很清晰，然而，当有大量的 form fields时，可能会有些冗长。让我们使用 `ReactLink` 来节省我们的输入： + +```javascript{4,9} +var LinkedStateMixin = require('react-addons-linked-state-mixin'); + +var WithLink = React.createClass({ + mixins: [LinkedStateMixin], + getInitialState: function() { + return {message: 'Hello!'}; + }, + render: function() { + return ; + } +}); +``` + +`LinkedStateMixin` 添加了一个 `linkState()` 方法到你的React组件。`linkState()` 返回一个 `ReactLink` 包含当前React state值的对象和一个改变它的回调函数。 + +`ReactLink` 对象可以作为props在树中上下传递，所以很容易（显示的）在深层次的组件和高层次的state之间 设置双向绑定。 + +注意 checkboxes 有一个关于他们 `value` 属性的特殊行为，这个行为是 如果checkbox被选中 值会在表单提交时被发送。 `value` 不会 checkbox 选中或是不选中时更新。对于checkboxes，你应该用`checkedLink` 代替 `valueLink`: +``` + +``` + +## 引擎盖下 + +There are two sides to `ReactLink`: the place where you create the `ReactLink` instance and the place where you use it. To prove how simple `ReactLink` is, let's rewrite each side separately to be more explicit. + +### ReactLink Without LinkedStateMixin + +```javascript{5-7,9-12} +var WithoutMixin = React.createClass({ + getInitialState: function() { + return {message: 'Hello!'}; + }, + handleChange: function(newValue) { + this.setState({message: newValue}); + }, + render: function() { + var valueLink = { + value: this.state.message, + requestChange: this.handleChange + }; + return ; + } +}); +``` + +As you can see, `ReactLink` objects are very simple objects that just have a `value` and `requestChange` prop. And `LinkedStateMixin` is similarly simple: it just populates those fields with a value from `this.state` and a callback that calls `this.setState()`. + +### ReactLink Without valueLink + +```javascript +var LinkedStateMixin = require('react-addons-linked-state-mixin'); + +var WithoutLink = React.createClass({ + mixins: [LinkedStateMixin], + getInitialState: function() { + return {message: 'Hello!'}; + }, + render: function() { + var valueLink = this.linkState('message'); + var handleChange = function(e) { + valueLink.requestChange(e.target.value); + }; + return ; + } +}); +``` + +The `valueLink` prop is also quite simple. It simply handles the `onChange` event and calls `this.props.valueLink.requestChange()` and also uses `this.props.valueLink.value` instead of `this.props.value`. That's it! diff --git a/docs/docs/10.3-class-name-manipulation.zh-CN.md b/docs/docs/10.3-class-name-manipulation.zh-CN.md new file mode 100644 index 0000000000000..48b38d9090667 --- /dev/null +++ b/docs/docs/10.3-class-name-manipulation.zh-CN.md @@ -0,0 +1,11 @@ +--- +id: class-name-manipulation-zh-CN +title: 类名操纵 +permalink: class-name-manipulation-zh-CN.html +prev: two-way-binding-helpers-zh-CN.html +next: test-utils-zh-CN.html +--- + +> NOTE: +> +> 此模块已被弃用; 用 [JedWatson/classnames](https://github.com/JedWatson/classnames) 替代. diff --git a/docs/docs/12-context.zh-CN.md b/docs/docs/12-context.zh-CN.md new file mode 100644 index 0000000000000..c6da13bad6fb7 --- /dev/null +++ b/docs/docs/12-context.zh-CN.md @@ -0,0 +1,173 @@ +--- +id: context-zh-CN +title: Context +permalink: context-zh-CN.html +prev: advanced-performance-zh-CN.html +--- + +React最大的优势之一是他很容易从你的React组件里跟踪数据流动。当你看着一个组件，你可以很容易准确看出哪个props被传入，这让你的APP很容易推断。 + +偶尔，你想通过组件树传递数据，而不在每一级上手工下传prop，React的 "context" 让你做到这点。 + +＞　注意： +＞　 +＞　Context是一个先进的实验性特性．这个 API 很可能在未来版本变化. +> +> 大多数应用将不会需要用到 context. 尤其是如果你刚开始用React,你很可能不会想用 context.使用 context 将会使你的代码很难理解因为它让数据流不清晰.它类似于在你的应用里使用全局变量传递state. +> +> **如果你必须使用 context ,保守的使用它** +> +> 不论你正在创建一个应用或者是库,试着分离你对 context 的使用到一个小区域,并尽可能避免直接使用 context API,以便在API变动时容易升级. + +## 从树里自动传递info + +假设你有一个这样的结构: + +```javascript +var Button = React.createClass({ + render: function() { + return ( + + ); + } +}); + +var Message = React.createClass({ + render: function() { + return ( +
+ {this.props.text} +
+ ); + } +}); + +var MessageList = React.createClass({ + render: function() { + var color = "purple"; + var children = this.props.messages.map(function(message) { + return ; + }); + return
{children}
; + } +}); +``` + +在这里例子里,我们手工穿透一个 `color` prop 以便于恰当格式化 `Button` 和 `Message` 组件.主题是一个很好的例子,当你可能想整个子树都可以访问一部分信息时(比如color). 使用 context 我们可以自动传过这个树: + +```javascript{2-4,7,18,25-30,33} +var Button = React.createClass({ + contextTypes: { + color: React.PropTypes.string + }, + render: function() { + return ( + + ); + } +}); + +var Message = React.createClass({ + render: function() { + return ( +
+ {this.props.text} +
+ ); + } +}); + +var MessageList = React.createClass({ + childContextTypes: { + color: React.PropTypes.string + }, + getChildContext: function() { + return {color: "purple"}; + }, + render: function() { + var children = this.props.messages.map(function(message) { + return ; + }); + return
{children}
; + } +}); +``` + +通过添加 `childContextTypes` 和 `getChildContext` 到 `MessageList` ( context 提供),React下传信息到子树中的任何组件(在这个例子中, `Button`可以由定义 `contextTypes`来访问它). + +如果 `contextTypes` 没有定义,那么 `this.context` 将是一个空对象. + +## 父子耦合 + +Context 同样可以使你构建这样的 APT: + +```javascript + + aubergine + butternut squash + clementine + +``` + +通过在 `Menu` 组件下传相关的信息,每个 `MenuItem` 可以与包含他们的 `Menu` 组件沟通. + +**在你用这个API构建组件以前,考虑一下是否有清晰的替代方案** 我们 喜欢像这样简单的用数组传递items: + +```javascript + +``` + +记住你同样可以在props里传递整个React组件,如果你想. + +## 在生命周期方法里引用 context + +如果 `contextTypes` 在一个组件中定义,接下来的生命周期方法会收到一个额外的参数, `context` 对象: + +```javascript +void componentWillReceiveProps( + object nextProps, object nextContext +) + +boolean shouldComponentUpdate( + object nextProps, object nextState, object nextContext +) + +void componentWillUpdate( + object nextProps, object nextState, object nextContext +) + +void componentDidUpdate( + object prevProps, object prevState, object prevContext +) +``` + +## 在无状态函数组件里引用 context + +无状态函数同样能够引用 `context` 如果 `contextTypes` 被定义为函数的属性.下面的代码展示了被写为无状态函数组件的 `Button` 组件. + +```javascript +function Button(props, context) { + return ( + + ); +} +Button.contextTypes = {color: React.PropTypes.string}; +``` + +## 什么时候不用 context + +正像全局变量是在写清晰代码时最好要避免的,你应该在大多数情况下避免使用context. 特别是,在用它来"节省输入"和代替显示传入props时要三思. + +context最好的使用场景是隐式的传入登录的用户,当前的语言,或者主题信息.要不然所有这些可能就是全局变量,但是context让你限定他们到一个单独的React树里. + +不要用context在组件里传递你的模型数据.通过树显示的传递你的数据更容易理解.使用context使你的组件更耦合和不可复用,因为 依赖于他们在哪里渲染,他们会表现不同的行为. + +## 已知的限制 + +如果一个由组件提供的context值变动,使用那个值的子级不会更新,如果一个直接的父级从 `shouldComponentUpdate` 返回 `false` .详见 issue [#2517](https://github.com/facebook/react/issues/2517) . diff --git a/docs/docs/conferences.zh-CN.md b/docs/docs/conferences.zh-CN.md new file mode 100644 index 0000000000000..cc1666d92cb75 --- /dev/null +++ b/docs/docs/conferences.zh-CN.md @@ -0,0 +1,29 @@ +--- +id: conferences-zh-CN +title: 会议 +permalink: conferences-zh-CN.html +prev: thinking-in-react-zh-CN.html +next: videos-zh-CN.html +--- + +### React.js Conf 2015 +一月 28 & 29 + +[Website](http://conf.reactjs.com/) - [Schedule](http://conf.reactjs.com/schedule.html) - [Videos](https://www.youtube-nocookie.com/playlist?list=PLb0IAmt7-GS1cbw4qonlQztYV1TAW0sCr) + + + +### ReactEurope 2015 +七月 2 & 3 + +[Website](http://www.react-europe.org/) - [Schedule](http://www.react-europe.org/#schedule) + +### Reactive 2015 +十一月 2-4 + +[Website](https://reactive2015.com/) - [Schedule](https://reactive2015.com/schedule_speakers.html#schedule) + +### ReactEurope 2016 +六月 2 & 3 + +[Website](http://www.react-europe.org/) - [Schedule](http://www.react-europe.org/#schedule) diff --git a/docs/docs/getting-started.zh-CN.md b/docs/docs/getting-started.zh-CN.md index 685fa100defa7..fba40104e3711 100644 --- a/docs/docs/getting-started.zh-CN.md +++ b/docs/docs/getting-started.zh-CN.md @@ -13,7 +13,6 @@ redirect_from: "docs/index-zh-CN.html" * **[React JSFiddle](https://jsfiddle.net/reactjs/69z2wepo/)** * [React JSFiddle without JSX](https://jsfiddle.net/reactjs/5vjqabv3/) - ## 通过 npm 使用 React 我们建议在 React 中使用 CommonJS 模块系统，比如 [browserify](http://browserify.org/) 或 [webpack](https://webpack.github.io/)。使用 [`react`](https://www.npmjs.com/package/react) 和 [`react-dom`](https://www.npmjs.com/package/react-dom) npm 包. @@ -29,23 +28,32 @@ ReactDOM.render( ); ``` +要用 browserify 安装 React DOM 和构建你的包。 + +```sh +$ npm install --save react react-dom babelify babel-preset-react +$ browserify -t [ babelify --presets [ react ] ] main.js -o bundle.js +``` -在安装 browserify 之后安装 React DOM 和构建你的应用包。 +要用 webpack 安装 React DOM 和构建你的包: ```sh -$ npm install --save react react-dom -$ browserify -t babelify main.js -o bundle.js +$ npm install --save react react-dom babel-preset-react +$ webpack ``` -## 不使用 npm 快速开始 +> 注意: +> +> 如果你正在使用 ES2015, 你将要使用 `babel-preset-es2015` 包. + +## 不用 npm 的快速开始 -If you're not ready to use npm yet, you can download the starter kit which includes prebuilt copies of React and React DOM. -如果你没有做好使用 npm 的准备，你可以下载包含了 React 和 ReactDOM 预生成包的入门教程包。 +如果你现在还没准备要使用npm,你可以下载这个已经包含了预构建的 React 和 React DOM 拷贝的入门套件.
- 下载入门教程 {{site.react_version}} + 下载入门套件 {{site.react_version}}
@@ -96,21 +104,24 @@ ReactDOM.render( ### 离线转换 -先安装[Babel](http://babeljs.io/)命令行工具（依赖 [npm](https://www.npmjs.com/)）： +先安装[Babel](http://babeljs.io/)命令行工具（需要 [npm](https://www.npmjs.com/)）： ``` -npm install --global babel +npm install --global babel-cli +npm install babel-preset-react ``` 然后把你的 `src/helloworld.js` 文件转成标准的 JavaScript: ``` -babel src --watch --out-dir build - +babel --presets react src --watch --out-dir build ``` -`build/helloworld.js` 会在你对文件进行修改时自动生成。 阅读 [Babel CLI 文档](http://babeljs.io/docs/usage/cli/) 了解高级用法。 +> 注意: +> +> 如果你正在使用 ES2015, 你将需要使用 `babel-preset-es2015` 包. +`build/helloworld.js` 会在你对文件进行修改时自动生成。 阅读 [Babel CLI 文档](http://babeljs.io/docs/usage/cli/) 了解高级用法。 ```javascript{2} ReactDOM.render( @@ -121,14 +132,15 @@ ReactDOM.render( 对照下面更新你的 HTML 代码 -```html{7,11} +```html{8,12} Hello React! - + +
@@ -137,8 +149,6 @@ ReactDOM.render( ``` - - ## 下一步 去看看[入门教程](/react/docs/tutorial.html) 和入门教程包 `examples` 目录下的其它例子学习更多。 diff --git a/docs/docs/ref-01-top-level-api.zh-CN.md b/docs/docs/ref-01-top-level-api.zh-CN.md index eb45c81ccc395..cc1e8ef643363 100644 --- a/docs/docs/ref-01-top-level-api.zh-CN.md +++ b/docs/docs/ref-01-top-level-api.zh-CN.md @@ -69,123 +69,143 @@ factoryFunction createFactory( 返回一个生成给定类型的 ReactElements 的函数。如同 `React.createElement`，type 参数既可以是一个 html 标签名字符串（例如. “div”，“span”，等等），也可以是一个 `ReactClass` 。 - - -### React.render +### React.isValidElement ```javascript -ReactComponent render( - ReactElement element, - DOMElement container, - [function callback] -) +boolean isValidElement(* object) ``` -渲染一个 ReactElement 到 DOM 里提供的 `容器（container）`中，并返回一个对组件的引用。 +验证对象是否是一个 ReactElement。 -如果 ReactElement 之前被渲染到了 `container` 中，这将对它执行一次更新，并仅变动需要变动的 DOM 来反映最新的 React 组件。 -如果提供了可选的回调函数，则该函数将会在组件渲染或者更新之后被执行。 +### React.DOM -> 注意: -> -> `React.render()` 控制你传入的 container 节点的内容。 -> 当初次调用时，任何现存于内的 DOM 元素将被替换。 -> 其后的调用使用 React的 diffing 算法来有效率的更新。 -> -> `React.render()` 不会修改 container 节点（只修改 container 的子级）。 -> 将来，也许能够直接插入一个组件到已经存在的 DOM 节点而不覆盖 -> 现有的子级。 +`React.DOM` 用 `React.createElement` 为 DOM 组件提供了便利的包装器。该方式应该只在不使用 JSX 的时使用。例如，`React.DOM.div(null, 'Hello World!')`。 -### React.unmountComponentAtNode +### React.PropTypes -```javascript -boolean unmountComponentAtNode(DOMElement container) -``` +`React.PropTypes` 包含了能与 组件的`propTypes` 对象一起使用的类型，用以验证传入你的组件的 props。更多有关 `propTypes` 的信息，请见 [可重用组件](/react/docs/reusable-components-zh-CN.html)。 -从 DOM 中移除已经挂载的 React 组件，并清除它的事件处理器和 state。如果在 container 中没有组件被挂载，调用此函数将什么都不做。如果组件被卸载返回 `true`，如果没有组件被卸载返回 `false`。 +### React.Children -### React.renderToString +`React.Children` 为处理 `this.props.children` 这个不透明的数据结构提供了工具。 + +#### React.Children.map ```javascript -string renderToString(ReactElement element) +array React.Children.map(object children, function fn [, object thisArg]) ``` -把 ReactElement 渲染为它原始的 HTML 。这应该仅在服务器端使用。React 将会返回一个 HTML 字符串。你可以用这种方法在服务器端生成 HTML，然后在初始请求下传这些标记，以获得更快的页面加载速度及允许搜索引擎抓取页面（便于 SEO）。 +在每一个包含在 `children` 中的直接子级上调用 `fn` ，`fn`中的 `this` 设置为 `thisArg`。如果 `children` 是一个嵌套的对象或者数组，它将被遍历：不会传入容器对象到 `fn` 中。如果 children 是 `null` 或者 `undefined`，则返回 `null` 或者 `undefined` 而不是一个空数组。 -如果在一个在已经有了这种服务器预渲染标记的节点上面调用 `React.render()`，React 将会维护该节点，仅绑定事件处理器，让你有一个非常高效的初次加载体验。 +#### React.Children.forEach +```javascript +React.Children.forEach(object children, function fn [, object thisArg]) +``` -### React.renderToStaticMarkup +类似 `React.Children.map()`，但是不返回数组。 + +#### React.Children.count ```javascript -string renderToStaticMarkup(ReactElement element) +number React.Children.count(object children) ``` -类似于 `renderToString` ，除了不创建额外的 DOM 属性，比如 `data-react-id`，这仅在 React 内部使用的属性。如果你想用 React 做一个简单的静态页面生成器，这是很有用的，因为去除额外的属性能够节省很多字节。 - +返回 `children` 中的组件总数，相等于传递给 `map` 或者 `forEach` 的回调函数应被调用次数。 -### React.isValidElement +#### React.Children.only ```javascript -boolean isValidElement(* object) +object React.Children.only(object children) ``` -验证对象是否是一个 ReactElement。 - +返回 `children` 中仅有的子级。否则抛出异常。 -### React.findDOMNode +#### React.Children.toArray ```javascript -DOMElement findDOMNode(ReactComponent component) +array React.Children.toArray(object children) ``` -如果这个组件已经被挂载到了 DOM，它返回相应的浏览器原生的 DOM 元素。这个方法对于读取 DOM 的值很有用，比如表单域的值和执行 DOM 的测量。如果 `render` 返回 `null` 或者 `false`， `findDOMNode` 返回 `null`. +以赋key给每个child的平坦的数组形式,返回不透明的 `children` 数据结构.如果你想操纵你的渲染方法的子级的合集这很有用,尤其如果你想在 `this.props.children` 传下之前渲染或者切割. -### React.DOM +## ReactDOM -`React.DOM` 用 `React.createElement` 为 DOM 组件提供了便利的包装器。该方式应该只在不使用 JSX 的时使用。例如，`React.DOM.div(null, 'Hello World!')`。 +`react-dom` 包提供了 具体的DOM方法,这些方法可以在你的app的顶层作为一个你需要时脱离React模式的安全舱口 被使用.你的大多数组件不需要使用这个模块. +### ReactDOM.render -### React.PropTypes +```javascript +ReactComponent render( + ReactElement element, + DOMElement container, + [function callback] +) +``` -`React.PropTypes` 包含了能与 组件的`propTypes` 对象一起使用的类型，用以验证传入你的组件的 props。更多有关 `propTypes` 的信息，请见 [可重用组件](/react/docs/reusable-components-zh-CN.html)。 +渲染一个 ReactElement 到 DOM 里提供的 `容器（container）`中，并返回一个对 组件(或者返回 `null` 对于 [无状态组件](/react/docs/reusable-components.html#stateless-functions)) 的[引用](/react/docs/more-about-refs.html) +如果 ReactElement 之前被渲染到了 `container` 中，这将对它执行一次更新，并仅变动需要变动的 DOM 来反映最新的 React 组件。 -### React.Children +如果提供了可选的回调函数，则该函数将会在组件渲染或者更新之后被执行。 -`React.Children` 为处理 `this.props.children` 这个不透明的数据结构提供了工具。 +> 注意: +> +> `ReactDOM.render()` 控制你传入的 container 节点的内容。 +> 当初次调用时，任何现存于内的 DOM 元素将被替换。 +> 其后的调用使用 React的 diffing 算法来有效率的更新。 +> +> `ReactDOM.render()` 不会修改 container 节点（只修改 container 的子级）。 +> 将来，也许能够直接插入一个组件到已经存在的 DOM 节点而不覆盖 +> 现有的子级。 -#### React.Children.map + +### ReactDOM.unmountComponentAtNode ```javascript -object React.Children.map(object children, function fn [, object thisArg]) +boolean unmountComponentAtNode(DOMElement container) ``` -在每一个包含在 `children` 中的直接子级上调用 `fn` ，`fn`中的 `this` 设置为 `thisArg`。如果 `children` 是一个嵌套的对象或者数组，它将被遍历：不会传入容器对象到 `fn` 中。如果 children 是 `null` 或者 `undefined`，则返回 `null` 或者 `undefined` 而不是一个空对象。 +从 DOM 中移除已经挂载的 React 组件，并清除它的事件处理器和 state。如果在 container 中没有组件被挂载，调用此函数将什么都不做。如果组件被卸载返回 `true`，如果没有组件被卸载返回 `false`。 -#### React.Children.forEach + +### ReactDOM.findDOMNode ```javascript -React.Children.forEach(object children, function fn [, object thisArg]) +DOMElement findDOMNode(ReactComponent component) ``` +如果这个组件已经被挂载到了 DOM，它返回相应的浏览器原生的 DOM 元素。这个方法对于读取 DOM 的值很有用，比如表单域的值和执行 DOM 的测量。**在大多数情况下,你可以连接一个ref到DOM节点上,并避免使用 `findDOMNode`** 如果 `render` 返回 `null` 或者 `false`， `findDOMNode` 返回 `null`. -类似 `React.Children.map()`，但是不返回对象。 +> 注意: +> +> `findDOMNode()` 是一个用来访问底层DOM节点的安全舱口.大多数情况下,使用这个安全舱口是不被鼓励的,因为它穿破了组件的抽象. +> +> `findDOMNode()` 只在已挂载的组件上工作(即是,已经被放置到DOM里的组件).如果你尝试在没有被挂载的组件上调用这个方法(比如在 一个没有被创建的组件的`render()`里 调用 `findDOMNode()` )会抛出一个异常. +> +> `findDOMNode()` 不能用在无状态组件. -#### React.Children.count +## ReactDOMServer + +`react-dom/server` 允许你在服务器上渲染你的组件. + +### ReactDOMServer.renderToString ```javascript -number React.Children.count(object children) +string renderToString(ReactElement element) ``` -返回 `children` 中的组件总数，相等于传递给 `map` 或者 `forEach` 的回调函数应被调用次数。 +把 ReactElement 渲染为它原始的 HTML 。这应该仅在服务器端使用。React 将会返回一个 HTML 字符串。你可以用这种方法在服务器端生成 HTML，然后在初始请求下传这些标记，以获得更快的页面加载速度及允许搜索引擎抓取页面（便于 SEO）。 -#### React.Children.only +如果在一个在已经有了这种服务器预渲染标记的节点上面调用 `ReactDOM.render()`，React 将会维护该节点，仅绑定事件处理器，让你有一个非常高效的初次加载体验。 + + +### ReactDOMServer.renderToStaticMarkup ```javascript -object React.Children.only(object children) +string renderToStaticMarkup(ReactElement element) ``` -返回 `children` 中仅有的子级。否则抛出异常。 +类似于 `renderToString` ，除了不创建额外的 DOM 属性，比如 `data-react-id`，这仅在 React 内部使用的属性。如果你想用 React 做一个简单的静态页面生成器，这是很有用的，因为去除额外的属性能够节省很多字节。 diff --git a/docs/docs/ref-02-component-api.zh-CN.md b/docs/docs/ref-02-component-api.zh-CN.md index b718526ad5f6c..3186f22e93d45 100644 --- a/docs/docs/ref-02-component-api.zh-CN.md +++ b/docs/docs/ref-02-component-api.zh-CN.md @@ -8,13 +8,13 @@ next: component-specs-zh-CN.html ## React.Component -当渲染时，React 组件的实例在 React 内部被创建。这些实例在随后的渲染中被重复使用，并可以在组件方法中通过 `this` 访问。唯一的在 React 之外获取 React 组件实例句柄的方法是保存 `React.render` 的返回值。在其它组件内，你可以使用 [refs](/react/docs/more-about-refs-zh-CN.html) 得到相同的结果。 +当渲染时，React 组件的实例在 React 内部被创建。这些实例在随后的渲染中被重复使用，并可以在组件方法中通过 `this` 访问。唯一的在 React 之外获取 React 组件实例句柄的方法是保存 `ReactDOM.render` 的返回值。在其它组件内，你可以使用 [refs](/react/docs/more-about-refs-zh-CN.html) 得到相同的结果。 ### setState ```javascript -setState( +void setState( function|object nextState, [function callback] ) @@ -29,7 +29,7 @@ setState( setState({mykey: 'my new value'}); ``` -也可以以 `function(state, props)` 传递一个函数。当你想要把一个在设置任何值之前参考前一次 state+props 的值的原子更新放在队列中 这会有很用。例如，假如我们想在 state 增加一个值。 +也可以以 `function(state, props)` 传递一个函数。当你想要把一个在设置任何值之前参考前一次 state+props 的值的原子更新放在队列中 这会有很用。例如，假如我们想在 state 增加一个值: ```javascript setState(function(previousState, currentProps) { @@ -53,7 +53,7 @@ setState(function(previousState, currentProps) { ### replaceState ```javascript -replaceState( +void replaceState( object nextState, [function callback] ) @@ -69,7 +69,7 @@ replaceState( ### forceUpdate ```javascript -forceUpdate( +void forceUpdate( [function callback] ) ``` @@ -91,7 +91,7 @@ DOMElement getDOMNode() > Note: > -> getDOMNode 被废弃了，已经被 [React.findDOMNode()] 替换(/react/docs/top-level-api-zh-CN.html#react.finddomnode). +> getDOMNode 被废弃了，已经被 [ReactDOM.findDOMNode()] 替换(/react/docs/top-level-api-zh-CN.html#reactdom.finddomnode). > > 这个方法在从 `React.Component` 扩展的 ES6 `class` 组件里不可用。它也许会在未来的 React 版本中被完全移除。 @@ -99,41 +99,41 @@ DOMElement getDOMNode() ### isMounted ```javascript -bool isMounted() +boolean isMounted() ``` 如果组件渲染到了 DOM 中，`isMounted()` 返回 true，否则返回 `false`。可以使用该方法来控制对 `setState()` 和 `forceUpdate()` 的异步调用。 > 注意: > -> 这个方法在从 `React.Component` 扩展的 ES6 `class` 组件里不可用。它也许会在未来的 React 版本中被完全移除。 +> 这个方法在从 `React.Component` 扩展的 ES6 `class` 组件里不可用。它也许会在未来的 React 版本中被完全移除,所以你也要移除它 [start migrating away from isMounted() now](/react/blog/2015/12/16/ismounted-antipattern.html) ### setProps ```javascript -setProps( +void setProps( object nextProps, [function callback] ) ``` -当和一个外部的 JavaScript 应用整合的时候，你也许会想用 `React.render()` 给 React 组件标示一个改变。 +当和一个外部的 JavaScript 应用整合的时候，你也许会想用 `ReactDOM.render()` 给 React 组件标示一个改变。 在根组件上调用 `setProps()` 会改变他的属性并触发一次重绘。另外，你可以提供一个可选的回调函数，一旦 `setProps` 完成并且组件被重绘它就执行。 > 注意: > -> 如果可能，上述的在同一个节点上再次调用 `React.render()` 的方法是优先替代的。它往往使更新更容易理解。（两种方法并没有显著的性能区别。） +> 这个方法被弃用了并会很快移除.这个方法在从 `React.Component` 扩展的 ES6 `class` 组件里不可用. 取代调用 `setProps`,试着以新的 props 再次调用 `ReactDOM.render()`. 更多的注意事项,见我们的[blog post about using the Top Level API](/react/blog/2015/10/01/react-render-and-top-level-api.html) > -> 这个方法仅能在根组件上被调用。也就是说，它仅在直接传给 `React.render()` 的组件上可用，在它的子级上不可用。如果你倾向于在子组件上使用 `setProps()`，不要利用响应式更新，而是当子组件在 `render()` 中创建的时候传入新的 prop 到子组件中。 +> 如果可能，上述的在同一个节点上再次调用 `ReactDOM.render()` 的方法是优先替代的。它往往使更新更容易理解。（两种方法并没有显著的性能区别。） > -> 这个方法在从 `React.Component` 扩展的 ES6 `class` 组件里不可用。它也许会在未来的 React 版本中被完全移除。 +> 这个方法仅能在根组件上被调用。也就是说，它仅在直接传给 `ReactDOM.render()` 的组件上可用，在它的子级上不可用。如果你倾向于在子组件上使用 `setProps()`，不要利用响应式更新，而是当子组件在 `render()` 中创建的时候传入新的 prop 到子组件中。 ### replaceProps ```javascript -replaceProps( +void replaceProps( object nextProps, [function callback] ) @@ -143,4 +143,4 @@ replaceProps( > 注意: > -> 这个方法在从 `React.Component` 扩展的 ES6 `class` 组件里不可用。它也许会在未来的 React 版本中被完全移除。 +> 这个方法被弃用了并会很快移除.这个方法在从 `React.Component` 扩展的 ES6 `class` 组件里不可用. 取代调用 `replaceProps`,试着以新的 props 再次调用 `ReactDOM.render()`. 更多的注意事项,见我们的[blog post about using the Top Level API](/react/blog/2015/10/01/react-render-and-top-level-api.html) diff --git a/docs/docs/ref-03-component-specs.zh-CN.md b/docs/docs/ref-03-component-specs.zh-CN.md new file mode 100644 index 0000000000000..95d6cb19a673a --- /dev/null +++ b/docs/docs/ref-03-component-specs.zh-CN.md @@ -0,0 +1,217 @@ +--- +id: component-specs-zh-CN +title: 组件的规范和生命周期 +permalink: component-specs-zh-CN.html +prev: component-api-zh-CN.html +next: tags-and-attributes-zh-CN.html +--- + +## 组件规范(Specifications) + +当调用 `React.createClass()` 创建一个组件类时,你应该提供一个包含有 `render` 方法以及可选的其他生命周期方法的 规范(Specifications)对象. + +> 注意: +> +> 同样可以使用单纯的 JavaScript 类作为组件类. 这些类可以实现大多数相同的方法,虽然有一些不同.更多关于不同的信息,请阅读我们关于[ES6 classes](/react/docs/reusable-components.html#es6-classes)的文档. + +### render + +```javascript +ReactElement render() +``` + + `render()` 是必须的 + + 当被调用时,它应该检查 `this.props` 和 `this.state` 并返回单个子元素.这个子元素即可以是一个 对原生DOM的虚拟表达(比如 `
` 或 `React.DOM.div()`)也可以是其他你自定义的复合组件. + + 你也可以返回 `null` 或 `false` 来指示你不想要任何东西被渲染.幕后,React 渲染一个 `