React 参考文档(基于v16.2.0) 01 : 顶层API

React 顶层API （Top-Level API）

React 是整个React库的入口点，你可以将它想象成最顶层的命名空间。当使用<script>标签加载React时，这些顶层API就会在React命名空间下可用了。

如果你在基于npm使用ES6，可以这么引入React顶层API :import React from 'react'

如果你在基于npm使用ES5，就要这么引入React顶层API : var React = require('react')

概述 (Overview)

组件 (Components)

React组件帮你把UI分成独立可重用的片段(piece),你可以把这些片段隔离地来考虑其应用，因为它们的关注点是分离的。

定义React组件的话，可以通过继承以下两个类之一 ：

• React.Component
• React.PureComponent

如果你用的不是ES6的类，那就需要使用create-react-class模块，这里有更多的信息供你参考 : Using React without ES6

创建React组件

我们推荐使用JSX描述你的UI应该是个什么样子。JSX元素其实是调用React.createElement()的语法糖。如果使用JSX的话，你就不用直接调用如下方法了 :

• createElement()
• createFactory()

如果使用React时候你不打算用JSX，到这里看看 Using React without JSX

元素变形 (Transforming Elements)

React 提供了几个用于操作元素的API :

• cloneElement()
• isValidElement()
• React.Children

片段 (Fragments)

React 也提供了一个组件，用于不使用包装器(wrapper)处理多个元素 :

• React.Fragment

参考文档 (Reference)

React.Component

React.Component是所有React组件的基类，在使用ES6定义一个React组件是，它是这么被使用的:

class Greeting extends React.Component {
  render() {
    return <h1>Hello, {this.props.name}</h1>;
  }
}

在React.Component API参考文档中有该类的方法和属性的一个列表。

React.PureComponent

React.PureComponent类似于React.Component。区别在于,React.Component没有实现方法 shouldComponentUpdate(),而React.PureComponent基于一个浅层属性/状态比较实现了它(with a shallow prop and state comparison)。

属性/状态（props/state）一样的前提下，如果你的React组件的**render()**函数渲染出一样的结果，某些情况下你可以使用 React.PureComponent来提升性能。

注意
React.component的方法shouldComponentUpdate()仅仅浅层比较对象。如果包含了复杂数据结构，这种做法可能导致错误。所以仅在当你打算使用简单属性/状态时扩展PureComponent,或者在深层数据结构变化时使用forceUpdate()。或者，考虑使用不变对象来辅助嵌套数据的快速比较。
 
Furthermore, React.PureComponent’s shouldComponentUpdate() skips prop updates for the whole component subtree. Make sure all the children components are also “pure”.
 
另外，React.component的方法shouldComponentUpdate()跳过了整个组件子树的属性更新。所以请确保所有孩子组件也是"纯净的"(pure)。

createElement()

React.createElement(
  type,
  [props],
  [...children]
)

创建并返回指定类型为type的一个 React element.类型参数type可以是一个HTML标签名称字符串(比如 div或者span),一个 React 组件类型(类或者函数),或者一个React 片段类型。

使用JSX写的代码会被转换成React.createElement()。如果你在使用JSX,通常情况下你不需要直接调用React.createElement()。

cloneElement()

React.cloneElement(
  element,
  [props],
  [...children]
)

使用参数element作为起始点克隆并返回一个新的React元素。结果元素会通过属性浅层合并的方式拥有原始元素的属性。新的孩子节点会替换已经存在的孩子节点。原始节点的key和ref在新的节点中会被保留。

React.cloneElement()基于等价于以下写法:

<element.type {...element.props} {...props}>{children}</element.type>

然而，他还保持了ref属性。This means that if you get a child with a ref on it, you won’t accidentally steal it from your ancestor. You will get the same ref attached to your new element. （译注 : 这句话没太理解，所以这里不做翻译）

该API方法是作为如下被废弃的方法的替代被引入的 :
React.addons.cloneWithProps()

createFactory()

React.createFactory(type)

返回一个用于产生特定类型type的React元素的函数。跟[React.createElement()]中的类型参数type类似，它可能是一个HTML标签名称字符串(比如 div或者span),一个 React 组件类型(类或者函数),或者一个React 片段类型。

如果你在使用JSX的话，通常情况下你不会直接调用React.createFactory()。

isValidElement()

React.isValidElement(object)

验证一个对象是否是一个React元素。返回 true 或者 false。

React.Children

React.Children用于提供处理this.props.children不透明数据结构的工具方法。

React.Children.map

React.Children.map(children, function[(thisArg)])

对children中的每个直接元素调用指定函数function,this指针会作为参数thisArg传入进去。如果children是一个keyed fragment或者数组(arrya),它会被遍历访问。函数参数 function永远不会被传给容器对象。该方法正常情况下返回数组(array)，如果children是null或者undefined,返回的结果会相应的是null或者undefined,而不是一个数组(array)。

React.Children.forEach

React.Children.forEach(children, function[(thisArg)])

跟 React.Children.map类似，但是不返回数组。

React.Children.count

React.Children.count(children)

返回children中的元素总数，和React.Children.map/forEach中回调函数将会被调用的次数相等。

React.Children.only

React.Children.only(children)

验证children只有一个元素(一个React element)并返回它，否则该方法抛出一个错误error。

React.Children.toArray

React.Children.toArray(children)

将不透明数据结构对象children转换成一个数组。当你需要在render方法中操作children集合时，尤其是你想重新排序或者切分(slice)this.props.children时然后往下传时，该方法很有用。

React.Fragment

React.Fragment组件可以让你在一个**render()**方法中不用创建一个额外的DOM节点就可以返回多个元素(译注：通常情况下render()方法总是创建并返回唯一一个DOM节点)：

render() {
  return (
    <React.Fragment>
      Some text.
      <h2>A heading</h2>
    </React.Fragment>
  );
}

你也可以利用快捷语法<></>来使用React.Fragment。
更多的信息，请参考 React v16.2.0: Improved Support for Fragments。