二十一、React顶级API

全局变量React是React库的入口。如果你通过一个script标签使用的React，那么它的顶级API都会在全局环境下一个名称为React的变量上。如果你是通过npm使用的ES6，你可以这样写：import React From 'react';。你是通过npm使用的ES5，你可以这样写VAR React = require('react');。

总览

components

React组件可以让你将UI部分独立出来，成为可重用的部分。从而单独考虑分离出来的每一部分功能。可以通过React.COMponent或者React.PureComponent来创建React组件。

• React.Component

• React.PureComponent

如果你不是用ES6的class功能,你可以使用以下代替:

• React.createClass()

创建一个React元素

我们推荐使用JSX来定义UI。每个JSX元素都是React.createElement(component, PRops, children)的语法糖。使用JSX就意味着你不需要直接调用下面的方法:

• React.createElement()

• React.createFactory()

处理React元素

React同时还为处理元素提供了一些其他APIs:

• React.cloneElement()

• React.isValidElement()

• React.Children

使用PropTyPEs进行类型检测

你可以使用React.PropTypes为一个组件上的props进行类型检测。

• React.PropTypes

• React.PropTypes.array

• React.PropTypes.bool

• React.PropType.func

• React.PropTypes.number

• React.PropTypes.object

• React.PropTypes.string

• React.PropTypes.symbol

• React.PropTypes.node

• React.PropTypes.element

• React.PropTypes.instanceOf()

• React.PropType.oneof()

• React.PropType.oneOfType()

• React.PropType.arrayOf()

• React.PropType.objectOf()

• React.PropTypes.Shape()

• React.PropTypes.any

以上的验查器默认都是可选的。你可以使用isRequired来标记一个必填属性。如果用户没有根据指定类型传入props或者压根没有传入props的话则会给出一个错误提示。

插件

如果你使用了react-wITh-addons.js,那么React组件可以通过变量React.addons使用。

• React.addons

使用方法

React.Component

React.Component是所有React组件的基类,当使用ES6 classes定义一个组件的用法如下:

