React Top-Level API


TOC

```
React
	React.Component
	React.createClass
	React.createElement
	React.cloneElement
	React.createFactory
	React.isValidElement
	React.DOM
	React.PropTypes
	React.Children
		React.Children.map
		React.Children.forEach
		React.Children.count
		React.Children.only
		React.Children.toArray
ReactDOM
	ReactDOM.render
	ReactDOM.unmountComponentAtNode
	ReactDOM.findDOMNode
ReactDOMServer
	ReactDOMServer.renderToString
	ReactDOMServer.renderToStaticMarkup
```
## React

React 作为 react 库的一个入口,它是一个全局的变量. 如果使用 CommonJS 的语法,可以直接 require 它.

### React.Component

```javascript
class Component
```

当使用es6的语法来定义类的时候,它是一个 react 组件的基类. [可以查看这里 重用组件](https://facebook.github.io/react/docs/reusable-components.html#es6-classes)来查看如何通过 es6的类来使用. 更多关于组件的api, [看这里](https://facebook.github.io/react/docs/component-api.html)

### React.createClass

```javascript
ReactClass createClass(object specification)
```

通过特定条件来创建一个组件类.一个组件是了一个`render` 方法,然后返回一个单个的结果. 这个结果可有很深的子集. 使用它不需要像一般的类那样你需要` new` 他们,他们已经通过封装直接就有能用.
可以[通过这里查看组件的生命周期和定义](https://facebook.github.io/react/docs/component-specs.html)[汉化](http://qiita.com/xiangzhuyuan/items/abb5ca4833069c5295c2)

### React.createElement

```javascript
ReactElement createElement(
  string/ReactClass type,
  [object props],
  [children ...]
)
```

创建并返回一个`React Element`,参数可以是普通的 `html tag 字符`或者上面通过` React.createClass` 创建的类.

### React.cloneElement

```
ReactElement cloneElement(
  ReactElement element,
  [object props],
  [children ...]
)
```
克隆一个 ReactElement

### React.createFactory

```javascript
factoryFunction createFactory(
  string/ReactClass type
)
```

返回一个工程方法, 用来创建 ReactElement通过给定的类型, 参数和` createElement` 一样,可以是 html 的 tag string 名或者是 React 的 class.

### React.isValidElement

```javascript
boolean isValidElement(* object)
```


验证对象是否是 ReactElement.


### React.DOM

`React.DOM`给 DOM 组件 提供了一个方便的封装给 `React.createElement`他们只适合在不使用 JSX 的情况下使用, 如 `React.DOM.div(null, 'Hello World!')`


### React.PropTypes

`React.PropTypes` 用来验证组件给定参数的合法性 [Reusable Components](https://facebook.github.io/react/docs/reusable-components.html).


### React.Children

`React.Children`提供了一系列的方法用来处理` this.props.children`.

#### React.Children.map

```javascript
array React.Children.map(object children, function fn [, object thisArg])
```

如果当前这个 children 包含子节点,立即执行这个` fn` 并且把 this 指向` thisArg`. 如果 children 是一个 keyed fragment, 或者 array. 那么 fb 将不会被执行. 如果 children 是空的将直接返回 null 或者未定义.


#### React.Children.forEach

```javascript
React.Children.forEach(object children, function fn [, object thisArg])
```

类型map 方法但是不返回数组

#### React.Children.count

```javascript
number React.Children.count(object children)
```

返回子集的数量,相当于调用了多少次 fn 的回调

#### React.Children.only

```javascript
object React.Children.only(object children)
```
只取子集

#### React.Children.toArray

```javascript
array React.Children.toArray(object children)
```

将子集作为 array 返回

> Note:
> 
> `React.Children.toArray()` changes keys to preserve the semantics of nested arrays when flattening lists of children. That is, `toArray` prefixes each key in the returned array so that each element's key is scoped to the input array containing it.

## ReactDOM

react-dom 包提供了针对 DOM 的一方法,他们会在 app 的最顶层使用.

### ReactDOM.render

```javascript
render(
  ReactElement element,
  DOMElement container,
  [function callback]
)
```

把 ReactElement 渲染成一个真实的 DOM 然后装到给定的容器里. 如果已经把这个 element 装到容器那就更新它. 如果提供回调函数,将在装载或者更新之后触发.


> Note:
>
> `ReactDOM.render()` controls the contents of the container node you pass in. Any existing DOM elements
> inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient
> updates.
>
> `ReactDOM.render()` does not modify the container node (only modifies the children of the container). In
> the future, it may be possible to insert a component to an existing DOM node without overwriting
> the existing children.
>
> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
> and should be avoided because future versions of React may render components asynchronously in some cases. If you need a reference to the root `ReactComponent` instance, the preferred solution is to attach a
> [callback ref](/react/docs/more-about-refs.html#the-ref-callback-attribute) to the root element.


### ReactDOM.unmountComponentAtNode

```javascript
boolean unmountComponentAtNode(DOMElement container)
```
卸载 DOM

### ReactDOM.findDOMNode

```javascript
DOMElement findDOMNode(ReactComponent component)
```

如果当前element 已经装载,他将返回一个原始的 DOM 元素. 这个方法有助于读取 DOM 以外的值或者拿到 DOM 的值.更多的时候你可以通过追加一个引用给 DOM 的节点而不需要他.

> Note:
>
> `findDOMNode()` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction.
>
> `findDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.
>
> `findDOMNode()` cannot be used on stateless components.

## ReactDOMServer

The `react-dom/server` package allows you to render your components on the server.

### ReactDOMServer.renderToString

```javascript
string renderToString(ReactElement element)
```
可以在服务器端拿到渲染好的 html 直接传递给浏览器.


### ReactDOMServer.renderToStaticMarkup

```javascript
string renderToStaticMarkup(ReactElement element)
```
和 renderToString 类型,区别就是它不会处理 react 自己的标记,简单的返回 html. 可以作为一个简单的模板系统使用.