class Greeting extends React.Component {
    render() {
        return <h1>Hello, {this.props.name}</h1>
    }
}
ReactDOM.render(
    <Greeting name={"zhangyatao"}/>,
    document.getElementById('root)
)

React.PureComponet

React.PureComponent表面上很像React.Component,但是它实现了shouldComponentUpdate()对props和state的进行浅比较。

如果你React组件的render()方法每次使用相同的props和state并且渲染出相同的结果。这种情况你可以使用React.PureComponent来提升性能。

提示

React.PureComponent的shouldComponentUpdate()仅会对对象进行浅比较,如果对象包含复杂的数据结构,对于深层次的差异有可能会产生false-negatives(假阴性,相当于医院中的错诊)。

React.createClass()

React.createClass(specification)

如果你还没有使用ES6,你可以使用React.createClass()来创建一个组件类。

var Greeting = React.createClass({
    setInitialState: function() {
        return {value: 0};
    },
    render: function() {
        return <h1>Hello, {this.props.name}</h1>;
    }
})

React.createElement()

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

通过传入的类型和属性以及子元素来创建并返回一个新的React元素。其中type参数可以传入一个htML标签名称字符串(例如'div'或者'span')，或者传入一个React组件(一个类组件或功能性组件)。

React.DOM提供了DOM组件可以比较便捷地通过React.createElement()包装的方法。例如，React.DOM.a(...)就是React.createElement('a',...)的便捷包装。这种方法可以是历史版本遗留产物，所以我们推荐你是用JSX或者使用React.createElement()来直接代替。

使用JSX写的代码会被转换为React.createElement()。如果你使用了JSX的话，通常不需要直接调用React.createElement()。

React.cloneElement()

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

传入一个React元素进行克隆并返回一个新的React元素。

React.createFactory()

React.createFactory(type)

返回一个生成给定类型的React元素的函数。就像React.createElement()，其中type参数可以传入一个html标签名称字符串(例如'div'或者'span')，或者传入一个React组件类型(一个类型组件或功能性组件)。

这种方法可以是一个历史版本遗留产物，我们推荐你是用JSX或者使用React.createElement()来直接代替。

使用JSX写的代码会被转换为React.createElement()。如果你使用了JSX的话，通常不需要直接调用React.createElement()。

React.isValidElement()

React.isValidElement(Object)

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

React.Children

React.children提供了处理this.props.children中那些不透明的数据结构的一些工具函数。

React.Children.map

React.Children.map(children, function[(thisarg))

React.Children.foreach

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

和React.Children.map相同，只不过不会返回一个数组。

React.Children.count

React.Children.count(children)

返回children中的组件总数。

React.Children.only

React.Children.only(children)

然会children中的只出现一次的子元素。否则抛出。

React.Children.toArray

React.Children.toArray(children)

将子元素中的不透明数据结构作为一个一维数组返回。如果你想在render方法中操作children集合，特别是如果你想在传递它之前重新排序或切割this.props.children，这歌方法将非常有用。

React.PropTypes

React.PropTypes是一系列类型验证器的集合，可以与组件的propTypes对象一起使用，以验证传递到组件的props。

React.PropTypes.array

React.PropTypes.array

验证prop是一个数组类型。

React.PropTypes.bool

React.PropTypes.bool

验证prop是一个布尔值。

React.PropTypes.func

React.PropTypes.func

验证prop是一个函数。

React.PropTypes.number

React.PropTypes.number

验证prop是一个数字。

React.PropTypes.object

React.PropTypes.object

验证prop是一个对象。

React.PropTypes.string

React.PropTypes.string

验证prop是一个字符串。

React.PropTypes.symbol

React.PropTypes.symbol

验证prop是一个symbol。

React.PropTypes.node

React.PropTypes.node

验证prop是一个可以渲染的东西：数字，字符串，元素 或者包含这些类型的数组（或片段）。

React.PropTypes.element

React.PropTypes.element

验证prop是一个React元素。

React.PropTypes.instanceOf()

React.PropTypes.instanceOf(class)

验证prop是否是class的实例，使用Javascript中的instaceof操作符。

React.PropTypes.oneOf()

React.PropTypes.oneOf(arrayOfValues)

通过将其视为枚举来验证prop是否受限于特定值。

MyComponent.propTypes = {
    optionalEnum: React.PropTypes.oneOf(['News', 'Photos']);
}

React.PropTypes.oneOfType()

React.PropTypes.oneOfType()

验证prop是可以是多种类型之一的对象。

MyComponent.propTypes = {
    optionalUnion: React.PropTypes.oneOfType([
        React.PropTypes.string,
        React.PropTypes.number,
        React.PropTypes.instanceOf(Message)
    ]),
}

React.PropTypes.arrayOf()

React.PropTypes.arrayOf(propType)

验证porp是一个特定类型的数组。

MyComponent.propTypes = {
    optionalArrayOf: React.PropTypes.arrayOf(React.PropTypes.number),
}

React.PropTypes.objectOf()

React.PropTypes.objectOf(propType)

验证prop是具有某个类型的属性值的对象。

MyComponent.propTypes = {
    optionalObjectOf: React.PropTypes.objectOf(React.PropTypes.number),
}

React.PropTypes.shape()

React.PropTypes.shape(object)

验证prop是采取特定形状的对象。

MyComponent.propTypes = {
    optionalObjectWithShape: React.PropTypes.shape({
        color: React.PropTypes.string,
        fontSize: React.PropTypes.number
    }),
}

React.PropTypes.any

React.PropTypes.any

验证prop具有任何数据类型的值。 通常后面是isRequired。

MyComponent.propTypes = {
    requiredAny: React.PropTypes.any.isRequired,
}

isRequired

propTypes.isRequired

您可以使用isRequired链接上述任何验证器，以确保在未提供prop的情况下显示警告。

MyComponent.propTypes = {
    requireDFunc: React.PropTypes.func.isRequired,
}

React.addons

React.addons

React.addons导出一系列附加组件，只有在使用react-with-addons.js时才可用。